API de validation d'email en temps réel : guide développeur

La vérification d'email en temps réel contrôle une adresse pendant que l'utilisateur est encore sur votre formulaire. Elle s'exécute dans les quelques centaines de millisecondes entre « Submit » et l'écran suivant, et répond à une question : cette adresse doit-elle entrer dans votre base de données ? Une API de vérification d'email en temps réel prend cette décision pour vous. Elle examine la syntaxe, le domaine et ses enregistrements MX, les signaux liés aux adresses jetables et aux rôles, le comportement catch-all et, si vous le demandez, la boîte aux lettres elle-même. Elle renvoie ensuite un résultat structuré que votre code peut exploiter.

Ce guide s'adresse aux développeurs qui ajoutent ce contrôle à un formulaire d'inscription, de paiement ou de génération de prospects. Il explique ce que font les vérifications, comment appeler une API, comment transformer chaque statut en décision produit et comment rester rapide lorsqu'un serveur de messagerie est lent. Les exemples utilisent l'API de vérification d'email BillionVerify, mais les conseils de conception s'appliquent à n'importe quel fournisseur.

Qu'est-ce que la validation d'email en temps réel ?

La validation d'email en temps réel est une vérification effectuée au moment où une adresse est saisie, et non plusieurs jours plus tard, lorsque la campagne est envoyée. L'utilisateur saisit une adresse. Votre frontend ou backend l'envoie à une API de vérification d'email. L'API répond avec un statut tel que valid, invalid ou catchall, ainsi que les signaux associés. Votre application autorise alors l'inscription, la bloque ou demande à l'utilisateur de corriger une faute de frappe.

L'essentiel, c'est le timing. Une faute comme gmial.com ne coûte rien à corriger tant que l'utilisateur est encore sur le formulaire. Une fois que l'email de bienvenue a rebondi, la même faute vous coûte ce client. Les mauvaises adresses nuisent également à votre réputation d'expéditeur, car chaque hard bounce indique aux fournisseurs de messagerie que vous envoyez des emails à des adresses non confirmées. La vérification d'email en temps réel les arrête à la porte.

Elle contribue également à lutter contre la fraude : une vérification en temps réel peut signaler une boîte de réception jetable avant même que le compte n'existe.

Validation d'email en temps réel vs en masse

Les deux approches utilisent les mêmes vérifications. Elles diffèrent par le moment où elles s’exécutent et le temps dont elles disposent.

• La validation en temps réel s’exécute sur une adresse à la fois, dans le cadre d’une demande utilisateur. Elle dispose d’un délai strict, souvent bien inférieur à une seconde, car un formulaire lent fait perdre des inscriptions. Elle empêche les mauvaises données d’entrer.
• La validation en masse s’exécute sur une liste complète, en arrière-plan. Elle peut prendre quelques minutes ou plusieurs heures, et personne n’attend devant un écran. Elle nettoie les données déjà présentes dans votre système, par exemple avant une grande campagne ou après un import CRM.

La plupart des équipes ont besoin des deux. Les vérifications en temps réel maintiennent la propreté des nouvelles données, tandis qu’une vérification d'email en masse périodique repère les adresses devenues invalides au fil du temps, comme celles d’employés ayant quitté une entreprise. Pour une comparaison plus approfondie, consultez la validation d'email en temps réel vs en masse.

Ce qu’un contrôle en temps réel teste réellement

Une API de validation d'email effectue une série de contrôles, du moins coûteux au plus coûteux. Chacun élimine un type différent d'adresse invalide.

Syntaxe

Le premier contrôle porte sur le format. Y a-t-il exactement un @ ? La partie locale contient-elle uniquement des caractères autorisés ? Le domaine ressemble-t-il bien à un domaine ? La syntaxe rejette les erreurs évidentes, comme john@@example ou jane.example.com. Elle est rapide et ne nécessite aucun appel réseau. Mais une syntaxe parfaite ne dit rien sur l'existence réelle de la boîte mail.

Domaine et enregistrements MX

Ensuite, l'API recherche le domaine dans le DNS. Un domaine sans enregistrements MX ne peut pas recevoir d'emails, donc une adresse qui y est rattachée est inutile, même si elle semble parfaitement correcte. Cela permet de détecter les domaines mal orthographiés et les domaines d'entreprise inactifs. BillionVerify renvoie les hôtes MX trouvés dans mx_records, et domain_suggestion peut contenir une correction probable lorsque le domaine ressemble à une faute de frappe d'un domaine courant.

