ДЛЯ РАЗРАБОТЧИКОВ

API проверки email.

Проверяйте отдельные адреса в формах или создавайте асинхронные задачи для клиентских списков. Сохраните своего почтового провайдера.

НАЧНИТЕ С ОДНОГО АДРЕСА

Ваш первый запрос.

Используйте бесплатный демонстрационный endpoint без ключа. Он ограничен по частоте запросов и предназначен для знакомства с сервисом.

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

Для платных проверок купите пакет и используйте /v1/fast-verify с ключом в X-API-Key. Не включайте ключи в URL, репозитории и аналитику.

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Пример на Python

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Пример на Node.js

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

СПИСОК НА ВХОДЕ, РЕЗУЛЬТАТЫ НА ВЫХОДЕ

Проверьте большой список.

POST /v1/tasks

Передайте до 10 000 адресов в одной задаче. Сохраните возвращённый ID задачи и проверьте accepted, skipped и invalids: не каждый входной адрес обязательно попадает в очередь. Дубли, неверно оформленные и подавленные адреса могут исключаться, а низкий баланс — привести к частичному приёму.

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

Запрашивайте статус, затем каждую страницу результатов. Ответ только с неверно оформленными адресами может содержать пустой ID задачи; не запрашивайте его статус.

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

Результаты завершённой задачи — JSON. Получайте страницы, пока не загрузите весь принятый список. Для автоматического уведомления о завершении передайте вебхук с mode: "completed" при создании задачи.

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

Перед включением в проде изучите схему настройки вебхуков и проверки подписи.

КАК ПОНЯТЬ ОТВЕТ

Формат не означает существование.

Это разные сигналы. Правильно оформленный адрес всё равно может не существовать, быть временным или не поддаваться подтверждению.

Поле	Значение
`valid`	Адрес прошёл проверку синтаксиса. Само по себе это не подтверждает ящик.
`exists`	Результат проверки ящика. Рассматривайте его вместе с ошибками и сигналами catch-all.
`disposable`	Домен распознан как провайдер временных email-адресов.
`accept_all`	Сервер принимает произвольные адреса; конкретный ящик нельзя надёжно подтвердить.
`error_category`	Объясняет сбой или риск, например no_mx, risky или временную проблему сервера.
`permanent_error`	Во время проверки возвращена постоянная ошибка. Временную ошибку не следует считать постоянным отказом.
`ttl`	Подсказка о времени повторной проверки или кэша в секундах, если возвращена.

Проверка не гарантирует доставку, не устраняет жалобы и не доказывает владение ящиком.

Знайте свой баланс.

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

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

Ответ 429 означает ограничение запросов. Подождите перед повтором. Другие ошибки текущего API могут возвращаться в JSON или текстом; не считайте HTTP-ошибки результатами проверки.

Контракт проверки.

Скачать OpenAPI JSON

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

Нужна помощь с подключением платформы? support@zbounce.net