Валидация Email

Массовая проверка email-адресов

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

Обработка невалидных адресов: Перед постановкой в очередь каждый email проходит синтаксическую проверку. Адреса с невалидным форматом автоматически исключаются из задачи, не тарифицируются и возвращаются в поле invalid_details ответа. Вы платите только за реально проверяемые email.

Идемпотентность: Передайте уникальный idempotency_key для защиты от дублирования задач при повторных запросах (например, при сетевых таймаутах). Повторный запрос с тем же ключом вернёт существующую задачу вместо создания новой.

Webhook-уведомления: Укажите webhook_url — мы отправим POST-запрос с результатами, когда задача завершится. Это избавляет от необходимости polling.

Кредиты: Списываются только за email с валидным синтаксисом. Формула: credits_used = valid_emails. Перед отправкой проверьте баланс через GET /api/v1/account/balance.

Лимиты: Максимальный размер одного запроса ограничен 100 MB. Для очень больших списков рекомендуем разбивать на пакеты по 50 000–100 000 email.

post/api/v1/validate/bulk

Request

  • Base URL: https://api.uchecker.net
  • URL: https://api.uchecker.net/api/v1/validate/bulk
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

emailsstring[] required

Массив email-адресов для проверки. Адреса с невалидным синтаксисом будут автоматически исключены (без списания кредитов) и перечислены в invalid_details ответа.

client_type'web' | 'api' | 'mcp' | 'sheets' | 'extension'

Кто отправил запрос. Значение сохраняется в задаче и видно в статистике. Наши клиенты называют себя сами: web — личный кабинет, mcp — MCP-сервер, sheets — дополнение для Google Таблиц, extension — расширение Chrome. Если поле не передано, задача помечается как api.

webhook_urlstring

URL для webhook-уведомления о завершении задачи. По окончании проверки на него уходит POST с Content-Type: application/json. Эндпоинт должен вернуть HTTP 200; при другом коде или таймауте доставка повторяется, всего до 5 попыток.

Тело запроса:

{
  "task_id": 123,
  "status": "completed",
  "summary": { "total": 100, "good": 80, "bad": 18, "unknown": 2 },
  "finished_at": "2024-01-01T12:34:56.000Z",
  "error_text": null
}

status принимает значения completed, failed или unknown. При failed причина приходит в error_text.

Важно: summary.bad здесь считается иначе, чем в GET /api/v1/tasks/{taskId}/analytics — в вебхуке в него попадают и адреса с маркером <risk>, а unknown содержит только непроверенные. Если вам нужна разбивка, где unknown включает недостоверные результаты, запрашивайте её через эндпоинт аналитики.

websocket_idstring

WebSocket ID для получения обновлений в реальном времени. Используется веб-интерфейсом для отображения прогресса без polling.

idempotency_keystring

Ключ идемпотентности. Уникальная строка (например, UUID), предотвращающая создание дублирующих задач при повторных запросах. Если задача с таким ключом уже существует — вернётся её текущий статус вместо создания новой.

Example request

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "info@company.ru"
  ],
  "client_type": "api",
  "webhook_url": "https://your-site.com/webhook/validation-complete",
  "idempotency_key": "import-2024-01-15-batch-3"
}

Response

Задача создана. Ответ содержит task_id, количество принятых и отклонённых email, списанные кредиты.

successboolean required

Признак успешного создания задачи

task_idnumber required

Уникальный идентификатор задачи для отслеживания прогресса и получения результатов

statusstring required

Статус задачи. queued — задача принята и ожидает обработки.

total_emailsnumber required

Общее количество email-адресов, переданных в запросе

valid_emailsnumber required

Количество email с валидным синтаксисом, принятых в очередь на проверку

invalid_emailsnumber required

Количество email с невалидным синтаксисом, исключённых из проверки (кредиты не списаны)

credits_usednumber required

Количество списанных кредитов. Равно valid_emails.

credits_remainingnumber required

Остаток кредитов на балансе после списания

estimated_completionstring required

Ориентировочное время завершения всей задачи. Формат ISO 8601.

notestring

Информационное сообщение о пропущенных адресах (если есть)

Example response

{
  "success": true,
  "task_id": 124,
  "status": "queued",
  "total_emails": 100,
  "valid_emails": 95,
  "invalid_emails": 5,
  "invalid_details": [
    {
      "email": "bad-email",
      "reason": "Invalid email syntax"
    }
  ],
  "credits_used": 95,
  "credits_remaining": 905,
  "estimated_completion": "2024-01-01T12:01:35.000Z",
  "note": "5 невалидных адресов были пропущены"
}

Changes

No recorded changes to this operation across all 1 revision of this API.