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.
-
Créer une clé
Un compte gratuit donne une clé API et 100 vérifications SMTP offertes, sans carte bancaire.
-
Envoyer l'adresse
Un appel
POST /v2/email/validate, avec l'en-têteAuthorization: Bearer. Le paramètresmtpdécide si la vérification facturée s'exécute. -
Décider sur le statut
Le champ
resultdit quoi faire de l'adresse. Lescoreet 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.
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.
{
"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 ?
- Enregistrements MX du domaine
features.dns. details. mxRecords - Enregistrements A et AAAA de repli
features.dns. details. hasARecord - Domaines jetables
features.disposable - Domaines malveillants
features.maliciousDomains - Typosquatting de domaine
features.typosquat - Faute de frappe de domaine, avec correction proposée
features.typoDomain - Adresse professionnelle ou grand public
businessEmail, freeProvider - Enregistrement SPF du domaine
features.domainHealth. checks. spf - Politique DMARC du domaine
features.domainHealth. checks. dmarc - Enregistrement BIMI du domaine
features.domainHealth. checks. bimi - Âge du domaine et titulaire, via RDAP
features.domainHealth. checks. age, . registrant
Le serveur : la boîte
Seul le serveur du destinataire sait si la boîte existe.
- Vérification SMTP de la boîte
features.smtp - Détection catch-all et accept-all
features.smtp. details. isCatchAll
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
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.
| Paramètre | Type | Effet |
|---|---|---|
| chaîne, obligatoire | Adresse à analyser. | |
| smtp | booléen, facultatif | Demande la vérification SMTP de la boîte. C'est le seul paramètre qui peut entraîner un débit de crédit. |
| enrichment | booléen, facultatif | Demande l'enrichissement d'identité : prénom, nom, genre et âge présumé déduits de la partie locale. |
| smtpTimeout | entier, facultatif | Délai maximal accordé à la session SMTP, en millisecondes. Le serveur n'accepte pas de valeur hors des bornes. |
| country | chaîne, facultatif | Pays 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. |
| Appel | Rôle |
|---|---|
| POST /v2/email/validate | Valider une adresse et recevoir le détail des contrôles. |
| GET /v2/widget/config | Configuration publique d'un widget, lue par le script embarqué. |
| POST /v2/widget/validate | Validation 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.
Traitement par lots
Import en CSV ou en TXT, jusqu'à 500 000 lignes et 15 mégaoctets par fichier. Export en CSV, XLSX, PDF.
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.
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.
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.
| Statut | Définition | Décision |
|---|---|---|
| valid | L'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. |
| invalid | L'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. |
| risky | L'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. |
| unknown | Le 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é.
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.
| Code | Situation | Ce qu'il faut en faire |
|---|---|---|
| 200 | Succès | La validation a abouti, le corps porte le résultat complet. |
| 401 | Non authentifié | L'en-tête Authorization est absent, mal formé, ou la clé a été révoquée. |
| 402 | Crédits épuisés | La 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. |
| 422 | Requête invalide | Un paramètre ne respecte pas son type ou ses bornes. Le corps liste les champs fautifs. |
| 429 | Plafond atteint | Le 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 ».
| Formule | Prix mensuel | Vérifications SMTP incluses |
|---|---|---|
| Free | Gratuit | Aucune allocation, crédits à acheter en pack |
| Starter | 29 euros HT | 25 000 par mois |
| Pro | 99 euros HT | 100 000 par mois |
| Cas | Ce que fait le moteur |
|---|---|
| La vérification SMTP n'a pas été demandée | L'appel porte « smtp: false ». Les dix-neuf autres contrôles s'exécutent sans quota. |
| L'adresse figure en liste blanche de l'organisation | Le SMTP est court-circuité, la liste tranche. |
| L'adresse figure en liste noire de l'organisation | Le 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 audit | Le 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.
- Les domaines catch-all. Un domaine configuré pour accepter toutes les adresses est repéré et signalé dans la réponse. Le statut rendu est indéterminé, et aucun crédit n'est débité.
- Les temporisations. Un serveur qui demande de repasser plus tard obtient un statut indéterminé plutôt qu'un verdict deviné, sans facturation. En traitement par lots, une seconde passe va chercher la réponse ferme.
- Une base toujours à jour. Revalider une liste avant chaque campagne importante se fait en quelques clics, et les contrôles gratuits ne consomment aucun crédit.
- Le temps de réponse. Sans vérification SMTP, la réponse est immédiate. Avec vérification SMTP, elle arrive dès que le serveur destinataire a répondu, et le délai maximal accordé se règle à chaque appel.
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é.