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",
"normalized": "someone@example.com",
"result": {
"status": "Good",
"detail": "Mailbox accepts mail"
},
"suggest": ["someone@example.net"],
"risk": {
"gmailDotTrick": true,
"aliasOf": "someone@gmail.com",
"seenVariants": 2,
"suspicious": true
}
}В этом примере показаны все поля, которые может вернуть эндпоинт. value и normalized присутствуют всегда — normalized просто повторяет адрес в нижнем регистре, если менять было нечего. suggest и risk присутствуют только тогда, когда это уместно, а два поля внутри risk независимы друг от друга — подробнее ниже.
normalized — это каноническая форма, к которой CleanContact привёл адрес: в нижнем регистре, с применёнными алиасами доменов и правилами для локальной части конкретных провайдеров. Как именно она вычисляется, описано в статье Нормализация email.
Поле status — одно из:
- Good — адрес существует и принимает почту.
- Bad — адрес не существует или отклонён.
- Unknown — однозначного ответа не получено вовремя.
Коды состояния
- 200 — проверка завершена; смотрите result.status для вердикта.
- 400 — параметр email отсутствует или некорректен.
- 401 — ключ API отсутствует, неизвестен или неактивен.
- 429 — слишком много запросов; снизьте темп и повторите.
Дополнительные поля ответа
В зависимости от адреса рядом с result может появиться два дополнительных элемента: поле suggest и объект risk с одним или обоими сигналами злоупотребления ниже.
- suggest — вероятное исправление, когда домен похож на опечатку доверенного провайдера. См. Подсказки при опечатках.
- risk.gmailDotTrick — сигнал злоупотребления, когда один адрес Gmail был отправлен под несколькими написаниями с точками. См. Gmail dot trick.
- risk.suspicious — сигнал злоупотребления, когда адрес не похож на написанный человеком. См. Подозрительные адреса.