Проверяйте email-адреса через REST API

Отправьте запрос со своего сервера

Создайте API-ключ в аккаунте и храните его на своем сервере: ключ не должен попадать в код, который получает браузер. Передайте email-адрес в теле запроса и ключ в заголовке авторизации. В примере используется полная проверка, выбранная по умолчанию.

Заголовок Idempotency-Key связывает запрос с одной операцией. Если после сетевой ошибки или повторной отправки формы нужно повторить запрос, используйте прежний ключ для того же адреса и глубины проверки. В пределах срока действия ключа это позволяет получить исходный результат без повторной проверки и списания кредитов.

curl -sS https://api.emvero.tech/v1/verifications \
  -H "Authorization: Bearer emv_your_credential" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-8f21c0" \
  -d '{"email":"ada@example.com"}'

Ниже приведен условный пример ответа с HTTP-кодом 200. Адрес, идентификатор и значения полей служат для иллюстрации; реальная проверка example.com не выполнялась.

{
  "id": "5f0b6f3e-1a4c-4a1f-9d2e-8f7b3c2a1d90",
  "email": "ada@example.com",
  "normalized": { "domain": "example.com", "ascii_domain": "example.com" },
  "status": "deliverable",
  "confidence": 0.92,
  "action": "allow",
  "checks": {
    "syntax": "valid",
    "domain": "valid",
    "mail_routing": "valid",
    "smtp": "accepted",
    "accept_all": "no",
    "disposable": false,
    "role_account": false,
    "public_provider": false,
    "smtp_utf8_required": false
  },
  "reason_codes": ["MX_FOUND", "SMTP_RCPT_ACCEPTED"]
}

HTTP-код 200 означает, что API вернул результат проверки. Сам адрес при этом может получить статус undeliverable. Ошибки HTTP относятся к запросу, авторизации, балансу, лимитам или работе сервиса; по ним нельзя судить о состоянии адреса.

Как читать результат проверки

Поле status описывает результат: deliverable, risky, undeliverable или unknown. Поле action рекомендует, как обработать адрес: принять (allow), продолжить с подтверждением почты (allow_with_email_confirmation) или отклонить (reject).

Читайте эти поля вместе с причинами. Например, одноразовый ящик может принимать письма и получить risky с рекомендацией allow. Признак риска сам по себе не означает техническую невозможность доставки, поэтому не определяйте действие только по статусу.

checks содержит результаты отдельных этапов и признаки риска. В reason_codes перечислены коды причин: например, DISPOSABLE_DOMAIN указывает на провайдера временной почты, а SMTP_RCPT_ACCEPTED означает, что почтовый сервер принял указанного получателя.

confidence оценивает силу свидетельств по шкале от 0 до 1. Это не вероятность существования ящика или попадания письма во «Входящие». На странице проверки отдельного адреса объясняем, что можно установить по формату адреса, почтовому маршруту и ответу сервера по SMTP.

Дождитесь результата, если API вернул pending

Если сведения от почтового сервера не получены за время запроса, полная проверка может вернуть pending. Проверка еще выполняется; это не пятый конечный статус. В ответе есть уже собранные данные, идентификатор id и интервал до следующего запроса retry_after_ms в миллисекундах. Ниже показана только часть условного ответа:

{
  "id": "5f0b6f3e-1a4c-4a1f-9d2e-8f7b3c2a1d90",
  "status": "pending",
  "retry_after_ms": 2000
}

Подождите указанный интервал и отправьте GET /v1/verifications/{id} с тем же Bearer-ключом. Если ответ все еще содержит pending, повторите опрос после очередного интервала. Завершите опрос, когда получите один из четырех конечных статусов. API не отправляет уведомлений о готовности результата (callback).

Задайте предел ожидания в своем приложении. Если время истекло, примените заранее выбранное правило, например продолжите регистрацию с подтверждением почты. Истечение вашего срока ожидания не означает, что API вернул unknown или признал адрес недоставляемым. Подробнее об опросе читайте в документации по незавершенным проверкам.

Выберите глубину проверки и обработайте ошибки HTTP

Если не передать variant, API использует full: проверяет формат адреса, домен и почтовый маршрут, а затем может получить сведения о ящике по SMTP. Значение "variant":"domain" ограничивает проверку форматом адреса, данными DNS и почтовым маршрутом. SMTP-соединение при этом не открывается.

Обе глубины доступны через один эндпоинт и возвращают одинаковый набор полей. Выбирайте глубину по задаче: проверка домена не устанавливает существование конкретного ящика. Полная проверка может собрать больше сведений, но тоже возвращает unknown, если их недостаточно.

Обработку ошибок HTTP предусмотрите отдельно от обработки статусов адреса. При 400 исправьте запрос, при 401 проверьте ключ, при 402 пополните баланс кредитов. При 429 снизьте частоту запросов и соблюдайте интервал из Retry-After, если заголовок есть в ответе. Ответ 5xx указывает на проблему сервиса и не дает оснований отклонить адрес.

При повторе той же операции сохраняйте ключ идемпотентности. Быстрый старт показывает, как подключить API, а справочник ошибок объясняет коды ответов.

Для регистрации и других форм используйте сценарий проверки в реальном времени. Для готового списка организуйте массовую проверку в своей системе: отправьте по одному запросу на каждый адрес и сохраните результаты. В Emvero нет загрузки CSV через сайт и отдельного batch-эндпоинта.