Быстрый старт с API Email Verifier TrekMail

Используйте API, когда проверка должна стать частью вашего продукта или процесса импорта. Создайте токен с областями доступа verify:read и verify:write, храните его в секрете и обращайтесь к тому же хосту, через который вы входите в систему. В примерах замените https://YOUR-TREKMAIL-HOST и YOUR_API_TOKEN.

1. Создайте токен

1. Откройте Панель управления → AI Agents & API.
2. Создайте токен.
3. Включите verify:read и verify:write.
4. Надёжно сохраните токен. Он показывается только один раз.

Передавайте его с каждым запросом:

Authorization: Bearer YOUR_API_TOKEN

Храните токен в хранилище секретов или переменной среды. Не помещайте его в браузерный код, публичный репозиторий, обращение в поддержку или экспортированный файл контактов. Если вы подозреваете утечку, отзовите токен и создайте замену в панели управления.

2. Проверьте один адрес

Используйте POST /api/v1/verify, чтобы немедленно получить результат для одного адреса. Если mode не указан, по умолчанию применяется Quick.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

Ответ содержит стабильные поля верхнего уровня: адрес, статус, оценку доверия, провайдера, факторы риска и оставшиеся кредиты. Объект checks записывает подробные свидетельства и может различаться, если проверка недоступна или режим Deep предоставляет дополнительные сведения.

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

Сначала считывайте status и trust_score. Считайте отдельные ключи проверок вспомогательными данными, а не гарантией владения почтовым ящиком или доставки.

Для одиночного endpoint действует ограничение маршрута в 60 запросов в минуту. Если вы проверяете введённый пользователем адрес при регистрации, вызывайте его после базовой проверки на стороне клиента. Когда сервис временно недоступен, покажите понятную ошибку, а не блокируйте пользователя на неопределённый срок.

3. Отправьте пакетное задание

Пакетные запросы принимают массив JSON emails, а не загрузку файла. Добавьте ключ идемпотентности, чтобы повторная попытка после сетевой ошибки не создала второе задание.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"September contacts",
    "mode":"deep",
    "emails":["first@example.com","second@example.net"]
  }'

Список может содержать до 50,000 записей. TrekMail нормализует дубликаты и исключает из задания записи с синтаксическими ошибками. В ответе указываются ID задания, количество принятых записей, небольшая выборка отклонённых записей, списанные кредиты и структура цены Deep.

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe означает количество записей, оплаченных по полной ставке Deep. skip означает количество записей, оплаченных по обычной ставке, поскольку провайдер не предоставляет полезных свидетельств на уровне почтового ящика. Ответ содержит окончательную стоимость этой отправки.

Перед отправкой полного списка удалите значения, которые не являются адресами, в собственном импортёре. API устраняет дубликаты и сообщает число отклонённых записей, но проверка источника создаёт более понятный контрольный след. Если с точки зрения вашего приложения истекло время ожидания запроса, повторите тот же пакетный запрос с тем же ключом идемпотентности и проверьте возвращённый ID задания, прежде чем создавать новую отправку.

4. Отслеживайте и скачивайте

Опрашивайте задание через GET /api/v1/verify/bulk/{jobId}, пока оно не достигнет конечного состояния:

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ содержит status, total, processed, progress, summary, время создания и время завершения. Завершённые и частично выполненные задания включают массив results с постраничной разбивкой.

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

После появления результатов можно запросить страницу меньшего размера или найти известный адрес:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Скачайте обработанное задание в формате CSV:

curl -o results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Фильтры экспорта API: all, safe и safe_risky (Safe + Valid + Risky).

Чтобы остановить ожидающее или выполняющееся задание, используйте endpoint отмены. Он возвращает кредиты за необработанную работу и сохраняет все обработанные строки:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Удаляйте задание только тогда, когда хотите удалить и его запись в Verifier, и результаты. Если оно всё ещё выполняется, сначала отмените его, а затем используйте endpoint удаления с ключом идемпотентности. В полном справочнике показаны оба вызова.

5. Обрабатывайте обычные ответы

• 402: аккаунту нужно больше кредитов.
• 422: проверьте тело запроса, выбранный режим или обязательный ключ идемпотентности пакетного запроса.
• 429: снизьте частоту запросов и повторите попытку с увеличением задержки.
• 503: проверка временно недоступна. Повторите попытку позже; плата за неудачную одиночную проверку возвращается.

Контрольный список для рабочей интеграции

1. Храните токен на стороне сервера и предоставляйте только две необходимые области доступа Verifier.
2. Проверяйте и нормализуйте ввод контактов перед вызовом пакетного API.
3. Сохраняйте ID задания, идентификатор отправленного списка, ключ идемпотентности и возвращённое значение credits_charged.
4. Используйте опрос с увеличением задержки, а не частый цикл.
5. Сохраните или обработайте CSV до окончания 15-дневного срока хранения.
6. Принимайте решения о согласии, отказах и исключениях в своём приложении. Результат Verifier их не заменяет.

Полный список endpoints, областей доступа и полей ответа приведён в справочнике REST API Email Verifier.