Skip to main content

Autocomplete, typos and enrichment

These endpoints help users enter an address correctly before you verify it. They are fast, never trigger SMTP and consume no credits.

EndpointUseAuthenticationLimit
POST /v2/email/suggest/domainSuggest domains after the @API key or widget60 requests/min/IP
POST /v2/email/suggest/typo-domainDetect a typo in the domainAPI key or widget60 requests/min/IP
GET /v2/email/suggest/domain/countriesList the countries coveredAPI key—
POST /v2/email/suggest/localpartGenerate prenom.nom, p.nom…API key—
POST /v2/email/suggest-firstnameAutocomplete a first nameAPI key—
POST /v2/email/suggest-lastnameAutocomplete a last nameAPI key—
POST /v2/email/enrichInfer first name, last name, gender and age from an addressAPI key—

All of them require a key. For the first two, used while users type in your forms, there are two ways to identify yourself:

  • from your server, with your API key in Authorization: Bearer …;
  • from a web page, with the widget: it sends the widget ID, with no key in the page, and the API checks that the page is served from an allowed domain of the linked widget key.

Each call counts towards the key's call limit, on top of the per-IP limit.

Suggest a domain​

POST/v2/email/suggest/domain· API key
curl https://api.yeswecheck.fr/v2/email/suggest/domain \
-H "Authorization: Bearer $YWC_API_KEY" \
-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
}
FieldDescription
countryCountry code (FR, DE, BE…) or GLOBAL (default).
partialWhat the user typed after the @. Filters and ranks the domains.
countMaximum number of suggestions (default 15). maxResults is a legacy alias.
typeFilter: webmail, isp, professional, secure.

Detect a typo​

POST/v2/email/suggest/typo-domain· API key

Same engine and same normalisation as verification: the two surfaces can never suggest two different corrections for the same address.

curl https://api.yeswecheck.fr/v2/email/suggest/typo-domain \
-H "Authorization: Bearer $YWC_API_KEY" \
-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"
}
}
  • Send email (full address) or domain (domain only; input is an alias). Without an @, suggestedEmail is null.
  • detected: false: no typo, suggestedDomain is null.
  • details.detectionMethod tells you where the correction comes from: list (corrections reference list), typosquat (known trap domain) or algorithm (distance engine). For algorithm, details.patterns, details.transformations and details.difficulty explain the correction.
  • No suggestion when the intended domain no longer receives mail, nor for a disposable domain.

Generate local parts​

POST/v2/email/suggest/localpart?domain=example.com· API key
curl "https://api.yeswecheck.fr/v2/email/suggest/localpart?domain=example.com" \
-H "Authorization: Bearer $YWC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"firstName": "John", "lastName": "Smith", "maxResults": 3}'
{
"firstName": "John",
"lastName": "Smith",
"domain": "example.com",
"partial": null,
"suggestions": [
{ "localpart": "john.smith", "pattern": "prenom.nom", "popularity": 10, "email": "[email protected]" },
{ "localpart": "johnsmith", "pattern": "prenomnom", "popularity": 9, "email": "[email protected]" },
{ "localpart": "j.smith", "pattern": "p.nom", "popularity": 9, "email": "[email protected]" }
],
"total": 3
}

firstName and lastName are required. includeNumbers: true adds variants with numbers, and partial filters on what has already been typed. The domain query parameter adds the email field to each suggestion. These addresses are guesses: verify the one you keep.

Autocomplete a first name or last name​

POST/v2/email/suggest-firstname· API key
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 works the same way and returns lastName instead of firstName. query is required (partial and input are aliases), and limit ranges from 1 to 20 (default 10).

Enrich an address​

POST/v2/email/enrich· API key

The enrichment from verification, without the verification.

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": "John",
"firstNameScore": 95,
"lastName": "Smith",
"lastNameScore": 90,
"gender": "male",
"genderScore": 98,
"presumedAge": 62,
"presumedAgeRange": "55-64",
"presumedAgeScore": 75,
"ageBasis": { "country": "FR", "resolvedFrom": "param", "source": "insee" },
"status": "success"
}
}

Values shown as an example. country is optional; see enrichment in detail for how the reference country is chosen.