Aller au contenu principal

Démarrage rapide

De la création du compte à la lecture d'un premier verdict, en quatre étapes.

1. Créer une clé API​

  1. Créez un compte sur app.yeswecheck.fr. Le plan Free inclut 100 crédits de bienvenue, sans carte bancaire.
  2. Ouvrez Clés API dans le menu du tableau de bord, puis créez une clé. Seuls les rôles owner et admin de l'organisation peuvent le faire.
  3. Choisissez les contrôles actifs. Le SMTP est désactivé par défaut : activez-le si vous voulez confirmer l'existence des boîtes (1 crédit par vérification conclusive).
  4. Copiez la clé immédiatement : elle n'est affichée qu'une seule fois.

Rangez-la dans une variable d'environnement de votre serveur, jamais dans le code ni dans une page web :

.env
YWC_API_KEY=ywc_live_xxxxxxxxxxxxxxxxxxxxxxxx
Tester sans dépenser

Une clé sans SMTP ne consomme aucun crédit : syntaxe, DNS, jetables, fautes de frappe et domaines pièges sont gratuits. Il n'existe pas d'environnement bac à sable distinct ; une clé ywc_test_… se comporte exactement comme une clé ywc_live_…, elle sert seulement à séparer vos usages.

2. Valider une adresse​

curl https://api.yeswecheck.fr/v2/email/validate \
-H "Authorization: Bearer $YWC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]"}'

Le corps de la requête ne contient que l'adresse. Les champs facultatifs (country, smtpTimeout) sont décrits dans la référence ; tout champ inconnu est refusé avec une erreur 400.

3. Lire la réponse​

Extrait d'une réponse, avec une clé dont le SMTP est activé et une boîte qui existe :

{
"result": "valid",
"score": 100,
"freeProvider": true,
"businessEmail": false,
"disposable": false,
"alias": false,
"finalDecision": "accepted",
"features": {
"syntax": { "result": "valid", "score": 100, "message": "…", "details": { "normalizedEmail": "[email protected]" } },
"dns": { "result": "valid", "score": 100, "reasonCode": "MX_FOUND", "message": "…" },
"smtp": { "result": "valid", "score": 100, "reasonCode": "MAILBOX_EXISTS", "message": "…" },
"disposable": { "result": "valid", "score": 100, "message": "…" },
"typoDomain": { "result": "valid", "score": 100, "message": "…" }
},
"metadata": {
"requestId": "0192f6b4-…",
"timestamp": "2026-10-15T09:12:44.512Z",
"processingTime": 1840,
"credits": { "used": 1, "remaining": 4819 },
"apiVersion": "2.0"
}
}

Trois champs suffisent pour décider :

ChampContenu
resultLe verdict : valid, risky, invalid ou unknown.
scoreLa confiance, de 0 à 100.
warningsPrésent seulement si un signal de risque a été relevé (jetable, faute de frappe, domaine piège…).
Le verdict s'appelle result

Une ancienne version de cette documentation parlait d'un champ status et de blocs typo, smtp.deliverable ou metadata.creditsUsed. Ils n'ont jamais existé dans l'API v2.

Le détail de chaque champ est dans Anatomie de la réponse.

4. Décider​

VerdictSignificationAction conseillée
validAdresse délivrable, sans signal de risque notableAccepter
riskyDélivrable mais risquée : jetable, domaine piège ou malveillant, adresse noreply, ou score sous 70Accepter avec réserve, ou refuser selon votre contexte
invalidSyntaxe fausse, domaine sans serveur de messagerie, boîte refusée par le SMTP, ou adresse en liste noireRefuser
unknownLe serveur n'a pas permis de conclure : domaine accept-all, greylisting, délai dépasséAccepter avec prudence, ne pas facturer de crédit

La page Verdicts et score détaille comment chaque verdict est obtenu.

Et ensuite​