Signaux liés aux adresses jetables, de rôle et de fournisseurs gratuits

Certaines adresses existent, mais restent mal adaptées à votre produit :

• Les adresses jetables proviennent de services de boîtes de réception temporaires et cessent généralement de fonctionner en quelques heures. Consultez le fonctionnement de la détection des emails jetables.
• Les adresses de rôle, comme info@ ou support@, sont destinées à une équipe et non à une personne. Elles sont généralement délivrables, mais ont tendance à susciter moins d'engagement.
• Les adresses de fournisseurs gratuits, comme Gmail, sont normales pour les particuliers, mais méritent d'être enregistrées dans un formulaire B2B.

L'API renvoie ces informations sous forme d'indicateurs (is_disposable, is_role, is_free), afin que vous puissiez prendre une décision pour chaque produit.

Domaines catch-all

Certains serveurs de messagerie acceptent les emails destinés à n'importe quelle adresse de leur domaine, qu'elle existe ou non. Pour ces domaines catch-all, un contrôle de boîte mail ne peut pas prouver qu'une boîte de réception précise existe. Un résultat catch-all n'est pas un mauvais résultat. Il signifie que le niveau de certitude est plus faible : le score compte donc davantage que le libellé. La détection des emails catch-all explique le fonctionnement de ce mécanisme et son importance.

Contrôle de boîte mail via SMTP

Le contrôle le plus approfondi demande au serveur de messagerie du destinataire, via SMTP, s'il accepterait un message, sans en envoyer un. Il détecte les adresses situées sur des domaines réels qui n'existent plus, comme la boîte mail d'un ancien employé. C'est également l'étape la plus lente, car elle dépend du serveur de quelqu'un d'autre. Dans BillionVerify, elle est contrôlée par le paramètre check_smtp. Si vous l'omettez, l'API exécute le contrôle SMTP ; envoyez check_smtp: false pour l'ignorer.

Réputation du domaine

BillionVerify peut également renvoyer un objet domain_reputation contenant les résultats des listes noires pour l'IP du serveur de messagerie du domaine. Cette information est fournie à titre indicatif uniquement : elle ne modifie ni le statut, ni le score, ni le coût.

Comment appeler une API de validation d'email en temps réel

Avec BillionVerify, une seule vérification en temps réel correspond à une requête HTTPS. L'URL de base est https://api.billionverify.com/v1, et votre clé API est transmise dans l'en-tête BV-API-KEY. Conservez cette clé sur votre serveur. Ne l'intégrez jamais dans le code du navigateur.

Voici une requête minimale, basée sur la référence de l'API :

curl -X POST https://api.billionverify.com/v1/verify/single \
  -H "BV-API-KEY: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","check_smtp":true}'

La requête accepte trois paramètres :

Une réponse réussie encapsule le résultat dans une enveloppe standard. Voici un exemple abrégé pour une adresse offrant une bonne délivrabilité des emails :

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "score": 0.95,
    "is_deliverable": true,
    "is_disposable": false,
    "is_catchall": false,
    "is_role": false,
    "is_free": false,
    "domain": "example.com",
    "mx_records": ["mail.example.com"],
    "check_smtp": true,
    "reason": "smtp_deliverable",
    "domain_suggestion": "",
    "response_time": 250,
    "credits_used": 1
  }
}

Si vous préférez un SDK, BillionVerify publie des SDK officiels pour Node.js, Python, TypeScript, Go, PHP et Java. Avec Node.js, npm install billionverify-sdk vous fournit un client doté d'une méthode verify ; avec Python, le package est billionverify.

Lire la réponse : statut, score et raison

Le champ status est celui sur lequel se basent la plupart des branches de code. Voici la signification de chaque statut et une valeur par défaut pertinente pour un formulaire d'inscription :

Le score vous fournit un signal plus précis compris entre 0 et 1. À titre indicatif, les résultats valid obtiennent un score de 0,85 à 1,0, catchall environ 0,55 à 0,75, unknown de 0,3 à 0,6, disposable 0,1 et invalid 0. Un résultat role conserve le score de la vérification sous-jacente. Vous pouvez utiliser le score pour définir votre propre seuil concernant les cas limites, par exemple pour n'accepter les adresses catch-all qu'au-dessus d'un certain score sur un formulaire à forte valeur.

