API de validation email hébergée en Europe

L'API de validation email de YesWeCheck analyse une adresse et renvoie un statut, les raisons qui le motivent et un score de risque. Vingt contrôles s'exécutent par adresse, dix-neuf sans consommer de crédit. La vérification SMTP est le seul contrôle facturé. Les données sont hébergées en France, chez OVHcloud.

Cette page rassemble la référence fonctionnelle de l'API : ce qu'elle mesure, ce qu'elle renvoie et ce qu'elle facture. Les schémas complets, les codes d'erreur détaillés et les exemples par langage vivent dans la documentation.

Intégrer l'API en trois étapes

Une intégration tient en trois gestes : obtenir une clé, envoyer l'adresse au point d'entrée de validation, puis décider sur le statut rendu. Le score et le détail des contrôles servent ensuite à affiner la décision, ou à expliquer un refus à la personne qui saisit.

  1. Créer une clé

    Un compte gratuit donne une clé API et 100 vérifications SMTP offertes, sans carte bancaire.

  2. Envoyer l'adresse

    Un appel POST /v2/email/validate, avec l'en-tête Authorization: Bearer. Le paramètre smtp décide si la vérification facturée s'exécute.

  3. Décider sur le statut

    Le champ result dit quoi faire de l'adresse. Le score et le détail des contrôles disent pourquoi.

Authentification

L'authentification passe par l'en-tête Authorization, avec le schéma Bearer, pour une clé API comme pour un jeton de session. L'en-tête X-API-Key n'est jamais lu par le serveur. Une clé de production commence par un préfixe distinct de celui d'une clé de test, ce qui rend les deux environnements impossibles à confondre.

L'authentification passe par l'en-tête Authorization, avec le schéma Bearer, pour une clé API comme pour un jeton de session. L'en-tête X-API-Key n'est jamais lu.

Requête
curl -X POST https://api.yeswecheck.fr/v2/email/validate \
  -H "Authorization: Bearer $YESWECHECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","smtp":true}'

Une clé de production porte le préfixe ywc_live_, une clé de test le préfixe ywc_test_.

Ce que renvoie l'API

La réponse porte un statut global, un score et le détail contrôle par contrôle. Chaque contrôle rend son propre résultat, son propre score et un message lisible. Les métadonnées indiquent le nombre de crédits débités par l'appel. Un client peut donc décider sur le statut seul, ou remonter jusqu'au signal exact qui l'a produit.

result
Le statut global : la seule valeur nécessaire pour accepter, refuser ou mettre de côté l'adresse.
score
La confiance dans ce statut, de 0 à 100. Sous 70, un résultat valide est rendu comme risqué.
features
Un objet par contrôle exécuté, avec son propre résultat, son score et un message lisible.
metadata.credits.used
Ce que l'appel a coûté. Sans vérification SMTP, elle vaut zéro.
Réponse
{
  "result": "valid",
  "score": 100,
  "businessEmail": true,
  "freeProvider": false,
  "disposable": false,
  "alias": false,
  "features": {
    "syntax": {
      "result": "valid",
      "score": 100,
      "message": "Adresse conforme."
    },
    "dns": {
      "result": "valid",
      "score": 100,
      "message": "Le domaine annonce un serveur de messagerie.",
      "details": {
        "primaryMx": "mx.exemple.fr",
        "hasARecord": true
      }
    },
    "smtp": {
      "result": "valid",
      "score": 100,
      "message": "Le serveur destinataire confirme la boîte.",
      "details": {
        "exists": true,
        "canReceiveMail": true,
        "isCatchAll": false,
        "smtpCode": 250
      }
    },
    "disposable": {
      "result": "valid",
      "score": 100,
      "message": "Domaine absent de la base de domaines jetables."
    }
  },
  "metadata": {
    "apiVersion": "v2",
    "credits": {
      "used": 1
    }
  }
}

Cet exemple montre un sous-ensemble de la réponse : la réponse réelle porte un objet par contrôle exécuté. Chaque champ montré ici existe dans le schéma de réponse du serveur, et un test le vérifie à chaque construction du site.

Les 20 contrôles

Chaque adresse soumise traverse vingt contrôles nommés. Dix-neuf s'exécutent en parallèle et n'ont aucun coût : syntaxe, DNS, domaines jetables, typosquatting, comptes de rôle, adresses noreply, santé du domaine. Le vingtième, la vérification SMTP, confirme auprès du serveur destinataire que la boîte existe, et consomme un crédit.

contact@exemple.fr

Avant l'@ : la forme

L'adresse est-elle bien écrite, et désigne-t-elle une personne ?

  • Syntaxe RFC 5322 et normalisation features.syntax
  • Comptes de rôle features.roleAccount
  • Adresses noreply, boîtes que personne ne lit features.noReply
  • Partie locale aléatoire, mesure d'entropie features.randomDetection
  • Vulgarité dans la partie locale features.profanity
  • Sous-adressage et alias features.aliasing

