Справочник API: эндпоинт /validate

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

Запрос

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

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

Ответ

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

{
  "value": "someone@example.com",
  "result": {
    "status": "Good",
    "detail": "Mailbox accepts mail"
  },
  "suggest": ["someone@example.net"],
  "risk": {
    "gmailDotTrick": true,
    "aliasOf": "someone@gmail.com",
    "seenVariants": 2
  }
}

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

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

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

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

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

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

Рядом с result в ответе может появиться два дополнительных поля — в зависимости от адреса:

• suggest — вероятное исправление, когда домен похож на опечатку доверенного провайдера. См. Подсказки при опечатках.
• risk — сигнал злоупотребления, когда один ящик Gmail был отправлен под несколькими написаниями с точками. См. Gmail dot trick.