Snelstart voor de TrekMail Email Verifier API

Gebruik de API wanneer verificatie onderdeel moet zijn van je product of importworkflow. Maak een token met verify:read en verify:write, houd het geheim en roep dezelfde host aan waarmee je je aanmeldt. Vervang in de voorbeelden https://YOUR-TREKMAIL-HOST en YOUR_API_TOKEN.

1. Een token maken

1. Open Dashboard → AI Agents & API.
2. Maak een token.
3. Schakel verify:read en verify:write in.
4. Bewaar het token veilig. Het wordt maar één keer weergegeven.

Stuur het mee met elk verzoek:

Authorization: Bearer YOUR_API_TOKEN

Bewaar het token in een geheimenopslag of omgevingsvariabele. Zet het niet in browsercode, een openbare repository, een supportverzoek of een geëxporteerd contactenbestand. Trek het in en maak een vervangend token in het dashboard als je vermoedt dat het openbaar is geworden.

2. Eén adres verifiëren

Gebruik POST /api/v1/verify voor een onmiddellijk resultaat voor één adres. Quick is standaard wanneer mode wordt weggelaten.

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"}'

Het antwoord bevat stabiele velden op het hoogste niveau, zoals adres, status, betrouwbaarheidsscore, provider, risicofactoren en resterende credits. Het object checks legt het gedetailleerde bewijs vast en kan variëren wanneer een controle niet beschikbaar is of de Deep-modus extra informatie biedt.

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

Lees eerst status en trust_score. Beschouw afzonderlijke controlesleutels als ondersteunende details, niet als garantie van mailboxbezit of bezorging.

Het afzonderlijke endpoint heeft een routelimiet van 60 verzoeken per minuut. Als je tijdens de registratie een door een gebruiker ingevoerd adres controleert, roep je het aan na eenvoudige validatie aan de clientzijde. Toon een duidelijke fout wanneer de service tijdelijk niet beschikbaar is, in plaats van de persoon onbeperkt te blokkeren.

3. Een bulktaak indienen

Bulkverzoeken accepteren een JSON-array emails, geen bestandsupload. Voeg een idempotentiesleutel toe, zodat een nieuwe netwerkpoging geen tweede taak maakt.

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

De lijst kan maximaal 50,000 items bevatten. TrekMail normaliseert duplicaten en weigert items met ongeldige syntaxis voor de taak. Het antwoord vermeldt de taak-ID, het geaccepteerde aantal, een kleine steekproef van afwijzingen, de berekende credits en de uitsplitsing van de Deep-prijs.

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

probe is het aantal dat tegen het volledige Deep-tarief wordt berekend. skip is het aantal tegen het normale tarief omdat de provider geen bruikbaar bewijs op mailboxniveau biedt. Het antwoord geeft de gezaghebbende kosten voor die indiening.

Verwijder waarden die geen adressen zijn in je eigen importprogramma voordat je een volledige lijst indient. De API ontdubbelt adressen en meldt een geweigerd aantal, maar bronvalidatie zorgt voor een duidelijker controlespoor. Als het verzoek vanuit je toepassing gezien een time-out krijgt, probeer je hetzelfde bulkverzoek opnieuw met dezelfde idempotentiesleutel en controleer je de geretourneerde taak-ID voordat je een nieuwe indiening maakt.

4. Controleren en downloaden

Controleer de taak met GET /api/v1/verify/bulk/{jobId} totdat deze een eindstatus bereikt:

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

Het antwoord bevat status, total, processed, progress, summary, de aanmaaktijd en de voltooiingstijd. Voltooide en gedeeltelijke taken bevatten een gepagineerde array results.

Controleer met een verstandig interval en oplopende wachttijd. Een taak kan in behandeling blijven voordat het werk begint en Deep-werk kan langer duren wanneer een ontvangende provider extra bewijs biedt. Leid geen vaste voltooiingstijd af uit alleen de lijstgrootte.

Je kunt een kleinere resultatenpagina aanvragen of naar een bekend adres zoeken zodra resultaten beschikbaar zijn:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Download een verwerkte taak als CSV:

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

De API-exportfilters zijn all, safe en safe_risky (Safe + Valid + Risky).

Gebruik het annuleringsendpoint om een wachtende of actieve taak te stoppen. Het betaalt onverwerkt werk terug en behoudt verwerkte rijen:

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

Verwijder een taak alleen wanneer je zowel de verifierregistratie als de resultaten wilt wissen. Annuleer de taak eerst als deze nog actief is en gebruik daarna het verwijderingsendpoint met een idempotentiesleutel. De volledige referentie toont beide aanroepen.

5. Gebruikelijke antwoorden afhandelen

• 402: het account heeft meer credits nodig.
• 422: controleer de aanvraagbody, de geselecteerde modus of de verplichte idempotentiesleutel voor een bulkverzoek.
• 429: verlaag de frequentie en probeer het opnieuw met oplopende wachttijd.
• 503: verificatie is tijdelijk niet beschikbaar. Probeer het later opnieuw; een mislukte afzonderlijke verificatie wordt terugbetaald.

Checklist voor een productie-integratie

1. Bewaar het token op de server en ken alleen de twee benodigde verifier-scopes toe.
2. Valideer en normaliseer contacten voordat je de bulk-API aanroept.
3. Bewaar de taak-ID, identificatie van de ingediende lijst, idempotentiesleutel en de geretourneerde waarde credits_charged.
4. Controleer met oplopende wachttijd in plaats van een continue lus.
5. Bewaar of verwerk de CSV vóór het einde van de bewaartermijn van 15 dagen.
6. Houd beslissingen over toestemming, afmelding en onderdrukking in je eigen toepassing bij. Een verifierresultaat vervangt deze niet.

Gebruik de REST API-referentie voor Email Verifier voor alle endpoints, scopes en antwoordvelden.