Vos règles

Les adresses et domaines que votre organisation autorise ou refuse.

  • Listes blanche et noire de l'organisation features.listCheck

19 contrôles sans crédit tous sauf la vérification SMTP, sans quota

Après l'@ : le domaine

Peut-il recevoir du courrier, et inspire-t-il confiance ?

Le serveur : la boîte

Seul le serveur du destinataire sait si la boîte existe.

Seul étage facturé : 1 crédit, et seulement si le statut conclut

Une seule réponse resultvalid score100 featuresle détail de chaque contrôle

Les 20 contrôles, rangés selon la partie de l'adresse qu'ils examinent, avec leur champ dans la réponse de l'API. Les contrôles gratuits s'exécutent ensemble ; la vérification SMTP interroge ensuite le serveur du destinataire, et c'est la seule qui peut coûter un crédit.

Chaque contrôle s'active ou se coupe sur la clé API : voir les contrôles dans la documentation.

Paramètres de la requête

Une seule information est obligatoire : l'adresse à analyser. Les autres paramètres activent la vérification SMTP, l'enrichissement d'identité, ou ajustent le délai accordé au serveur destinataire. Sans le paramètre qui demande la vérification SMTP, l'appel n'entraîne jamais de débit, quelle que soit la réponse rendue.

Les 5 paramètres acceptés par l'appel de validation.
ParamètreTypeEffet
emailchaîne, obligatoireAdresse à analyser.
smtpbooléen, facultatifDemande la vérification SMTP de la boîte. C'est le seul paramètre qui peut entraîner un débit de crédit.
enrichmentbooléen, facultatifDemande l'enrichissement d'identité : prénom, nom, genre et âge présumé déduits de la partie locale.
smtpTimeoutentier, facultatifDélai maximal accordé à la session SMTP, en millisecondes. Le serveur n'accepte pas de valeur hors des bornes.
countrychaîne, facultatifPays de référence pour l'estimation d'âge du prénom, en code ISO 3166-1. Sans ce paramètre, le pays est déduit du domaine.
Les 3 points d'entrée publics, appelés avec une clé API ou par le widget.
AppelRôle
POST /v2/email/validateValider une adresse et recevoir le détail des contrôles.
GET /v2/widget/configConfiguration publique d'un widget, lue par le script embarqué.
POST /v2/widget/validateValidation appelée par le widget depuis un site client.

Temps réel et traitement par lots

Le même moteur sert deux usages. En temps réel, une requête porte une adresse et la réponse revient dans l'appel, ce qui convient à un formulaire d'inscription. En traitement par lots, un fichier est déposé depuis la console web, traité de façon asynchrone puis restitué ligne par ligne, ce qui convient au nettoyage d'une base existante. Le traitement par lots n'a pas de point d'entrée REST public.

Temps réel

Une requête, une réponse, la décision est immédiate. C'est le mode du formulaire d'inscription et de la qualification de prospect à la saisie.

Voir le fonctionnement de la validation en temps réel

Traitement par lots

Import en CSV ou en TXT, jusqu'à 500 000 lignes et 15 mégaoctets par fichier. Export en CSV, XLSX, PDF.

Voir le déroulement d'un traitement par lots

Widget de formulaire

Le même moteur, appelé depuis un formulaire, sans écrire de code d'intégration et sans exposer de clé dans la page.

Voir l'intégration du widget dans un formulaire

Le même moteur depuis ChatGPT, Claude ou Le Chat, en conversation

Vérification SMTP

La vérification SMTP ouvre une session avec le serveur destinataire, lui annonce l'expéditeur et le destinataire, puis s'arrête avant d'écrire le message. Aucun courrier n'arrive dans la boîte analysée. C'est le seul contrôle facturé, et il ne l'est que lorsque le serveur permet réellement de conclure.

La vérification SMTP ouvre une session avec le serveur destinataire, lui annonce l'expéditeur et le destinataire, puis s'arrête avant d'écrire le message. Aucun courrier n'arrive dans la boîte analysée, et la personne dont l'adresse est vérifiée ne reçoit rien.

Quand la sonde SMTP a réellement dialogué avec le serveur, son résultat fait foi. Les autres contrôles peuvent dégrader un résultat en « risky », ils ne peuvent jamais transformer un refus du serveur en acceptation.

Comprendre la vérification SMTP

Score et statuts

Chaque adresse reçoit un statut parmi quatre et un score de zéro à cent. Le statut dit ce qu'il faut faire de l'adresse, le score dit avec quelle confiance. Un résultat techniquement acceptable dont le score descend sous le seuil de dégradation est rendu comme risqué plutôt que comme valide.

