Naslagwerk voor de Email Verifier REST API

De Email Verifier API is beschikbaar onder /api/v1. Gebruik de TrekMail-host waarop je account inlogt. In de voorbeelden hieronder wordt https://YOUR-TREKMAIL-HOST als tijdelijke aanduiding gebruikt.

Authenticatie en scopes

Geef een API-token door in de header Authorization:

Authorization: Bearer YOUR_API_TOKEN

Schakel scopes in wanneer je het token maakt:

Geef een client beide scopes als die werk moet indienen en daarna het resultaat moet lezen of downloaden.

Host en aanvraagindeling

Alle voorbeelden gebruiken JSON-aanvraagbody's en een Bearer-token. De bestandsupload in het dashboard staat los van de API: POST /verify/bulk accepteert een JSON-array emails, geen multipart-bestand. Gebruik exact de host die bij het account en token hoort. Ga er niet van uit dat een token of saldo van de ene merkhost op een andere host werkt.

Stuur Content-Type: application/json mee voor aanvragen naar POST /verify en POST /verify/bulk. Bewaar het token en de idempotentiewaarde buiten client-side code.

Idempotentie

POST /api/v1/verify/bulk en DELETE /api/v1/verify/bulk/{jobId} vereisen de header Idempotency-Key. Genereer voor elke bedoelde bewerking een nieuwe waarde en gebruik die alleen opnieuw wanneer je dezelfde bewerking opnieuw probeert.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

Voor een losse verificatie en het annuleren van een taak is deze header niet vereist. Een bulkaanvraag wordt ook beschermd door detectie van dezelfde genormaliseerde lijst en modus binnen 24 uur, maar een idempotentiesleutel blijft het juiste mechanisme voor nieuwe pogingen.

Omgaan met een onzekere netwerkuitkomst

Als je toepassing de reactie op een bulkaanvraag kwijtraakt, genereer dan geen nieuwe idempotentiesleutel en dien niet nog een lijst in. Herhaal exact dezelfde aanvraag met dezelfde sleutel. Bewaar de sleutel bij de identificatie van de bronlijst totdat TrekMail een taak-ID teruggeeft. Zo blijft de nieuwe poging gekoppeld aan de oorspronkelijke bewerking en ontstaat er geen vermijdbare tweede afschrijving.

Overzicht van endpoints

Plaats /api/v1 voor elk pad in deze tabel.

Creditsaldo opvragen

GET /api/v1/verify/credits

Op de standaard TrekMail-host bevat de reactie de inbegrepen hoeveelheid van het abonnement en het gekochte saldo:

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

Op een White Label-host zijn alleen gekochte credits beschikbaar voor het merkproduct. De reactie bevat daarom purchased_balance en total_available.

Voorbeeldaanvraag:

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/credits \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Vraag het saldo direct voor een grote indiening op. Een saldoreactie is een momentopname. Een toepassing die meerdere taken indient, moet daarom het in elke bulkreactie afgeschreven bedrag vastleggen in plaats van dit later op basis van een verouderd getal te berekenen.

Saldovelden

Saldoreacties van White Label bevatten bewust minder velden, omdat het merkproduct alleen gekochte credits gebruikt.

Eén adres verifiëren

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

De reactie bevat email, status, trust_score, checks, provider, risk_factors en credits_remaining. Op de standaardhost bevat credits_remaining de waarden monthly en purchased. De gedetailleerde structuur van checks kan verschillen per modus en op basis van wat de ontvangende provider beschikbaar stelt.

Quick kost 1 credit. Deep kost normaal 2 credits, terwijl providerspecifieke uitzonderingen tegen 1 credit worden berekend. Als de verificatie na de afschrijving niet kan worden uitgevoerd, stort de aanvraag voor één adres die afschrijving terug en geeft deze een reactie voor tijdelijke onbeschikbaarheid.

Voorbeeldaanvraag:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

