Справочник API: сервис /validate

API CleanContact — это единственный эндпоинт с аутентификацией. Отправьте адрес — получите вердикт.

Запрос

Выполните GET-запрос с адресом в параметре строки и вашим ключом API в заголовке X-API-Key.

curl -H "X-API-Key: <ваш-ключ>" \
  "https://api.cleancontact.ru/validate?email=som.e.o.ne@gmail.com"

Ответ

Успешный вызов возвращает 200 с отправленным адресом, его канонической нормализованной формой и объектом результата.

{
  "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
}

В этом примере показаны все поля, которые может вернуть эндпоинт. value и normalized присутствуют всегда — normalized просто повторяет адрес в нижнем регистре, если менять было нечего. suggest, risk и humaneness присутствуют только тогда, когда это уместно, а два поля внутри risk независимы друг от друга — подробнее ниже.

normalized — это каноническая форма, к которой CleanContact привёл адрес: в нижнем регистре, с применёнными алиасами доменов и правилами для локальной части конкретных провайдеров. Как именно она вычисляется, описано в статье Нормализация email.

Поле status — одно из:

• Good — адрес существует и принимает почту.
• Bad — адрес не существует или отклонён.
• Unknown — однозначного ответа не получено вовремя.

Коды состояния

• 200 — проверка завершена; смотрите result.status для вердикта.
• 400 — параметр email отсутствует или некорректен.
• 401 — ключ API отсутствует, неизвестен или неактивен.
• 429 — слишком много запросов; снизьте темп и повторите.

Дополнительные поля ответа

В зависимости от адреса рядом с result могут появиться дополнительные поля: suggest, объект risk с одним или обоими сигналами злоупотребления ниже, и humaneness.

• suggest — вероятное исправление, когда домен похож на опечатку доверенного провайдера. См. Подсказки при опечатках.
• risk.gmailDotTrick — сигнал злоупотребления, когда один адрес Gmail или Яндекса был отправлен под несколькими написаниями (точки в Gmail, точки и дефисы в Яндексе). См. Gmail dot trick.
• risk.suspicious — сигнал злоупотребления, когда адрес не похож на написанный человеком. См. Подозрительные адреса.
• humaneness — оценка от 0 до 1 по шкале машинного обучения, насколько адрес похож на выбранный человеком, независимая от сигналов risk выше. См. Скоринг человечности.