Справочник REST API Email Verifier

API Email Verifier доступен по адресу /api/v1. Используйте тот хост TrekMail, через который ваш аккаунт входит в систему. В приведённых ниже примерах https://YOUR-TREKMAIL-HOST используется как placeholder.

Аутентификация и области доступа

Передавайте API-токен в заголовке Authorization:

Authorization: Bearer YOUR_API_TOKEN

Включите области доступа при создании токена:

Предоставьте клиенту обе области доступа, если он должен отправлять задания, а затем читать или скачивать результат.

Хост и формат запроса

Во всех примерах используются тела запросов JSON и Bearer-токен. Загрузчик файлов в панели управления работает отдельно от API: POST /verify/bulk принимает массив JSON emails, а не multipart-файл. Используйте точный хост, которому принадлежат аккаунт и токен. Не следует считать, что токен или баланс с одного брендированного хоста будет работать на другом.

Отправляйте Content-Type: application/json в запросах POST /verify и POST /verify/bulk. Храните токен и значение идемпотентности вне клиентского кода.

Идемпотентность

Для POST /api/v1/verify/bulk и DELETE /api/v1/verify/bulk/{jobId} требуется заголовок Idempotency-Key. Создавайте новое значение для каждой запланированной операции и повторно используйте его только при повторе той же операции.

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

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

Обработка неопределённого результата сетевого запроса

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

Обзор endpoints

Добавляйте /api/v1 перед каждым путём в этой таблице.

Чтение баланса кредитов

GET /api/v1/verify/credits

На стандартном хосте TrekMail ответ содержит лимит плана и приобретённый баланс:

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

На хосте White Label брендированный продукт может использовать только приобретённые кредиты, поэтому ответ содержит purchased_balance и total_available.

Пример запроса:

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

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

Поля баланса

Ответы о балансе White Label намеренно содержат меньше полей, поскольку брендированный продукт использует только приобретённые кредиты.

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

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

Ответ содержит email, status, trust_score, checks, provider, risk_factors и credits_remaining. На стандартном хосте у credits_remaining есть значения monthly и purchased. Подробная структура checks может меняться в зависимости от режима и данных, которые предоставляет принимающий провайдер.

Quick стоит 1 кредит. Deep обычно стоит 2 кредита, а исключения для определённых провайдеров рассчитываются по 1 кредиту. Если после списания проверку выполнить невозможно, запрос одного адреса возвращает это списание и ответ о временной недоступности.

Пример запроса:

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"}'

Используйте поля верхнего уровня status, trust_score, provider и risk_factors как обычный контракт приложения. checks содержит полезные вспомогательные данные, но отдельные ключи могут отличаться, когда вышестоящая проверка пропущена, недоступна или режим Deep получает дополнительную информацию.

Интерпретация результата одиночной проверки

Не позволяйте приложению считать принятый удалённый ответ проверкой владения или разрешения. Решения о подписке, отказе от рассылки и предпочтениях контакта обрабатывайте отдельно.

Создание пакетного задания

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

Дубликаты нормализуются до расчёта цены. Новое задание при успешном создании возвращает 201 со следующими данными:

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

probe и skip объясняют расчёт цены Deep. deep_savings представляет собой разницу по сравнению со списанием полной ставки Deep за каждый отправленный адрес. Для дубликата списка возвращаются существующие job_id и статус вместо запуска другого задания.

Пример запроса:

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

Перед допуском задания API проверяет синтаксическую корректность отправленных значений email. Если отклонены все записи, он возвращает 422 и не создаёт задание. Если отклонена часть записей, успешный ответ содержит rejected_count и до пяти значений в rejected_sample. Не считайте эту небольшую выборку полным отчётом об очистке данных; сохраняйте результат проверки источника в собственном импортёре.

Контрольный список пакетной отправки

1. Прочитайте и нормализуйте источник в собственном приложении.
2. Ограничьте запрос 50,000 отправляемыми записями.
3. Создайте и сохраните ключ идемпотентности до запроса.
4. Сделайте имя задания достаточно понятным, чтобы оператор мог узнать его позднее.
5. Сохраните job_id, credits_charged и структуру цены, возвращённую TrekMail.
6. Опрашивайте сохранённый job_id; не определяйте завершение по исходному HTTP-запросу.

Чтение задания

GET /api/v1/verify/bulk/{jobId}

Основной ответ содержит job_id, name, status, total, processed, progress, summary, created_at и completed_at.

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

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

Необязательные параметры запроса:

