API проверки email: выбор между одиночными, множественными и массовыми запросами

Узнайте, как выбрать подходящий тип запроса к API проверки email для каждой задачи и как преобразовать результаты «Доставляемый», «Недоставляемый» и «Не определено» в программный код.

Запросы к API проверки email можно разделить на три типа в зависимости от того, кто ожидает ответа и сколько адресов необходимо проверить. Используйте одиночную проверку (POST /api/v1/check), когда пользователь ожидает ответа по одному адресу; синхронную множественную проверку (POST /api/v1/batch-check, от 1 до 100 адресов, результаты возвращаются в порядке ввода), когда поступает небольшая группа адресов; и асинхронную массовую задачу (POST /api/v1/bulk-tasks с последующим опросом статуса), когда адреса уже содержатся в файле. Независимо от типа запроса, проектируйте код с учетом трех состояний, а не простого флага «да/нет»: доставляемый, недоставляемый и не определено, при этом некорректные форматы должны отсеиваться до отправки запроса. Каждый полученный результат описывает состояние адреса только на момент проверки.

На что отвечает API проверки email, а что остается на ваше усмотрение

Большинство страниц, ранжирующихся по этой теме, ограничиваются перечислением функций. Вопрос интеграции более узкий: что именно решает один запрос и за что по-прежнему отвечает ваше приложение?

Проверка доставляемости email в EmailCheckPro возвращает результат «Доставляемый» (адрес мог получать почту на момент проверки) или «Недоставляемый». Проверка аватара email добавляет сигнал о наличии публичного аватара, но только для адресов в доменах gmail.com, yandex.ru и mail.ru.

Ваше приложение по-прежнему отвечает за три задачи:

• Проверка формата. Полный адрес состоит из локальной части, символа @ и домена. Некорректный ввод — это ошибка формы, а не вердикт «Недоставляемый», поэтому выявляйте такие ошибки до выполнения запроса.
• Подтверждение владения. Ссылка для подтверждения или ваши собственные записи о согласии пользователя решают эту задачу.
• Актуальность. Результат относится к моменту проверки. Сохраняйте дату рядом с результатом, чтобы последующие процессы понимали, насколько он устарел.

Соблюдение этих границ в коде, а не только в документации, позволяет избежать наиболее распространенных ошибок интеграции, описанных ниже.

Выбор типа запроса к API проверки email

Три типа запросов не являются взаимозаменяемыми, и выбор неподходящего часто приводит к медленной работе форм или сбоям в задачах импорта.

Краткое руководство по выбору:

1. Кто-то ожидает ответа на экране? Используйте одиночный эндпоинт только для того адреса, который ввел пользователь.
2. Адреса поступают вместе и их не более 100? Отправьте один множественный запрос. Это по-прежнему синхронная операция: просто более объемный одиночный вызов, а не массовая задача.
3. Источник — это уже готовый файл или список из сотен строк? Отправьте массовую задачу и позвольте фоновому процессу собрать результат. Применяются лимиты задач для каждого продукта, указанные в документации API.
4. Нужны ли аватары? Сначала отфильтруйте список, оставив только поддерживаемые домены gmail.com, yandex.ru и mail.ru. Неподдерживаемый домен отклоняется до списания средств, а в массовом файле для проверки аватаров это приведет к ошибке подготовки с возвратом резервирования.

Для нескольких сотен адресов, которые не оформлены в файл, разумно использовать либо несколько множественных запросов, либо проверку в реальном времени через панель управления, которая поддерживает до 500 адресов.

Преобразование результатов в логику приложения

Сведение результатов к логическому значению — это ошибка, которую допускают большинство интеграций. Небольшой тип состояния позволяет сохранить смысл:

Из документации следуют три правила:

• При одиночной проверке в реальном времени адрес со статусом «Не определено» возвращает бизнес-код вместо результата и не тарифицируется. Рассматривайте эту ветку как отдельное состояние, а не как ошибку, которую нужно повторять в бесконечном цикле.
• В множественном ответе для каждого элемента указано, существует ли завершенный результат. Только элементы с таким результатом могут быть «Доставляемыми» или «Недоставляемыми»; остальные относятся к ветке «Не определено» или «Не завершено».
• Некорректные, неудачные и неопределенные проверки не тарифицируются, поэтому повторная попытка позже ничего не стоит, кроме времени. Запланируйте повторную попытку, вместо того чтобы повторять её немедленно.

Выполнение асинхронных массовых задач без сюрпризов

Массовая задача — это небольшая конечная машина, и она должна выполняться в фоновом процессе, а не в рамках веб-запроса.

1. Подготовьте файл. Создайте TXT или CSV с одним полным адресом email на каждой строке. Некорректные и дублирующиеся строки удаляются при подготовке, но предварительная очистка от явного мусора упрощает сверку количества.
2. Отправьте и сохраните. Сохраните идентификатор задачи, возвращенный POST /api/v1/bulk-tasks, в своей базе данных вместе с именем исходного файла, используемым продуктом и временем отправки. В случае сбоя процесса вы сможете возобновить работу, а не отправлять задачу заново.
3. Опрашивайте статус терпеливо. Выполняйте GET /api/v1/bulk-tasks/{id} не чаще одного раза в 30 секунд. Запланированная задача, которая проверяет статус и переходит в режим ожидания, подходит для этого лучше, чем цикл, удерживающий соединение открытым.
4. Скачивайте своевременно. Успешная задача предоставляет один CSV-файл по ссылке для скачивания, которая действует 12 часов. Если срок действия ссылки истек, запросите ту же задачу снова для получения новой ссылки, вместо того чтобы загружать файл повторно.
5. Объединяйте по адресу. Поскольку при подготовке строки могут быть удалены, объединяйте результирующий CSV с вашими записями по адресу email, а не по номеру строки.

