Документация API

Быстрый старт

Создайте API-ключ в панели, храните его на сервере и передавайте как Bearer-токен. Каждый принятый запрос на проверку расходует один кредит.

Запрос

curl -sS -X POST 'https://api.verifyemail.net/api/v1/verifications' \
  -H 'Authorization: Bearer ve_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"address":"[email protected]"}'

Ответ · HTTP 200

{
  "errcode": 0,
  "address": "[email protected]",
  "is_deliverable": true,
  "status": 250,
  "catch_all": false,
  "disposable": false
}

Аутентификация

Создайте API-ключ в панели: Панель → API-ключи

Полное значение ve_live_… показывается только один раз.

Храните API-ключи в серверных секретах. Не помещайте их в браузерный код, параметры URL, открытые репозитории или доступные клиенту журналы.

Authorization: Bearer ve_live_your_api_key

Проверка адреса

POST/verifications

Тело запроса

Поле	Тип	Обязательно	Описание
address	string	Да	Полный адрес электронной почты.

Поля ответа

Поле	Тип	Описание
errcode	number	0 означает успех; остальные значения обрабатывайте по таблице ошибок.
address	string	Нормализованный адрес электронной почты.
is_deliverable	boolean	Принимает ли принимающий сервер указанного получателя.
status	number \| null	Числовой код ответа SMTP или null, если ответ SMTP не был получен.
catch_all	boolean \| null	Принимает ли домен любого получателя. Null означает отсутствие надёжного вывода.
disposable	boolean	Принадлежит ли адрес домену временной почты.

250 · HTTP 200 · errcode 0

Принимающий сервер принял получателя.

550 · HTTP 200 · errcode 0

Домен или принимающий сервер отклонил получателя.

null · HTTP 422

Адрес недействителен или не может быть проверен.

null · HTTP 503

Надёжный вывод недоступен; повторите попытку позже.

Также доступен следующий GET-эндпоинт. Рекомендуется POST, чтобы адреса не попадали в журналы прокси и историю браузера: /verifications?address=…

Проверка оставшихся кредитов

GET/usage

Этот запрос не расходует кредиты проверки. Сессии панели и все API-ключи одного пользователя используют общий баланс.

Запрос

curl -sS 'https://api.verifyemail.net/api/v1/usage' \
  -H 'Authorization: Bearer ve_live_your_api_key'

Ответ · HTTP 200

{
  "errcode": 0,
  "verification_limit": 100,
  "verification_used": 1,
  "remaining_verifications": 99,
  "unlimited": false
}

Поле	Тип	Описание
verification_limit	number	Текущий общий лимит. Ноль означает безлимитный доступ.
verification_used	number	Количество уже использованных кредитов проверки.
remaining_verifications	number \| null	Оставшиеся кредиты; null для безлимитного аккаунта.
unlimited	boolean	Является ли текущий лимит безграничным.

Безлимитные планы возвращают remaining_verifications: null, unlimited: true.

Коды ошибок

Используйте числовой errcode в логике программы. Текст message может изменяться.

Ответ с ошибкой

{
  "errcode": 10006,
  "message": "request rate limit exceeded"
}

errcode	HTTP	Значение
0	2xx	Запрос выполнен успешно.
10000	400	Неверный запрос; проверьте JSON, заголовки и метод HTTP.
10001	400 / 422	Параметр или бизнес-правило не прошло проверку.
10002	401	Учётные данные отсутствуют, недействительны или просрочены.
10003	403	У аккаунта нет доступа к ресурсу.
10004	404	Запрошенный ресурс не существует.
10005	409	Ресурс конфликтует с текущим состоянием.
10006	429	Превышен лимит запросов в секунду.
10007	429	Кредиты проверки исчерпаны.
10008	429	Исчерпана параллельная ёмкость сервиса.
10009	500	Произошла внутренняя ошибка сервиса.
10010	503	Сервис временно недоступен или не настроен.
10011	502	Внешний сервис вернул ошибку.

Заголовки ограничения

Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset — описывают текущее окно запросов.

Готовы отправить первый запрос?Создайте аккаунт и получите 100 кредитов проверки.