Русский · English
Готовые примеры работы с API проверки почты на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP.
Валидация email и проверка существования почтового ящика: сервис обращается к почтовому серверу домена и выясняет, принял бы тот письмо на этот адрес — само письмо при этом НЕ отправляется. Заодно проверяется MX-запись, catch-all-домен, одноразовый email, спам-ловушка, жалобщик и ролевой адрес (info@, sales@), а ещё возвращается подсказка по опечатке в домене (gmial.com → gmail.com).
Каждый пример запускается сразу — без регистрации, без ключа, без карты. В коде зашит публичный демо-ключ.
git clone https://github.com/atlorium-api/email-verification-api-client
cd email-verification-api-client/python && pip install -r requirements.txt && python main.pyДемо-ключ: ответы сгенерированы (моки), не реальные данные.
Чистка списка рассылки. Адресов на входе: 4
АДРЕС СТАТУС РЕШЕНИЕ КОММЕНТАРИЙ
anna.petrova@example.com valid SEND Ящик существует, домен принимает почту
ivan@invalid.example.com invalid DROP Ящика не существует — письмо отскочит (hard bounce)
promo@spamtrap.example.com spamtrap DROP СПАМ-ЛОВУШКА — убивает репутацию домена-отправителя
pavel@gmial.com valid SEND Ящик существует, домен принимает почту
ПОДСКАЗКИ ПО ОПЕЧАТКАМ (это спасённый контакт, а не потерянный):
[~] возможно, опечатка: pavel@gmial.com → pavel@gmail.com
!!! СПАМ-ЛОВУШКА В СПИСКЕ: 1 !!!
promo@spamtrap.example.com
Такой адрес никто не заводил и ни на что не подписывал — его публикуют,
чтобы ловить рассылки по купленным базам. Одно попадание роняет репутацию
домена-отправителя, после чего в спам уходит ВСЯ рассылка, включая письма
живым клиентам. Удалять безусловно и выяснять, откуда адрес взялся.
ИТОГО
Проверено адресов: 4
К отправке (SEND): 2
На свой риск (RISKY): 0
Повторить позже: 0 (не тарифицируется)
Выброшено (DROP): 2
Bounce rate без чистки: 25.0 % (несуществующих ящиков: 1 из 4)
Спам-ловушек: 1 <-- критично
Лимит у этого сервиса жёсткий — и он одинаков для демо-ключа и боевого, — поэтому на четырёх адресах пример дважды упирается в 429, ждёт и повторяет (в stderr: ... лимит запросов, пауза 30 с). Так и задумано — см. «Цены и лимиты».
Демо-ключ отвечает правдоподобными моками, а не результатами настоящей SMTP-проверки. Так и задумано: интеграцию можно написать и протестировать до оплаты. Подставьте боевой ключ — тот же код начнёт возвращать реальные вердикты.
Очистка базы рассылки перед отправкой, валидация адреса в форме регистрации, отсев одноразовых ящиков при выдаче триала, снижение bounce rate.
Примеры не просто печатают JSON, а применяют данные: в каждом есть функция filterMailingList(), которая по каждому адресу выносит решение — SEND, SEND_RISKY, RETRY_LATER или DROP — и в конце считает, каким был бы bounce rate, если бы список отправили как есть.
Самое ценное, что даёт сервис, — детект спам-ловушек. Спам-ловушка (spamtrap) — адрес, который никто не заводил и на который никто не подписывался: его специально публикуют, чтобы поймать тех, кто рассылает по купленным и спарсенным базам. Такой ящик отвечает как живой, поэтому отличить его самостоятельно невозможно. Одно попадание роняет репутацию домена-отправителя — и в спам уходит вся рассылка, включая письма живым клиентам. Поэтому в примерах spamtrap — это не просто «ещё один DROP», а отдельное громкое предупреждение.
Логика решения, одинаковая во всех шести примерах:
| Статус | Решение | Почему |
|---|---|---|
valid |
SEND | Ящик существует, домен принимает почту |
catch-all |
SEND_RISKY | Домен принимает письма на любой адрес, поэтому существование конкретного ящика проверить снаружи невозможно. Отправлять на свой риск и желательно отдельным сегментом |
unknown |
RETRY_LATER | Greylisting: сервер домена не ответил. Не тарифицируется — просто повторите позже |
invalid |
DROP | Ящика не существует, письмо отскочит (hard bounce) |
do_not_mail |
DROP | Ролевой адрес (info@, sales@) или одноразовый ящик |
abuse |
DROP | Жалобщик: ранее отмечал письма как спам |
spamtrap |
DROP + предупреждение | Убивает репутацию домена-отправителя. Удалять безусловно |
Если пришло поле didYouMean — это спасённый контакт, а не потерянный: адрес с опечаткой в домене (gmial.com) можно предложить пользователю исправить.
- Проверяется доставляемость, а не то, читает ли ящик живой человек.
- Для catch-all-доменов существование конкретного ящика проверить невозможно в принципе — это ограничение SMTP, а не сервиса.
- Персональные данные владельца ящика (имя, фамилия, пол) не собираются и не отдаются.
- Письмо на проверяемый адрес не отправляется — ни тестовое, ни какое-либо ещё.
Проверить API вообще без клонирования:
curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
"https://atlorium.com/api/EmailValidation?email=user@example.com"| Язык | Запуск | Требуется |
|---|---|---|
| Python | pip install -r requirements.txt && python main.py |
Python 3.10+ |
| TypeScript / Node.js | npm install && npm start |
Node.js 20+ |
| Go | go run . |
Go 1.22+ |
| Java | java Main.java |
JDK 17+ (без зависимостей) |
| C# | dotnet run |
.NET 8+ |
| PHP | php main.php |
PHP 8.1+ |
Передать свой список адресов через запятую:
python main.py "anna@example.com,sales@catchall.example.com,x@unknown.example.com"Ключ передаётся в заголовке Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
| Ключ | Что делает |
|---|---|
ak_sandbox_demo_mockdata_v1 |
Демо-ключ. Публичный, один на всех. Возвращает моки, денег не списывает, регистрации не требует. Ответы детерминированы — на них можно писать стабильные тесты. |
| Боевой ключ | Настоящая SMTP-проверка. Получить в личном кабинете: atlorium.com |
Переход на боевой ключ не требует правок в коде — все примеры читают переменную окружения:
export ATLORIUM_API_KEY="ak_ваш_боевой_ключ"Каждый ответ песочницы помечен заголовком X-Atlorium-Sandbox: true — перепутать мок с реальными данными невозможно.
Чтобы протестировать все ветки обработки, не дожидаясь, пока нужный статус попадётся случайно, песочница отдаёт фиксированный статус по домену:
| Домен в адресе | Статус ответа | subStatus |
|---|---|---|
invalid.example.com |
invalid |
mailbox_not_found |
nodns.example.com |
invalid |
no_dns_entries (нет MX) |
catchall.example.com |
catch-all |
— |
unknown.example.com |
unknown |
greylisted |
spamtrap.example.com |
spamtrap |
possible_trap |
abuse.example.com |
abuse |
global_suppression |
disposable.example.com |
do_not_mail |
disposable |
role.example.com |
do_not_mail |
role_based |
| любой другой домен | valid |
— |
Домены gmial.com и gmai.com дополнительно возвращают didYouMean — так проверяется ветка подсказки по опечатке.
Базовый адрес: https://atlorium.com
| Метод | Путь | Назначение |
|---|---|---|
GET |
/api/EmailValidation |
Проверка доставляемости одного почтового адреса |
| Параметр | Где | Тип | Описание |
|---|---|---|---|
email |
query | string | Почтовый адрес для проверки. Например, user@example.com |
Это единственный параметр — других у метода нет.
| Поле | Тип | Что содержит |
|---|---|---|
email |
string | Проверенный адрес в нормализованном виде |
status |
string | Итоговый вердикт. Valid, Invalid, CatchAll, Unknown, SpamTrap, Abuse, DoNotMail |
statusRaw |
string | Статус в том виде, как его вернул источник: valid, invalid, catch-all, unknown, spamtrap, abuse, do_not_mail |
subStatus |
string | null | Уточнение вердикта: mailbox_not_found, no_dns_entries, role_based, disposable, greylisted, possible_trap, global_suppression |
account |
string | null | Часть адреса до @ |
domain |
string | null | Часть адреса после @ |
freeEmail |
bool | Бесплатный почтовик (gmail.com, mail.ru, yandex.ru, outlook.com) |
catchAllDomain |
bool | null | Домен принимает почту на любой адрес |
didYouMean |
string | null | Подсказка по опечатке в домене: gmial.com → gmail.com |
domainAgeDays |
int | null | Возраст домена в днях. Совсем молодой домен — повод насторожиться |
smtpProvider |
string | null | Почтовая платформа домена: outlook, g-suite, zoho, yandex |
mxFound |
bool | Найдена ли MX-запись. Без неё домен почту не принимает в принципе |
mxRecord |
string | null | Основная MX-запись домена |
activeInDays |
string | null | Признак активности ящика. Платная надстройка провайдера — на базовом тарифе пусто |
activeFirstSeen |
string | null | Когда активность впервые зафиксирована. Тоже платная надстройка — обычно пусто |
processedAtUtc |
date-time | null | Момент проверки, UTC |
elapsedMs |
int | Сколько заняла проверка, мс |
fromCache |
bool | Ответ взят из кэша (повторная проверка того же адреса) |
deliverable |
bool | Можно ли безопасно писать. true только при status = Valid: catch-all и unknown — это неопределённость, а не разрешение |
Других полей в ответе нет.
| Код | Причина | Что делать |
|---|---|---|
400 |
Адрес не передан или синтаксически некорректен | Проверьте формат. Такой запрос не тарифицируется |
401 |
Ключ отсутствует, просрочен или недействителен | Проверьте заголовок Authorization |
402 |
Недостаточно кредитов на балансе | Пополнить на atlorium.com |
429 |
Превышен rate-limit | Повторить с задержкой — см. заголовок Retry-After |
503 |
Сервис проверки временно недоступен | Повторить позже. За сбой на нашей стороне деньги не списываются |
Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.
Оплата pay-as-you-go, без подписки: платите только за выполненные запросы. Актуальные тарифы и лимиты — на atlorium.com/pricing.
Исход unknown (greylisting, сервер домена не ответил) не тарифицируется: вы платите только за содержательный вердикт. Запрос с некорректным адресом (400) — тоже.
Актуальные цены и лимиты: atlorium.com/pricing
Про лимиты — честно. Они считаются по IP и у этого сервиса жёсткие — причём одинаковые для демо-ключа и боевого: песочница показывает ровно те условия, которые вы получите после оплаты. Список из четырёх адресов гарантированно упрётся в 429 — примеры это штатно обрабатывают: ждут и повторяют запрос (см. retry_after / retryAfter). Поэтому запуск примера занимает около минуты, и это не поломка, а честная демонстрация реальных лимитов продукта: песочница выдаёт ровно те лимиты, которые получит платящий пользователь. Если запускать примеры подряд, можно исчерпать и часовой лимит — тогда пример скажет об этом прямо и завершится, а не зависнет.
Отправляется ли письмо на проверяемый адрес? Нет. Сервис обращается к почтовому серверу домена и по его ответу выясняет, принял бы тот письмо на этот ящик. Само письмо не отправляется — владелец адреса ничего не увидит.
Почему статус catch-all, а не «валидный» или «невалидный»? Потому что домен настроен принимать письма на любой адрес и отвечает «принято» даже на несуществующий ящик. Это ограничение SMTP: выяснить снаружи, существует ли конкретный ящик на таком домене, невозможно в принципе. Честный ответ здесь — «неопределённость», а не выдуманная уверенность.
Что такое спам-ловушка и почему это важнее всего остального? Это адрес, который никто не заводил и на который никто не подписывался — его публикуют специально, чтобы ловить рассылки по купленным и спарсенным базам. Ящик отвечает как живой, отличить его самостоятельно невозможно. Одно попадание роняет репутацию домена-отправителя, после чего в спам уходит вся рассылка целиком. Именно ради этого сервис и нужен.
Платить за unknown придётся? Нет. Если почтовый сервер домена применил greylisting, не ответил или заблокировал проверку, вердикта нет — и денег за это не берут. Повторите проверку позже.
Что делать с do_not_mail? Удалять из рассылки. Это либо ролевой адрес (info@, sales@) — его читает отдел, а не человек, и жалоба на спам оттуда прилетает быстрее всего, — либо одноразовый ящик, созданный на десять минут.
Насколько снижается bounce rate? Из списка уходят все invalid — именно они и дают hard bounce. Почтовые провайдеры считают bounce rate выше ~2 % признаком грязной базы и начинают резать доставляемость, поэтому чистка окупается на первой же рассылке.
Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но возвращает моки, а не результаты настоящей SMTP-проверки.
Проверка почты редко бывает единственной задачей. Из того же аккаунта и тем же ключом доступны:
- ИИ-чат — модели, сессии, суммаризация текста
- Валидация телефона — формат, тип номера, оператор диапазона
- Распознавание текста с картинки — OCR по изображению или Base64
- Стандартизация адреса — разбор строки на компоненты и оценка качества
- ЕГРЮЛ/ЕГРИП — проверка контрагента по ИНН/ОГРН: статус, адрес, капитал
- Адреса ГАР/ФИАС — поиск и подсказки по официальному справочнику
Полный каталог — atlorium.com
- Документация API (Swagger): atlorium.com/emailAPI
- Описание сервиса: atlorium.com/emailDescription
- Веб-интерфейс: atlorium.com/emailGUI
- OpenAPI-спецификация: email_ru.json
- Поддержка: support@atlorium.com
MIT — берите код и используйте как хотите, в том числе в коммерческих проектах.