CSV-файл с результатами доставляемости связывает каждый адрес с его исходом. CSV-файл с аватарами также указывает, был ли найден публичный аватар, и предоставляет ссылку на него. Ссылка может быть пустой, даже если аватар присутствует, поэтому рассматривайте пустую ссылку как нормальное значение.

Ежедневная эксплуатация интеграции

Когда типы запросов и состояния настроены правильно, несколько привычек помогут поддерживать стабильную работу интеграции:

• Только серверные ключи. API-ключ расходует баланс аккаунта, который является общим для веб-проверок, REST-вызовов, массовых задач и доступа через MCP. Никогда не используйте его в коде браузера или мобильных приложений.
• Проверяйте в момент изменения. Проверяйте адрес при создании или редактировании, а затем повторно используйте сохраненный результат в течение вашего окна перепроверки, вместо того чтобы вызывать API при каждом просмотре страницы.
• «Открытый» отказ в форме, «закрытый» в конвейере. Если проверка идет медленно или результат не определен во время регистрации, позвольте пользователю продолжить, пометив адрес флагом. В конвейере рассылки удерживайте помеченные строки до тех пор, пока не будет получен завершенный результат.
• Защищайте свой эндпоинт. Если ваше приложение предоставляет маршрут «проверить этот адрес», ограничьте частоту запросов и возвращайте единообразные сообщения. Руководство OWASP по проверке email предостерегает от того, чтобы формы раскрывали информацию о существовании аккаунта.
• Предоставьте AI-клиентам MCP-эндпоинт. https://emailcheckpro.com/mcp поддерживает одиночные проверки, до 100 адресов за вызов, перечисление продуктов и запросы баланса. Массовая работа с файлами остается в рамках веб-процесса или REST API.

Текущие лимиты запросов и детали использования опубликованы в документации API EmailCheckPro; ознакомьтесь с ними там, вместо того чтобы закладывать предположения в код.

Проверка формата, соответствующая ожиданиям API

Самый дешевый вызов — это тот, который вы не совершаете для некорректного ввода. Две ссылки помогут вам выбрать разумный фильтр:

• Стандарт WHATWG HTML определяет шаблон, который браузеры используют для полей type="email". Он намеренно отходит от полных стандартов почты, чтобы оставаться практичным, что делает его разумной базой для проверки на стороне сервера.
• RFC 5321 описывает формы адресов, используемые при передаче почты. Рассматривайте его как справочник форматов для граничных случаев, таких как локальные части в кавычках, а не как описание работы сервиса проверки.

На практике: удаляйте пробелы, убирайте завершающие знаки препинания, скопированные из документов, приводите домен к нижнему регистру, сохраняйте локальную часть в исходном виде и отклоняйте только тот ввод, в котором явно отсутствуют локальная часть, символ @ или домен. Слишком строгие шаблоны, отвергающие знаки «плюс» или длинные домены верхнего уровня, отталкивают реальных пользователей, и их следует избегать.

Часто задаваемые вопросы

Когда командам следует переходить от множественных вызовов к массовым задачам?

Переходите, когда адреса уже находятся в файле или когда для обработки списка потребовалось бы множество последовательных множественных вызовов. Множественные запросы подходят для групп до 100 адресов, которые поступают вместе и требуют ответов в одном ответе. Массовые задачи подходят для подготовленных экспортов, которые могут подождать, так как результат приходит позже в виде одного CSV-файла, а процессу нужно лишь опрашивать статус каждые 30 секунд или реже.

Как приложению следует хранить результаты API проверки email?

Храните адрес в исходном виде, использованный продукт, результат в виде текста, дату проверки и источник адреса. Такая запись позволяет службе поддержки объяснить решение, позволяет задачам перепроверки выбирать самые старые результаты в первую очередь и отделяет неопределенные или незавершенные строки от недоставляемых. Избегайте хранения необработанных ответов API в качестве единственной записи, так как другие системы будут зависеть от формата API.

Может ли результат «Доставляемый» заменить подтверждение по email?

Нет. Результат «Доставляемый» информирует о том, мог ли адрес получать почту на момент проверки, при этом сама проверка ничего не отправляет. Ссылка для подтверждения отвечает на другой вопрос: контролирует ли человек, введший адрес, этот почтовый ящик и согласен ли он получать сообщения. Многие процессы регистрации используют проверку, чтобы отсеять неактивные адреса перед отправкой, а затем полагаются на подтверждение для получения согласия и проверки владения.

Какой самый безопасный способ повторить проверки, которые не завершились?

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

Узнайте больше

Выберите информацию о продукте, которая соответствует следующему шагу в вашем рабочем процессе.

• Просмотреть документацию по продукту →
• Связаться с командой →