Отменённое задание с обработанными строками можно скачать, но для его экспорта используйте endpoint скачивания.

Чтение состояний задания без догадок

Клиент API должен выполнять опрос с увеличением задержки. Не отправляйте новое пакетное задание только потому, что существующее всё ещё ожидает обработки или локальный сетевой запрос завершился по тайм-ауту.

Пример ответа о статусе

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

Значения summary могут расти по мере выполнения работы. Для отображения хода выполнения используйте processed и total, а не сумму только тех категорий, которые приложение распознаёт сейчас.

Скачивание задания

GET /api/v1/verify/bulk/{jobId}/download

Скачивание доступно для завершённых, частично завершённых или отменённых заданий, у которых есть обработанные строки. Передаётся поток CSV со столбцами Email, Status, Trust Score, Provider и Risk Factors.

Пример:

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

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

Endpoint скачивания возвращает конфликт, пока обработанный экспорт недоступен. Сначала проверьте состояние задания. Успешный запрос передаёт CSV потоком, а не возвращает оболочку JSON, поэтому обрабатывайте его в HTTP-клиенте как файловый ответ.

Получение списка заданий

GET /api/v1/verify/bulk

Используйте page, per_page и необязательный status. Значение per_page по умолчанию равно 20 и принимает числа от 1 до 100. Значения статуса задания: pending, processing, completed, partial, cancelled и failed.

Ответ содержит массив jobs и объект pagination. Каждая запись задания содержит его ID, имя, статус, общее количество, количество обработанных записей, ход выполнения и временные метки.

Пример:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Используйте endpoint списка при перезапуске worker или когда нужно сверить ID заданий. Не считайте имя задания уникальным идентификатором; сохраняйте возвращённый числовой job_id.

Структура ответа со списком заданий

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

Используйте параметр запроса status, когда на операционной странице нужны только активные или только завершённые задания. Пагинация важна для аккаунтов, проверяющих много списков; не считайте, что один ответ содержит всю историю.

Отмена задания

POST /api/v1/verify/bulk/{jobId}/cancel

Отменяйте только ожидающую или выполняющуюся работу. Успешный ответ выглядит так:

{"status":"cancelled","credits_refunded":40}

Возврат относится к необработанной работе. Если задание достигло конечного состояния до получения запроса на отмену, API вернёт конфликт вместо изменения результата.

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

Отмена не удаляет задание. При необходимости скачайте обработанные строки или затем удалите завершённую запись.

Удаление задания

DELETE /api/v1/verify/bulk/{jobId}

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

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

Эта операция безвозвратна для записи верификатора. Она не отзывает файлы CSV, уже скачанные приложением, поэтому применяйте к этим копиям собственный процесс хранения.

Порядок удаления

1. Прочитайте статус задания.
2. Отмените его, если оно ожидает обработки или выполняется.
3. Сохраните весь обработанный экспорт, который требуется оставить.
4. Удалите невыполняющееся задание верификатора с ключом идемпотентности.
5. Удалите все копии, хранящиеся в вашей системе, в соответствии с её правилами конфиденциальности и хранения.

Ошибки и повторные попытки

Для одиночной проверки действует ограничение маршрута в 60 запросов в минуту, а для пакетной отправки в 10 запросов в минуту. Реализуйте логику повторов с увеличением задержки, сохраняйте тот же ключ идемпотентности при повторе пакетного запроса и не повторяйте запрос вслепую после неизвестного результата сетевого обращения.

Безопасная схема повторной попытки

1. Создайте и сохраните один ключ идемпотентности до пакетной отправки.
2. Отправьте запрос с этим ключом.
3. Если ответ потерян, повторите идентичный запрос с тем же ключом.
4. Сохраните возвращённый job_id и прекратите создавать новые отправки для этого исходного списка.
5. Опрашивайте это задание до конечного состояния, затем скачайте или обработайте результат.

Для одиночной проверки временный ответ 503 означает, что сервис не смог завершить проверку. Повторите позже с обычным увеличением задержки. Не преобразуйте такой ответ в результат Invalid в собственной базе данных.

Безопасность контактных данных

Во многих контекстах списки email являются персональными данными. Отправляйте только данные, необходимые для проверки, ограничивайте доступ токена системой, выполняющей задание, и не записывайте полные массивы адресов в журналы приложения. Когда журналирование необходимо, сохраняйте ID задания, количество, время и общий результат, а не полный список.

TrekMail хранит результаты в течение 15 дней. До интеграции списков большого объёма подготовьте собственный безопасный путь хранения или удаления экспорта.

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