VOOR ONTWIKKELAARS

API voor e-mailverificatie.

Gebruik een controle per adres voor formulieren, of asynchrone taken voor klantlijsten. Behoud je huidige e-mailprovider.

BEGIN MET ÉÉN ADRES

Je eerste aanvraag.

Gebruik het gratis demo-endpoint zonder sleutel. Het heeft een aanvraaglimiet en is bedoeld om de dienst uit te proberen.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

Voor betaalde controles koop je een pakket en gebruik je /v1/fast-verify met je sleutel in X-API-Key. Houd sleutels buiten URL's, versiebeheer en analysetools.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Python-voorbeeld

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Node.js-voorbeeld

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

EEN LIJST ERIN, RESULTATEN ERUIT

Verifieer een grotere lijst.

POST /v1/tasks

Dien tot 10.000 adressen per taak in. Bewaar de geretourneerde taak-ID en controleer accepted, skipped en invalids: niet elke invoer komt per se in de wachtrij. Duplicaten, onjuist opgemaakte en geblokkeerde adressen kunnen worden verwijderd, en bij een laag saldo kan de lijst gedeeltelijk worden geaccepteerd.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

Vraag de status op en haal daarna elke resultaatpagina op. Een antwoord met alleen ongeldige invoer kan een lege taak-ID hebben; vraag die niet op.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Resultaten van voltooide taken zijn JSON. Blijf pagina's ophalen totdat de volledige geaccepteerde lijst is opgehaald. Voor automatische afronding geef je een webhook mee met mode: "completed" bij het aanmaken van de taak.

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

Raadpleeg het schema voor de webhookconfiguratie en de verificatie van handtekeningen voordat je dit in productie inschakelt.

BEGRIJP HET ANTWOORD

Opmaak is geen bestaan.

Dit zijn aparte signalen. Een correct opgemaakt adres kan toch niet bestaan, tijdelijk zijn of onmogelijk te bevestigen.

Veld	Betekenis
`valid`	Het adres heeft de syntaxcontrole doorstaan. Dat alleen bevestigt de mailbox niet.
`exists`	Het resultaat van de mailboxtest. Interpreteer het samen met fouten en catch-all-signalen.
`disposable`	Het domein is herkend als aanbieder van tijdelijke e-mailadressen.
`accept_all`	De server accepteert willekeurige adressen; de specifieke mailbox is niet betrouwbaar te bevestigen.
`error_category`	Verklaart een fout of risico, zoals no_mx, risky of een tijdelijk serverprobleem.
`permanent_error`	Tijdens de controle is een permanente fout geretourneerd. Een tijdelijke fout moet je niet als permanente weigering behandelen.
`ttl`	Een tijdsindicatie in seconden voor opnieuw proberen of caching, indien geretourneerd.

Verificatie kan geen aflevering garanderen, klachten niet uitsluiten en niet bewijzen wie eigenaar van een mailbox is.

Ken je saldo.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Het antwoord bevat resterende, gereserveerde en gebruikte credits, het sleuteltype en de vervaldatum. Een standaardverificatie kost één credit; de feitelijke filtering en afrekening hangen af van de route en de acceptatie van de taak. Controleer het antwoord voordat je een volledig geüploade lijst als verwerkt beschouwt.

Een 429-antwoord betekent dat aanvragen worden beperkt. Wacht even voordat je het opnieuw probeert. Andere fouten kunnen in de huidige API als JSON of tekst worden geretourneerd; interpreteer HTTP-fouten niet als verificatieresultaten.

Het verificatiecontract.

OpenAPI JSON downloaden

Het openbare contract omvat demo, snelle verificatie, taken, taakstatus, resultaten en accountsaldo. Endpoints voor verzending en beheer vallen buiten deze verificatiereferentie.

Hulp nodig bij het koppelen van je platform? support@zbounce.net