Valider une adresse depuis un serveur
Cas d'usage typiques : inscription, création de compte client, saisie d'un contact dans un CRM, prise de commande. Votre serveur reçoit l'adresse, appelle YesWeCheck et décide.
POST/v2/email/validate· clé APIChoisir la clé
| Besoin | Réglage de la clé |
|---|---|
| Filtrer les fautes, jetables et domaines morts, sans coût | SMTP désactivé |
| Confirmer que la boîte existe | SMTP activé, avec un plafond de crédits |
| Formulaire public à fort trafic | Préférez le widget, conçu pour l'anti-abus |
Un client minimal
- TypeScript
- Python
- PHP
ywc.ts
type Verdict = 'valid' | 'risky' | 'invalid' | 'unknown';
interface Feature<D = Record<string, unknown>> {
result: 'valid' | 'invalid' | 'unknown';
score: number;
message: string;
reasonCode?: string;
details?: D;
}
export interface ValidationResponse {
result: Verdict;
score: number;
freeProvider: boolean;
businessEmail: boolean;
disposable: boolean;
alias: boolean;
finalDecision: 'accepted' | 'rejected';
policy: { decision: 'accepted' | 'rejected'; reasons: string[]; rejectedByClientConfig: boolean };
warnings?: { code: string; severity: 'info' | 'warning' | 'error'; message: string; data?: Record<string, unknown> }[];
features: {
syntax: Feature;
dns: Feature;
smtp?: Feature;
typoDomain?: Feature<{ suggestedDomain?: string; suggestedEmail?: string }>;
typoCorrection?: { correctedDomain: string; correctedEmail?: string };
[name: string]: unknown;
};
metadata: { requestId: string; processingTime: number; credits: { used: number; remaining: number } };
}
export async function validateEmail(email: string): Promise<ValidationResponse> {
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 }),
signal: AbortSignal.timeout(30_000),
});
if (!res.ok) {
const body = await res.text();
throw new YwcError(res.status, body, res.headers.get('retry-after'));
}
return res.json();
}
export class YwcError extends Error {
constructor(readonly status: number, readonly body: string, readonly retryAfter: string | null) {
super(`YesWeCheck ${status}`);
}
}
ywc.py
import os
import requests
class YwcError(Exception):
def __init__(self, status, body, retry_after=None):
super().__init__(f"YesWeCheck {status}")
self.status, self.body, self.retry_after = status, body, retry_after
def validate_email(email: str) -> dict:
res = requests.post(
"https://api.yeswecheck.fr/v2/email/validate",
headers={"Authorization": f"Bearer {os.environ['YWC_API_KEY']}"},
json={"email": email},
timeout=30,
)
if not res.ok:
raise YwcError(res.status_code, res.text, res.headers.get("Retry-After"))
return res.json()
ywc.php
function ywc_validate_email(string $email): array
{
$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]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("YesWeCheck $status: $body");
}
return json_decode($body, true);
}
Réponse en texte brut sur certains 429
Le limiteur de débit par IP répond en texte brut, pas en JSON. Lisez le corps d'une erreur comme du texte, puis tentez de le décoder. Voir Codes d'erreur.
Une logique de décision complète
decide.ts
import type { ValidationResponse } from './ywc';
type Decision =
| { action: 'accept' }
| { action: 'accept_with_warning'; reason: string }
| { action: 'suggest'; email: string }
| { action: 'reject'; reason: string };
export function decide(r: ValidationResponse): Decision {
// 1. Votre politique de validation peut refuser une adresse livrable.
// Elle n'évalue que ses propres règles : un `invalid` reste à traiter plus bas.
if (r.finalDecision === 'rejected') {
return { action: 'reject', reason: r.policy.reasons.join(', ') };
}
// 2. Correction : d'abord l'adresse corrigée vérifiée, sinon la suggestion.
// Si l'adresse saisie est valide, la faute n'est qu'une information.
if (r.result !== 'valid') {
const corrected =
r.features.typoCorrection?.correctedEmail ??
r.features.typoDomain?.details?.suggestedEmail;
if (corrected) return { action: 'suggest', email: corrected };
}
switch (r.result) {
case 'valid':
return { action: 'accept' };
case 'invalid':
return { action: 'reject', reason: 'Adresse non délivrable' };
case 'risky':
return r.disposable
? { action: 'reject', reason: 'Les adresses temporaires ne sont pas acceptées' }
: { action: 'accept_with_warning', reason: 'Adresse à risque' };
case 'unknown':
// Serveur non concluant (accept-all, greylisting) : ne bloquez pas un vrai client.
return { action: 'accept_with_warning', reason: 'Adresse non confirmée' };
}
}
Adaptez les branches risky et unknown à votre contexte : un formulaire de paiement peut refuser risky, une newsletter peut tout accepter sauf invalid.
Gérer les erreurs sans bloquer vos utilisateurs
La validation ne doit jamais empêcher un client légitime de s'inscrire parce que l'API est momentanément indisponible.
| Statut | Cause | Réaction conseillée |
|---|---|---|
400 | Corps invalide (adresse mal formée pour le validateur, champ inconnu) | Corriger l'appel ; ne pas réessayer |
401 | Clé absente, invalide ou révoquée | Alerter l'équipe technique ; accepter l'adresse en mode dégradé |
402 | Plus de crédits pour le SMTP | Recharger ; en attendant, accepter ou utiliser une clé sans SMTP |
403 | IP ou origine non autorisée pour la clé | Corriger les restrictions de la clé |
429 | Débit ou plafond de crédits de la clé atteint | Attendre Retry-After secondes ; ne pas boucler |
5xx, délai dépassé | Incident | Une nouvelle tentative après quelques secondes, puis mode dégradé |
try {
const verdict = await validateEmail(email);
return decide(verdict);
} catch (e) {
// Mode dégradé : on accepte, on marque l'adresse pour une revalidation ultérieure.
logger.warn('YesWeCheck indisponible', e);
return { action: 'accept' as const };
}
Conseils
- Validez au bon moment : à la soumission du formulaire côté serveur, pas à chaque frappe. Pour la saisie en direct, utilisez le widget ou les endpoints d'autocomplétion.
- Conservez
metadata.requestIdavec l'adresse : c'est la référence à donner au support. - Ne revalidez pas en boucle la même adresse : un résultat valid ou invalid reste fiable plusieurs jours ; un unknown mérite une nouvelle tentative plus tard.
- Plus de quelques centaines d'adresses d'un coup : passez par le traitement par lots.