Ontwikkelaars

Een API voor e-mailverificatie die gewoon werkt

Controleer één adres in realtime, of stuur een hele lijst als batch. Alle verzoeken gebruiken HTTPS en geven JSON terug. Maak API-sleutels aan in je dashboard onder API-sleutels.

Vraag een API-sleutel aan Lees de referentie

REST en JSON
Batch-callbacks
Dezelfde credits als het dashboard

De pagina API-sleutels in BounceBell met actieve sleutels en een formulier om een nieuwe sleutel aan te maken

verify.sh

# Verify one addresscurl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth@acme-foods.com" \  -H "Authorization: Bearer YOUR_API_KEY" { "status": "valid",  "reason": "mailbox_exists",  "did_you_mean": null }

Authenticatie

Stuur je API-sleutel bij elk verzoek mee als bearer-token in de Authorization-header. Bewaar sleutels op je server. Zet ze nooit in browsercode of mobiele apps.

Authorization: Bearer YOUR_API_KEY

De basis-URL voor elk endpoint is https://bouncebell.com/api/v1.

Controleer één adres

GET https://bouncebell.com/api/v1/verify

Parameter	Verplicht	Beschrijving
`email`	Ja	Het te controleren adres. URL-gecodeerd.
`timeout`	Nee	Aantal seconden om op de mailserver te wachten, van 3 tot 30. Standaard 10. Is de tijd op, dan is de status `unknown` en wordt er geen credit gebruikt.

Voorbeeld

curl "https://bouncebell.com/api/v1/verify?email=rini.elizabeth%40acme-foods.example" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "rini.elizabeth@acme-foods.example",
  "status": "valid",
  "reason": "mailbox_exists",
  "domain": "acme-foods.example",
  "mx_record": "mx1.acme-foods.example",
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "did_you_mean": null,
  "checked_at": "2026-10-30T09:30:12Z",
  "credits_used": 1
}

Resultaatvelden

Veld	Type	Beschrijving
`email`	string	Het adres zoals je het hebt verstuurd.
`status`	string	De uitslag. Zie statussen.
`reason`	string	Waarom we tot de uitslag kwamen, bijvoorbeeld `mailbox_not_found` of `no_mail_server`.
`domain`	string	Het domeingedeelte, in kleine letters.
`mx_record`	string or null	De mailserver met de hoogste prioriteit.
`disposable`	boolean	True als het domein een dienst voor tijdelijke inboxen is.
`role`	boolean	True bij gedeelde inboxen zoals info@ of support@.
`free_provider`	boolean	True bij gratis mailboxproviders zoals Gmail.
`catch_all`	boolean	True als het domein elk adres accepteert.
`did_you_mean`	string or null	Een gecorrigeerd adres als het domein op een typefout lijkt.
`checked_at`	string	Wanneer de controle is uitgevoerd, in ISO 8601 UTC.
`credits_used`	integer	1, of 0 als de status `unknown` is.

Statussen

Status	Betekenis	Voorgestelde actie
`valid`	De mailbox bestaat en accepteert e-mail.	Versturen
`invalid`	Het adres, domein of de mailbox bestaat niet.	Verwijderen
`disposable`	Een dienst voor tijdelijke inboxen.	Verwijderen
`catch_all`	Het domein accepteert alle adressen, dus de mailbox kan niet worden bevestigd.	Nakijken
`role`	Een gedeelde inbox die bestaat.	Nakijken
`unknown`	De mailserver gaf niet op tijd antwoord. Niet in rekening gebracht.	Later opnieuw proberen

Batches

Stuur tot 100.000 adressen in één verzoek. De batch draait op de achtergrond; vraag de status op of geef een callback_url op, dan roepen we die aan zodra de batch klaar is.

Een batch aanmaken

POST https://bouncebell.com/api/v1/batches

curl -X POST "https://bouncebell.com/api/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October import", "emails": ["a@example.com", "b@example.com"],
       "callback_url": "https://yourapp.example/hooks/bouncebell"}'

{ "id": "bat_8f2k1q3m9x7w4p", "status": "queued", "total": 2, "done": 0 }

Credits voor elk uniek adres worden gereserveerd zodra de batch wordt aangemaakt, en onbekende resultaten worden terugbetaald als hij klaar is. De callback ontvangt een POST met {"event": "batch.completed", "batch_id": "...", "status": "done", "counts": {...}}. Callback-URL's moeten HTTPS gebruiken.

Voortgang opvragen

GET https://bouncebell.com/api/v1/batches/{id}

{ "id": "bat_8f2k1q3m9x7w4p", "status": "running", "total": 2, "done": 1 }

De status is queued, running of done. Bij done bevat het antwoord ook counts per status.

Resultaten downloaden

GET https://bouncebell.com/api/v1/batches/{id}/results

Geeft standaard JSON terug. Voeg ?format=csv toe voor een CSV-bestand. Elke rij heeft dezelfde velden als een losse controle.

Credits

GET https://bouncebell.com/api/v1/credits

{ "credits_remaining": 33420 }

Fouten en limieten

Fouten geven een JSON-body terug met een error-code en een leesbare message.

HTTP-code	Fout	Wat te doen
400	`bad_request`	Er ontbreekt een parameter of hij is onjuist. Lees de melding.
401	`invalid_key`	Controleer of de sleutel klopt en niet is ingetrokken.
402	`no_credits`	Koop meer credits.
403	`email_not_confirmed`	Open de bevestigingslink die we je mailden toen je je aanmeldde.
404	`not_found`	De batch bestaat niet of is na 30 dagen verwijderd.
429	`rate_limited`	Rustig aan. Wacht het aantal seconden uit de `Retry-After`-header af.
500	`server_error`	Probeer het na een korte pauze opnieuw. Blijft het probleem, neem dan contact op met support.

Losse controles zijn beperkt tot 20 verzoeken per seconde per sleutel. Vraag het ons als je meer nodig hebt.