Le champ reason explique le verdict. Un résultat invalid peut être accompagné de invalid_syntax, no_mx_records ou mailbox_not_found, et chacun correspond à un message différent pour l'utilisateur. Un problème de syntaxe signifie « vérifiez le format ». Une boîte aux lettres manquante signifie « cette boîte de réception n'existe pas ». La page raisons de la vérification répertorie toutes les raisons et indique lesquelles des raisons unknown méritent une nouvelle tentative.

Deux champs aident directement l'utilisateur : domain_suggestion peut alimenter une suggestion du type « Vouliez-vous dire gmail.com ? », et is_disposable explique pourquoi une adresse jetable a été refusée.

Concevoir le parcours d’inscription autour d’un budget de latence

La difficulté consiste à intégrer le contrôle dans un formulaire sans le ralentir. Commencez par définir un budget. Décidez combien de temps vous êtes prêt à retenir l’utilisateur, par exemple 300 à 500 millisecondes lors de l’envoi. Tout le reste découle de ce chiffre.

Le contenu produit de BillionVerify annonce des résultats mis en cache en moins de 200 ms et un contrôle SMTP complet en 1 à 3 secondes en moyenne. Cet écart vous laisse deux bonnes options :

1. Contrôle complet avec délai d’expiration. Appelez l’API avec SMTP activé et un délai d’expiration de 2 à 3 secondes. La plupart des réponses arrivent à temps et vous donnent un résultat clair, valid ou invalid. Si le délai expire, laissez passer la demande et effectuez une nouvelle vérification ultérieurement.
2. Contrôle rapide immédiat, contrôle approfondi ultérieur. Appelez l’API avec check_smtp: false. Cela permet uniquement de trancher les cas évidents : syntaxe incorrecte, domaine sans enregistrements MX, adresses jetables et adresses de rôle. Une adresse sur un domaine fonctionnel revient avec le statut unknown et la raison smtp_unverifiable, ce qui est attendu. Acceptez-la, puis lancez un second appel avec SMTP activé depuis une tâche en arrière-plan. Si la boîte aux lettres n’existe pas, marquez le compte et demandez à l’utilisateur de confirmer son adresse.

Quelques bonnes pratiques frontend sont également utiles :

• Validez lors de la perte de focus ou de l’envoi, pas à chaque frappe. Vérifier j, jo, joh gaspille des appels et des crédits.
• Effectuez d’abord les contrôles locaux de syntaxe afin d’éviter un aller-retour pour les erreurs évidentes.
• Appelez l’API depuis votre backend. Votre serveur conserve la clé API et enregistre le résultat ; le navigateur affiche uniquement le résultat.

Pour les détails liés à l’UX, tels que la formulation, l’emplacement des erreurs et le moment où afficher une indication, consultez la vérification d'email lors de l’inscription.

Échec fermé ou échec ouvert ? Gérer les délais d'attente et les cas inconnus

Le modèle qui fonctionne pour la plupart des produits est le suivant : bloquer en cas d'erreur claire, laisser passer en cas d'incertitude.

• Bloquer en cas d'erreur signifie bloquer l'inscription. Faites-le lorsque l'API indique que l'adresse est clairement invalide : invalid avec invalid_syntax ou no_mx_records, ou une adresse disposable sur un formulaire où les comptes temporaires peuvent causer des problèmes.
• Laisser passer en cas d'incertitude signifie autoriser l'utilisateur à continuer et effectuer un suivi ultérieurement. Faites-le lorsque la réponse est incertaine : un statut unknown, un domaine catch-all ou l'expiration de votre propre délai d'attente avant la réponse de l'API.

Pourquoi bloquer aussi les adresses incertaines ? De vraies personnes utilisent bon nombre d'entre elles. Les serveurs de messagerie d'entreprise appliquent souvent une greylist ou limitent le débit des vérifications SMTP ; les bloquer vous fait donc perdre de véritables inscriptions. Acceptez-les, marquez l'enregistrement, puis vérifiez-le à nouveau ultérieurement.

