Aller au contenu principal

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é API

Choisir la clé​

BesoinRéglage de la clé
Filtrer les fautes, jetables et domaines morts, sans coûtSMTP désactivé
Confirmer que la boîte existeSMTP activé, avec un plafond de crédits
Formulaire public à fort traficPréférez le widget, conçu pour l'anti-abus

Un client minimal​

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}`);
}
}
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.

StatutCauseRéaction conseillée
400Corps invalide (adresse mal formée pour le validateur, champ inconnu)Corriger l'appel ; ne pas réessayer
401Clé absente, invalide ou révoquéeAlerter l'équipe technique ; accepter l'adresse en mode dégradé
402Plus de crédits pour le SMTPRecharger ; en attendant, accepter ou utiliser une clé sans SMTP
403IP ou origine non autorisée pour la cléCorriger les restrictions de la clé
429Débit ou plafond de crédits de la clé atteintAttendre Retry-After secondes ; ne pas boucler
5xx, délai dépasséIncidentUne 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.requestId avec 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.