Développeurs

Une API de vérification d'e-mails qui fonctionne, tout simplement

Vérifiez une adresse en temps réel ou envoyez une liste entière en batch. Toutes les requêtes utilisent HTTPS et renvoient du JSON. Créez vos clés API dans votre tableau de bord, rubrique Clés API.

Obtenir une clé API Lire la référence

REST et JSON
Callbacks batch
Mêmes crédits que le tableau de bord

La page Clés API de BounceBell avec les clés actives et un formulaire pour créer une nouvelle clé

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 }

Authentification

Envoyez votre clé API comme jeton bearer dans l'en-tête Authorization de chaque requête. Conservez les clés sur votre serveur. Ne les placez jamais dans du code exécuté dans le navigateur ni dans des applications mobiles.

Authorization: Bearer YOUR_API_KEY

L'URL de base de chaque endpoint est https://bouncebell.com/api/v1.

Vérifier une adresse

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

Paramètre	Obligatoire	Description
`email`	Oui	L'adresse à vérifier. Encodez-la pour l'URL.
`timeout`	Non	Délai d'attente du serveur de messagerie en secondes, de 3 à 30. 10 par défaut. Si le délai expire, le statut est `unknown` et aucun crédit n'est utilisé.

Exemple

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
}

Champs du résultat

Champ	Type	Description
`email`	string	L'adresse telle que vous l'avez envoyée.
`status`	string	Le verdict. Voir les statuts.
`reason`	string	La raison du verdict, par exemple `mailbox_not_found` ou `no_mail_server`.
`domain`	string	La partie domaine, en minuscules.
`mx_record`	string or null	Le serveur de messagerie ayant la priorité la plus élevée.
`disposable`	boolean	Vrai si le domaine est un service de boîte de réception temporaire.
`role`	boolean	Vrai pour les boîtes partagées comme info@ ou support@.
`free_provider`	boolean	Vrai pour les fournisseurs de messagerie gratuits comme Gmail.
`catch_all`	boolean	Vrai lorsque le domaine accepte toutes les adresses.
`did_you_mean`	string or null	Une adresse corrigée lorsque le domaine semble contenir une faute de frappe.
`checked_at`	string	Date et heure de la vérification, au format ISO 8601 UTC.
`credits_used`	integer	1, ou 0 lorsque le statut est `unknown`.

Statuts

Statut	Signification	Action suggérée
`valid`	La boîte aux lettres existe et accepte les e-mails.	Envoyer
`invalid`	L'adresse, le domaine ou la boîte aux lettres n'existe pas.	Supprimer
`disposable`	Un service de boîte de réception temporaire.	Supprimer
`catch_all`	Le domaine accepte toutes les adresses, la boîte aux lettres ne peut donc pas être confirmée.	À examiner
`role`	Une boîte partagée qui existe.	À examiner
`unknown`	Le serveur de messagerie n'a pas répondu à temps. Non facturé.	Réessayer plus tard

Batchs

Envoyez jusqu'à 100 000 adresses en une seule requête. Le batch s'exécute en arrière-plan : interrogez son statut ou indiquez une callback_url que nous appellerons lorsque le batch sera terminé.

Créer un batch

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 }

Les crédits de chaque adresse unique sont réservés à la création du batch, et les résultats inconnus sont remboursés à la fin. Le callback reçoit un POST avec {"event": "batch.completed", "batch_id": "...", "status": "done", "counts": {...}}. Les URL de callback doivent utiliser HTTPS.

Suivre la progression

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

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

Le statut est queued, running ou done. Lorsqu'il est done, la réponse contient aussi les counts par statut.

Télécharger les résultats

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

Renvoie du JSON par défaut. Ajoutez ?format=csv pour obtenir un fichier CSV. Chaque ligne contient les mêmes champs qu'une vérification unitaire.

Crédits

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

{ "credits_remaining": 33420 }

Erreurs et limites

Les erreurs renvoient un corps JSON avec un code error et un message lisible.

Code HTTP	Erreur	Que faire
400	`bad_request`	Un paramètre est manquant ou incorrect. Lisez le message.
401	`invalid_key`	Vérifiez que la clé est correcte et n'a pas été révoquée.
402	`no_credits`	Achetez plus de crédits.
403	`email_not_confirmed`	Ouvrez le lien de confirmation que nous vous avons envoyé par e-mail lors de votre inscription.
404	`not_found`	Le batch n'existe pas ou a été supprimé après 30 jours.
429	`rate_limited`	Ralentissez. Attendez le nombre de secondes indiqué dans l'en-tête `Retry-After`.
500	`server_error`	Réessayez après un court délai. Si le problème persiste, contactez le support.

Les vérifications unitaires sont limitées à 20 requêtes par seconde et par clé. Contactez-nous si vous avez besoin de plus.