Gebruik status, trust_score, provider en risk_factors op het hoogste niveau als het normale contract voor je toepassing. checks bevat nuttig ondersteunend bewijs, maar afzonderlijke sleutels kunnen verschillen wanneer een eerdere controle wordt overgeslagen of niet beschikbaar is, of wanneer Deep aanvullende informatie verkrijgt.

Een afzonderlijk resultaat interpreteren

Laat een toepassing een geaccepteerde externe reactie niet behandelen als controle van eigendom of toestemming. Houd beslissingen over abonnementen, afmeldingen en contactvoorkeuren gescheiden.

Een bulktaak maken

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

Duplicaten worden voor de prijsberekening genormaliseerd. Een nieuwe taak die met succes is gemaakt, geeft 201 terug met:

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe en skip verklaren de prijsberekening van Deep. deep_savings is het verschil met het volledige Deep-tarief voor elk ingediend adres. Bij een dubbele lijst worden de bestaande job_id en status teruggegeven in plaats van een nieuwe taak te starten.

Voorbeeldaanvraag:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -d '{"name":"September contacts","mode":"deep","emails":["first@example.com","second@example.net"]}'

De API controleert de ingediende waarden op geldige e-mailsyntaxis voordat de taak wordt toegelaten. Als elk item wordt afgewezen, geeft de API 422 terug en wordt er geen taak gemaakt. Als sommige items worden afgewezen, vermeldt de geslaagde reactie rejected_count en maximaal vijf waarden in rejected_sample. Vertrouw niet op die kleine steekproef als volledig rapport voor gegevensopschoning. Bewaar het validatieresultaat van de bron in je eigen importprogramma.

Checklist voor bulkindiening

1. Lees en normaliseer de bron in je eigen toepassing.
2. Beperk de aanvraag tot 50,000 ingediende items.
3. Genereer en bewaar vóór de aanvraag een idempotentiesleutel.
4. Geef de taak een naam die een operator later gemakkelijk herkent.
5. Bewaar job_id, credits_charged en de prijsopbouw die TrekMail teruggeeft.
6. Poll de opgeslagen job_id; leid voltooiing niet af uit de oorspronkelijke HTTP-aanvraag.

Een taak opvragen

GET /api/v1/verify/bulk/{jobId}

De basisreactie bevat job_id, name, status, total, processed, progress, summary, created_at en completed_at.

Wanneer resultaten beschikbaar zijn voor een voltooide, gedeeltelijke of mislukte taak, bevat de reactie ook:

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

Optionele queryparameters:

Een geannuleerde taak met verwerkte rijen kan worden gedownload, maar gebruik het downloadendpoint voor de export.

Taakstatussen lezen zonder te gissen

Een API-client moet pollen met oplopende wachttijden. Dien geen nieuwe bulktaak in enkel omdat de bestaande taak nog wacht of omdat een netwerkaanvraag lokaal een time-out heeft bereikt.

Voorbeeld van een statusreactie

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

summary kan groeien terwijl het werk wordt uitgevoerd. Gebruik processed en total om de voortgang weer te geven, in plaats van alleen de categorieën op te tellen die je toepassing nu herkent.

Een taak downloaden

GET /api/v1/verify/bulk/{jobId}/download

De download is beschikbaar voor voltooide, gedeeltelijke of geannuleerde taken met verwerkte rijen. Er wordt een CSV gestreamd met de kolommen Email, Status, Trust Score, Provider en Risk Factors.

Voorbeeld:

curl -o september-results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe_risky" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Sla de download binnen de bewaartermijn van 15 dagen op. De CSV is een export voor je eigen proces en verandert niets aan toestemming, abonnementen of contactrecords in een ander systeem.

Het downloadendpoint geeft een conflict terug zolang er geen verwerkte export beschikbaar is. Controleer eerst de taakstatus. Een geslaagde aanvraag streamt de CSV in plaats van een JSON-wrapper terug te geven, dus verwerk deze als bestandsreactie in je HTTP-client.

Taken weergeven

GET /api/v1/verify/bulk

Gebruik page, per_page en optioneel status. per_page is standaard 20 en accepteert 1 tot 100. Taakstatussen zijn pending, processing, completed, partial, cancelled en failed.