Les 4 statuts, leur définition et la décision qu'ils appellent.
StatutDéfinitionDécision
validL'adresse existe et le serveur destinataire accepte de la recevoir. Quand la vérification SMTP est demandée, ce statut n'est rendu que si le serveur a confirmé la boîte.Accepter l'adresse.
invalidL'adresse ne peut pas recevoir de message : syntaxe non conforme, domaine sans enregistrement MX, boîte refusée par le serveur, ou adresse présente en liste noire de l'organisation.Rejeter l'adresse, elle produira un rebond définitif.
riskyL'adresse est techniquement acceptable mais porte un signal de risque : domaine jetable, domaine malveillant, domaine typosquatté, adresse noreply, ou score global inférieur au seuil de dégradation.Accepter sous condition, ou écarter selon la politique métier configurée.
unknownLe serveur destinataire n'a pas permis de conclure : domaine catch-all, temporisation greylisting ou serveur injoignable.Ne pas trancher sur ce seul résultat. Aucun crédit n'est débité.

Le score est rendu sur une échelle de 0 à 100. Sous 70, un résultat technique valide est dégradé en résultat risqué.

Lire la définition des statuts et du score

Codes de réponse à traiter

Une intégration robuste distingue quatre situations à traiter : le jeton refusé, le solde de crédits à recharger, le paramètre hors bornes et le plafond de la clé atteint. Chacune appelle une action simple et documentée. Un solde à zéro, en particulier, laisse accessibles les dix-neuf contrôles gratuits.

Les 5 codes de réponse qu'une intégration doit traiter.
CodeSituationCe qu'il faut en faire
200SuccèsLa validation a abouti, le corps porte le résultat complet.
401Non authentifiéL'en-tête Authorization est absent, mal formé, ou la clé a été révoquée.
402Crédits épuisésLa vérification SMTP a été demandée alors que le solde est nul. Les autres contrôles restent accessibles en retirant le paramètre smtp.
422Requête invalideUn paramètre ne respecte pas son type ou ses bornes. Le corps liste les champs fautifs.
429Plafond atteintLe plafond de la clé API est atteint. Le corps précise la fenêtre concernée.

Où sont traitées les adresses

YesWeCheck héberge ses données en France, chez OVHcloud. Aucun message n'est envoyé au destinataire pendant la vérification. Les adresses enregistrées sont chiffrées au repos.

Données hébergées en France, par OVHcloud.

Ce que coûte un appel

La structure de coût tient en une phrase : un crédit est débité si et seulement si la vérification SMTP a été demandée et que le statut final permet de conclure. Les dix-neuf autres contrôles s'exécutent sans quota. Cent vérifications SMTP sont offertes une fois, à l'inscription, sans carte bancaire.

Un crédit est débité si et seulement si la vérification SMTP a été demandée et que le statut final n'est pas « unknown ».

Les 3 formules mensuelles, en euros HT.
FormulePrix mensuelVérifications SMTP incluses
FreeGratuitAucune allocation, crédits à acheter en pack
Starter29 euros HT25 000 par mois
Pro99 euros HT100 000 par mois
Les 5 cas dans lesquels aucun crédit n'est débité.
CasCe que fait le moteur
La vérification SMTP n'a pas été demandéeL'appel porte « smtp: false ». Les dix-neuf autres contrôles s'exécutent sans quota.
L'adresse figure en liste blanche de l'organisationLe SMTP est court-circuité, la liste tranche.
L'adresse figure en liste noire de l'organisationLe SMTP est court-circuité, la liste tranche.
Le statut final est « unknown »En temps réel, aucun débit n'a lieu. En traitement par lots, ces adresses sont recréditées automatiquement à la clôture du fichier.
Le fichier est traité en mode auditLe mode audit ne débite aucun crédit, y compris pour l'échantillon qu'il vérifie en SMTP.

Les crédits achetés en pack n'expirent pas. Les crédits mensuels d'un abonnement ne sont pas reportables d'un mois sur l'autre.

100 vérifications SMTP sont créditées une fois à l'inscription. Les 19 autres contrôles ne consomment jamais de crédit.

Des réponses claires, même dans les cas difficiles

Certains serveurs ne laissent pas trancher : un domaine qui accepte toutes les adresses, ou un serveur qui temporise. L'API ne devine pas à votre place : elle rend un statut indéterminé, en nomme la raison, et ne facture rien. Vous décidez en connaissance de cause, et vous ne payez que les réponses utiles.

Commencer

Créer un compte suffit pour obtenir une clé API et cent vérifications SMTP offertes. Aucune carte bancaire n'est demandée. La documentation publie les schémas de réponse, les codes d'erreur et les exemples d'intégration par langage. Tant que la vérification SMTP n'est pas demandée, aucun crédit n'est consommé.