Autocomplétion, fautes de frappe et enrichissement

Ces endpoints aident à bien saisir une adresse avant de la valider. Ils sont rapides, ne déclenchent jamais de SMTP et ne consomment aucun crédit.

Endpoint	Usage	Authentification	Limite
POST /v2/email/suggest/domain	Proposer des domaines après le @	Aucune	60 requêtes/min/IP
POST /v2/email/suggest/typo-domain	Détecter une faute dans le domaine	Aucune	60 requêtes/min/IP
GET /v2/email/suggest/domain/countries	Lister les pays couverts	Clé API	—
POST /v2/email/suggest/localpart	Générer prenom.nom, p.nom…	Clé API	—
POST /v2/email/suggest-firstname	Autocompléter un prénom	Clé API	—
POST /v2/email/suggest-lastname	Autocompléter un nom	Clé API	—
POST /v2/email/enrich	Déduire prénom, nom, genre, âge d'une adresse	Clé API	—

Les deux premiers sont publics : ils peuvent être appelés depuis un navigateur, sur n'importe quel site.

Suggérer un domaine

POST/v2/email/suggest/domain· public

curl https://api.yeswecheck.fr/v2/email/suggest/domain \
  -H "Content-Type: application/json" \
  -d '{"country": "FR", "partial": "ho", "count": 3}'

{
  "country": "FR",
  "count": 3,
  "type": null,
  "partial": "ho",
  "suggestions": [
    { "domain": "hotmail.fr", "provider": "Microsoft", "type": "webmail", "popularity": 13, "score": 88.3 },
    { "domain": "yahoo.fr", "provider": "Yahoo", "type": "webmail", "popularity": 11, "score": 54.2 }
  ],
  "total": 2
}

Champ	Description
country	Code pays (FR, DE, BE…) ou GLOBAL (défaut).
partial	Ce que l'utilisateur a tapé après le @. Filtre et classe les domaines.
count	Nombre maximal de suggestions (défaut 15). maxResults est un alias ancien.
type	Filtre : webmail, isp, professional, secure.

Détecter une faute de frappe

POST/v2/email/suggest/typo-domain· public

Même moteur et même normalisation que la validation : les deux surfaces ne peuvent pas proposer deux corrections différentes pour la même adresse.

curl https://api.yeswecheck.fr/v2/email/suggest/typo-domain \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

{
  "input": "[email protected]",
  "inputDomain": "gmial.com",
  "detected": true,
  "suggestedDomain": "gmail.com",
  "suggestedEmail": "[email protected]",
  "score": 100,
  "message": "Possible typo in domain. Did you mean [email protected]?",
  "reasonCode": "TYPO_DETECTED",
  "details": {
    "suggestedDomain": "gmail.com",
    "suggestedEmail": "[email protected]",
    "typoType": "character_swap",
    "similarityScore": 90,
    "detectionMethod": "list"
  }
}

• Envoyez email (adresse complète) ou domain (domaine seul ; input est un alias). Sans @, suggestedEmail vaut null.
• detected: false : aucune faute, suggestedDomain vaut null.
• details.detectionMethod dit d'où vient la correction : list (référentiel de corrections), typosquat (domaine piège connu) ou algorithm (moteur de distance). Pour algorithm, details.patterns, details.transformations et details.difficulty expliquent la correction.
• Pas de suggestion quand le domaine visé ne reçoit plus de courrier, ni pour un domaine jetable.

Générer des parties locales

POST/v2/email/suggest/localpart?domain=exemple.fr· clé API

curl "https://api.yeswecheck.fr/v2/email/suggest/localpart?domain=exemple.fr" \
  -H "Authorization: Bearer $YWC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Jean", "lastName": "Dupont", "maxResults": 3}'

{
  "firstName": "Jean",
  "lastName": "Dupont",
  "domain": "exemple.fr",
  "partial": null,
  "suggestions": [
    { "localpart": "jean.dupont", "pattern": "prenom.nom", "popularity": 10, "email": "[email protected]" },
    { "localpart": "jeandupont", "pattern": "prenomnom", "popularity": 9, "email": "[email protected]" },
    { "localpart": "j.dupont", "pattern": "p.nom", "popularity": 9, "email": "[email protected]" }
  ],
  "total": 3
}

firstName et lastName sont obligatoires. includeNumbers: true ajoute des variantes avec chiffres, partial filtre selon ce qui a déjà été tapé. Le paramètre de requête domain ajoute le champ email à chaque suggestion. Ces adresses sont des hypothèses : validez celle que vous retenez.

Autocompléter un prénom ou un nom

POST/v2/email/suggest-firstname· clé API

curl https://api.yeswecheck.fr/v2/email/suggest-firstname \
  -H "Authorization: Bearer $YWC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "je", "limit": 2}'

{
  "query": "je",
  "suggestions": [
    { "firstName": "Jean", "source": "insee", "popularity": 510000, "gender": "M", "score": 198.2 },
    { "firstName": "Jessica", "source": "international", "popularity": 65000, "gender": "F", "score": 164.4 }
  ],
  "total": 2
}

POST /v2/email/suggest-lastname fonctionne de la même façon et renvoie lastName au lieu de firstName. query est obligatoire (partial et input sont des alias), limit va de 1 à 20 (défaut 10).

Enrichir une adresse

POST/v2/email/enrich· clé API

L'enrichissement de la validation, sans la validation.

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

{
  "result": "valid",
  "score": 95,
  "message": "…",
  "details": {
    "firstName": "Jean",
    "firstNameScore": 95,
    "lastName": "Dupont",
    "lastNameScore": 90,
    "gender": "male",
    "genderScore": 98,
    "presumedAge": 62,
    "presumedAgeRange": "55-64",
    "presumedAgeScore": 75,
    "ageBasis": { "country": "FR", "resolvedFrom": "param", "source": "insee" },
    "status": "success"
  }
}

Valeurs données à titre d'exemple. country est facultatif ; voir l'enrichissement en détail pour le choix du pays de référence.