De reactie bevat een array jobs en een object pagination. Elke taakrecord heeft een ID, naam, status, totaal, verwerkt aantal, voortgang en tijdstempels.

Voorbeeld:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Gebruik het lijstendpoint wanneer je worker opnieuw start of wanneer je taak-ID's moet vergelijken. Behandel een taaknaam niet als unieke identificatie; bewaar de numerieke job_id die wordt teruggegeven.

Structuur van de taaklijstreactie

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

Gebruik de queryparameter status wanneer een beheerpagina alleen actief of juist voltooid werk nodig heeft. Paginering is belangrijk voor accounts die veel lijsten verifiëren; neem niet aan dat één reactie de volledige geschiedenis bevat.

Een taak annuleren

POST /api/v1/verify/bulk/{jobId}/cancel

Annuleer alleen wachtend of actief werk. Een geslaagde reactie is:

{"status":"cancelled","credits_refunded":40}

De terugbetaling geldt voor onverwerkt werk. Als de taak een eindstatus bereikt voordat de annulering aankomt, geeft de API een conflict terug zonder het resultaat te veranderen.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Annulering verwijdert de taak niet. Download zo nodig de verwerkte rijen of verwijder het voltooide record daarna.

Een taak verwijderen

DELETE /api/v1/verify/bulk/{jobId}

Annuleer een actieve taak eerst. Verwijdering wist de taak en resultaten definitief nadat TrekMail de klaargezette bronlijst veilig heeft verwijderd. Een geslaagde reactie is:

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

Deze bewerking is definitief voor het verificatierecord. CSV-bestanden die je toepassing al heeft gedownload, worden niet ingetrokken. Pas dus je eigen bewaarbeleid toe op die kopieën.

Volgorde voor verwijdering

1. Lees de taakstatus.
2. Annuleer de taak als deze wacht of wordt verwerkt.
3. Bewaar elke verwerkte export die je moet behouden.
4. Verwijder de niet-actieve verificatietaak met een idempotentiesleutel.
5. Verwijder kopieën in je eigen systeem volgens de privacy- en bewaarregels.

Fouten en nieuwe pogingen

Losse verificatie heeft een routelimiet van 60 aanvragen per minuut en bulkindiening een routelimiet van 10 aanvragen per minuut. Bouw nieuwe pogingen met oplopende wachttijden, behoud dezelfde idempotentiesleutel voor een nieuwe bulkpoging en probeer een aanvraag niet blind opnieuw na een onbekende netwerkuitkomst.

Een veilig patroon voor nieuwe pogingen

1. Genereer en bewaar één idempotentiesleutel voordat je een bulktaak indient.
2. Dien de aanvraag in met die sleutel.
3. Als de reactie verloren gaat, herhaal je exact dezelfde aanvraag met dezelfde sleutel.
4. Bewaar de teruggegeven job_id en maak geen nieuwe indieningen meer voor die bronlijst.
5. Poll de taak totdat deze een eindstatus bereikt en download of verwerk daarna het resultaat.

Bij een losse verificatie betekent een tijdelijke 503 dat de service de controle niet kon voltooien. Probeer het later opnieuw met een normale oplopende wachttijd. Zet die reactie in je eigen database niet om in het resultaat Invalid.

Contactgegevens veilig houden

E-maillijsten zijn in veel situaties persoonsgegevens. Stuur alleen gegevens die nodig zijn voor verificatie, beperk toegang tot het token tot het systeem dat de taak uitvoert en vermijd volledige adresarrays in toepassingslogs. Als logregistratie nodig is, bewaar dan taak-ID, aantal, timing en resultaat op hoofdlijnen in plaats van de volledige lijst.

TrekMail bewaart resultaten 15 dagen. Plan veilige opslag van exports of een verwijderingsproces voordat je lijsten met grote volumes integreert.

Verificatiesignalen bewijzen geen eigendom, toestemming of toekomstige bezorging. Blijf toestemming en onderdrukking in je toepassing beheren, ook wanneer een adres Safe scoort.