Définissez un délai d'attente côté client pour votre appel API qui corresponde à votre budget de latence. Lorsqu'il expire, traitez le résultat comme unknown : acceptez, enregistrez un indicateur et mettez en file d'attente une nouvelle vérification en arrière-plan. Réessayez les résultats unknown ultérieurement plutôt que pendant la requête.

Exemple : Valider une adresse email lors de l'inscription avec Node.js

L'exemple ci-dessous montre la vérification rapide (conception 2) dans un gestionnaire d'inscription. Il utilise le point de terminaison REST documenté et les champs de réponse, un délai d'expiration, ainsi que les règles de basculement en mode ouvert ou fermé ci-dessus. Adaptez les noms à votre framework.

const BLOCK = new Set(['invalid', 'disposable']);

async function checkEmail(email) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 400);

  try {
    const response = await fetch('https://api.billionverify.com/v1/verify/single', {
      method: 'POST',
      headers: {
        'BV-API-KEY': process.env.BV_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, check_smtp: false }),
      signal: controller.signal,
    });
    const body = await response.json();
    if (!body.success) return { allow: true, recheck: true };

    const { status, reason, domain_suggestion } = body.data;
    if (BLOCK.has(status)) {
      return { allow: false, reason, suggestion: domain_suggestion };
    }
    return { allow: true, recheck: status === 'unknown' || status === 'catchall' };
  } catch {
    // Timeout or network error: fail open and re-check in the background.
    return { allow: true, recheck: true };
  } finally {
    clearTimeout(timer);
  }
}

Sans SMTP, la plupart des adresses réelles renvoient unknown et reçoivent l'indicateur recheck. Une fois le compte enregistré, une tâche en arrière-plan appelle le même point de terminaison avec SMTP activé pour chaque enregistrement marqué recheck. Le tutoriel Node.js présente une configuration plus complète, notamment le SDK officiel. La même requête fonctionne avec Python ou tout langage doté d'un client HTTP.

Limites de débit, mise en cache et coût

Une vérification en temps réel intervient lors de votre inscription, ses limites deviennent donc les vôtres. Prévoyez-les.

Limites de débit. BillionVerify protège sa capacité avec des limites par compte. Lorsque vous en atteignez une, l'API renvoie HTTP 429 avec le code 1003 et un en-tête Retry-After. Réduisez le rythme et réessayez, tout en conservant votre propre règle de fonctionnement en cas d'échec afin qu'une limite ne bloque jamais un véritable utilisateur.

Mise en cache. Les résultats sont mis en cache, c'est pourquoi les vérifications répétées sont rapides. Revérifier une adresse que votre compte a vérifiée au cours des dernières 24 heures est gratuit. Utilisez force_refresh: true uniquement lorsque vous avez réellement besoin d'une réponse actualisée, car cela ignore le cache et est facturé comme une nouvelle vérification.

Coût. Une vérification unique utilise normalement 1 crédit, indiqué dans credits_used. Chaque résultat unknown est gratuit, tout comme les échecs de syntaxe. Validez lors de l'envoi plutôt qu'à chaque frappe, et ne revérifiez pas une adresse que vous avez vérifiée récemment. BillionVerify vous offre 20 crédits gratuits chaque jour où vous vous connectez, jusqu'à 600 par mois, ce qui suffit pour créer et tester une intégration. Les packs de crédits payants sont indiqués sur la page des tarifs.

Au-delà du formulaire : lots, fichiers et webhooks

La validation en temps réel couvre les nouvelles adresses une par une. Pour tout le reste, la même API propose d’autres points d’entrée :

• Petits lots. POST /verify/bulk vérifie jusqu’à 50 adresses en une seule requête, ce qui convient à une synchronisation CRM ou à un écran d’importation.
• Listes volumineuses. POST /verify/file accepte un fichier CSV, TXT ou XLSX et le traite en arrière-plan.
• Webhooks. Au lieu d’interroger régulièrement une tâche de fichier, enregistrez un webhook pour les événements file.completed et file.failed. Consultez le guide sur les webhooks de vérification d'email pour les vérifications de signature et les nouvelles tentatives.
• Vérifications des adresses jetables uniquement. POST /verify/disposable répond uniquement à la question des adresses jetables et n’utilise pas de crédits.

Configuration courante : vérifications en temps réel sur chaque formulaire, un lot nocturne pour les enregistrements marqués recheck, et une tâche de fichier avant les campagnes importantes.

