POUR LES DÉVELOPPEURS

API de vérification e-mail.

Vérifiez une adresse à la fois dans les formulaires ou utilisez des tâches asynchrones pour les listes clients. Conservez votre fournisseur e-mail actuel.

COMMENCEZ PAR UNE ADRESSE

Votre première requête.

Utilisez le point d’accès de démonstration gratuit sans clé. Il est soumis à une limite de requêtes et sert à tester le service.

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

Pour les vérifications payantes, achetez une offre et utilisez /v1/fast-verify avec votre clé dans X-API-Key. Ne placez pas les clés dans les URL, les dépôts de code ou les outils d’analyse.

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

Exemple Python

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())

Exemple Node.js

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());

ENVOYEZ UNE LISTE, RECEVEZ LES RÉSULTATS

Vérifiez une liste plus grande.

POST /v1/tasks

Envoyez jusqu’à 10 000 adresses par tâche. Conservez l’identifiant de tâche retourné et examinez accepted, skipped et invalids: toutes les entrées ne sont pas forcément mises en file. Les doublons, les adresses mal formées ou exclues peuvent être retirés, et un solde faible peut entraîner une acceptation partielle.

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

Interrogez le statut, puis récupérez chaque page de résultats. Une réponse ne contenant que des entrées invalides peut avoir un identifiant de tâche vide ; ne l’interrogez pas.

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"

Les résultats des tâches terminées sont au format JSON. Récupérez les pages jusqu’à avoir obtenu toute la liste acceptée. Pour être informé automatiquement de la fin, transmettez un webhook avec mode: "completed" lors de la création de la tâche.

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

Consultez le schéma concernant la configuration des webhooks et la vérification des signatures avant leur activation en production.

COMPRENDRE LA RÉPONSE

Le format ne prouve pas l’existence.

Ce sont des signaux distincts. Une adresse bien formée peut ne pas exister, être jetable ou impossible à confirmer.

Champ	Signification
`valid`	L’adresse a passé la validation syntaxique. Cela ne confirme pas à lui seul sa boîte.
`exists`	Résultat du test de la boîte. Interprétez-le avec les erreurs et les signaux catch-all.
`disposable`	Le domaine a été reconnu comme fournisseur d’adresses e-mail temporaires.
`accept_all`	Le serveur accepte des adresses arbitraires ; la boîte précise ne peut pas être confirmée de façon fiable.
`error_category`	Explique un échec ou un risque, tel que no_mx, risky ou un problème temporaire de serveur.
`permanent_error`	Un échec permanent a été renvoyé pendant la vérification. Un échec temporaire ne doit pas être considéré comme un rejet permanent.
`ttl`	Indication de délai de nouvelle tentative ou de cache, en secondes, lorsqu’elle est renvoyée.

La vérification ne peut garantir la livraison, éliminer les plaintes ni prouver la propriété d’une boîte.

Connaissez votre solde.

GET /v1/me

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

La réponse inclut les crédits restants, réservés et utilisés, le type de clé et son expiration. Une vérification standard utilise un crédit ; le filtrage et la facturation effectifs dépendent du point d’accès et de l’acceptation de la tâche. Vérifiez la réponse avant de considérer une liste importée entière comme traitée.

Une réponse 429 indique une limitation des requêtes. Attendez avant de réessayer. Les autres erreurs de l’API actuelle peuvent être renvoyées en JSON ou en texte ; n’interprétez pas les erreurs HTTP comme des résultats de vérification.

La spécification de vérification.

Télécharger le JSON OpenAPI

La spécification publique couvre la démonstration, la vérification rapide, les tâches, leur statut, les résultats et le solde. Les points d’accès d’envoi et d’administration sont hors du périmètre de cette référence.

Besoin d’aide pour connecter votre plateforme ? support@zbounce.net