Démarrage rapide
De la création du compte à la lecture d'un premier verdict, en quatre étapes.
1. Créer une clé API
- Créez un compte sur app.yeswecheck.fr. Le plan Free inclut 100 crédits de bienvenue, sans carte bancaire.
- 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.
- 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).
- 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 :
YWC_API_KEY=ywc_live_xxxxxxxxxxxxxxxxxxxxxxxx
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
- Node.js
- Python
- PHP
curl https://api.yeswecheck.fr/v2/email/validate \
-H "Authorization: Bearer $YWC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]"}'
const res = await fetch('https://api.yeswecheck.fr/v2/email/validate', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.YWC_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email: '[email protected]' }),
});
if (!res.ok) throw new Error(`YesWeCheck ${res.status}`);
const verdict = await res.json();
console.log(verdict.result, verdict.score); // "valid" 100
import os
import requests
res = requests.post(
"https://api.yeswecheck.fr/v2/email/validate",
headers={"Authorization": f"Bearer {os.environ['YWC_API_KEY']}"},
json={"email": "[email protected]"},
timeout=30,
)
res.raise_for_status()
verdict = res.json()
print(verdict["result"], verdict["score"])
$ch = curl_init('https://api.yeswecheck.fr/v2/email/validate');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('YWC_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['email' => '[email protected]']),
]);
$verdict = json_decode(curl_exec($ch), true);
echo $verdict['result'] . ' ' . $verdict['score'];
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 :
| Champ | Contenu |
|---|---|
result | Le verdict : valid, risky, invalid ou unknown. |
score | La confiance, de 0 à 100. |
warnings | Présent seulement si un signal de risque a été relevé (jetable, faute de frappe, domaine piège…). |
resultUne 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
| Verdict | Signification | Action conseillée |
|---|---|---|
| valid | Adresse délivrable, sans signal de risque notable | Accepter |
| risky | Délivrable mais risquée : jetable, domaine piège ou malveillant, adresse noreply, ou score sous 70 | Accepter avec réserve, ou refuser selon votre contexte |
| invalid | Syntaxe fausse, domaine sans serveur de messagerie, boîte refusée par le SMTP, ou adresse en liste noire | Refuser |
| unknown | Le 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.