Checklist de vérification d'email en temps réel

Avant la mise en production, parcourez cette liste :

• La clé API se trouve sur le serveur, jamais dans le navigateur.
• La syntaxe est vérifiée localement avant l'appel à l'API.
• Le chemin de requête utilise check_smtp: false et un délai d'expiration adapté à votre budget de latence.
• invalid et disposable disposent de messages d'erreur clairs et spécifiques.
• unknown, catchall et les délais d'expiration échouent en mode permissif et sont mis en file d'attente pour une nouvelle vérification.
• domain_suggestion alimente une suggestion en cas de faute de frappe.
• Les réponses 429 déclenchent un ralentissement sans bloquer les utilisateurs.
• Les résultats sont enregistrés avec la fiche utilisateur afin de mesurer ultérieurement les taux de rebond.

FAQ

Qu’est-ce qu’une API de validation d’emails en temps réel ?

Une API de validation d’emails en temps réel vérifie une seule adresse email lorsqu’un utilisateur envoie un formulaire et renvoie un verdict en une fraction de seconde. Elle effectue des vérifications de syntaxe, de domaine, de MX, d’adresses jetables, de rôles et de domaines catch-all, ainsi que, facultativement, une vérification de boîte aux lettres via SMTP, afin que votre application puisse accepter, bloquer ou signaler l’adresse avant son ajout à votre base de données.

Quelle est la différence entre la validation d’emails en temps réel et la validation en masse ?

La validation d’emails en temps réel vérifie une adresse à la fois dans le cadre d’une requête utilisateur et doit répondre rapidement. La validation en masse vérifie toute une liste en arrière-plan et peut prendre beaucoup plus de temps. Utilisez les vérifications en temps réel pour garder les nouvelles données propres et les vérifications en masse pour nettoyer les données que vous possédez déjà.

Dois-je effectuer la vérification SMTP lors de chaque inscription ?

Cela dépend de votre budget de latence. La vérification SMTP confirme l’existence d’une boîte aux lettres ; sans elle, la plupart des adresses réelles sont renvoyées comme unknown. Si vous pouvez attendre 2 à 3 secondes, effectuez-la lors de l’envoi du formulaire avec un délai d’expiration. Sinon, lancez la vérification rapide avec check_smtp: false, puis effectuez la vérification SMTP dans une tâche en arrière-plan.

Que dois-je faire des résultats catch-all et unknown ?

Acceptez-les et vérifiez-les à nouveau plus tard. Un domaine catch-all accepte toutes les adresses, donc la vérification de boîte aux lettres ne peut pas prouver que la boîte de réception existe, tandis qu’un résultat unknown signifie que la vérification n’a pas pu se terminer. Bloquer ces utilisateurs fait perdre des inscriptions réelles ; les étiqueter puis les vérifier à nouveau permet de garder vos données propres sans nuire à la conversion.

Puis-je appeler l’API de vérification d’emails depuis le navigateur ?

Non. Cela expose votre clé API. Appelez l’API depuis votre backend et ne renvoyez que la décision.

Quelle est la rapidité de la vérification d’emails en temps réel ?

Avec BillionVerify, les résultats mis en cache sont renvoyés en moins de 200 ms, tandis qu’une vérification SMTP complète prend en moyenne 1 à 3 secondes. C’est pourquoi la vérification rapide sans SMTP doit être effectuée dans le chemin de la requête, et la vérification SMTP en arrière-plan.

Combien coûte une API de validation d’emails ?

Avec BillionVerify, une vérification unique utilise normalement 1 crédit, et chaque résultat unknown est gratuit. Vous recevez 20 crédits gratuits chaque jour où vous vous connectez, jusqu’à 600 par mois, et des packs de crédits payants sont disponibles sur la page des tarifs. force_refresh ignore le cache et est facturé comme une nouvelle vérification.

Commencez à valider les emails en temps réel

La vérification d'email en temps réel signifie moins de rebonds, moins de faux comptes et moins d'utilisateurs perdus à cause d'une faute de frappe. Ajoutez une vérification rapide au chemin de la requête, déplacez la vérification lente en arrière-plan et laissez les échecs certains bloquer, tandis que les résultats incertains passent. Créez un compte BillionVerify gratuit, obtenez une clé API et effectuez votre premier appel API de validation d'email à partir de la documentation ci-dessus.