The CleanContact API is a single authenticated endpoint. Send an address, get a verdict.
Request
Issue a GET request with the address as a query parameter and your API key in the X-API-Key header.
curl -H "X-API-Key: <your-key>" \
"https://api.cleancontact.ru/validate?email=som.e.o.ne@gmail.com"Response
A successful call returns 200 with the address you sent, its normalized canonical form, and a result object.
{
"value": "som.e.o.ne@gmail.com",
"normalized": "someone@gmail.com",
"result": {
"status": "Good",
"detail": "Mailbox accepts mail"
},
"suggest": ["someone@example.net"],
"risk": {
"gmailDotTrick": true,
"aliasOf": "someone@gmail.com",
"seenVariants": 2,
"suspicious": true
},
"humaneness": 0.9811
}This example shows every field the endpoint can return. value and normalized are always present — normalized simply repeats the lowercased address when nothing about it changes. suggest, risk, and humaneness are each present only when relevant, and the two fields inside risk are independent — see below.
normalized is the canonical form CleanContact resolved the address to: lowercased, with known domain aliases and provider-specific local-part rules applied. See Email Normalization for exactly how it is derived.
The status field is one of:
- Good — the mailbox exists and accepts mail.
- Bad — the address does not exist or is rejected.
- Unknown — no definitive answer was available in time.
Status codes
- 200 — validation completed; read result.status for the verdict.
- 400 — the email parameter was missing or malformed.
- 401 — the API key is missing, unknown, or inactive.
- 429 — too many requests; back off and retry.
Optional response fields
Depending on the address, extra fields may appear next to result: suggest, a risk object carrying one or both fraud signals below, and humaneness.
- suggest — a likely correction when the domain looks like a typo of a trusted provider. See Typo Suggestions.
- risk.gmailDotTrick — a fraud signal when a Gmail or Yandex mailbox has been submitted under several spellings (dots on Gmail, dots and hyphens on Yandex). See Gmail Dot Trick.
- risk.suspicious — a fraud signal when the address itself does not look like something a person would type, no history needed. See Suspicious Addresses.
- humaneness — a machine-learning score from 0 to 1 for how human-chosen the address looks, independent of the risk signals above. See Humaneness Score.