Документация API uChecker

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

Параметры

• emailstring· в теле· обязательный

  Адрес для проверки в формате RFC 5322.

• webhook_urlstring· в теле· необязательный

  Куда прислать POST с результатом, когда проверка завершится. Адрес должен быть доступен извне и отвечать 200.

• client_typestring· в теле· необязательный

  web | api

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

Запрос

{
  "email": "user@example.com",
  "webhook_url": "https://your-site.com/webhook/validation-complete"
}

Ответ 200

{
  "success": true,
  "task_id": 123,
  "email": "user@example.com",
  "status": "queued",
  "credits_used": 1,
  "credits_remaining": 999,
  "estimated_completion": "2024-01-01T12:00:30.000Z"
}

Проверить список адресов

Параметры

• emailsstring[]· в теле· обязательный

  Массив адресов. Невалидные по синтаксису будут исключены.

• webhook_urlstring· в теле· необязательный

  Куда прислать POST с результатами всех проверок по завершении задачи.

• idempotency_keystring· в теле· необязательный

  Произвольная уникальная строка — например, идентификатор импорта. Защищает от дублей при повторной отправке.

• client_typestring· в теле· необязательный

  web | api

  Помечает источник запроса.

Запрос

{
  "emails": ["user1@example.com", "user2@example.com", "info@company.ru"],
  "idempotency_key": "import-2024-01-15-batch-3"
}

Ответ 200

{
  "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": 904
}

Статус и прогресс задачи

Параметры

• taskIdnumber· в пути· обязательный

  Идентификатор задачи из ответа на запрос валидации.

Ответ 200

{
  "success": true,
  "task_id": 123,
  "status": "processing",
  "total_emails": 100,
  "processed_emails": 45,
  "progress_percent": 45,
  "created_at": "2024-01-01T12:00:00.000Z",
  "finished_at": null
}

Результаты валидации

Параметры

• taskIdnumber· в пути· обязательный

  Идентификатор задачи.

• formatstring· в строке запроса· необязательный· по умолчанию: json

  json | csv

  json отдаёт структуру, csv — тот же набор строкой с заголовками.

Ответ 200

{
  "success": true,
  "format": "json",
  "data": [
    { "email": "user1@example.com", "validation_result": "good" },
    {
      "email": "user2@example.com",
      "validation_result": "bad",
      "result": "mailbox_not_found"
    }
  ]
}

Скачать результаты в CSV

Параметры

• taskIdnumber· в пути· обязательный

  Идентификатор задачи.

Ответ 200

Content-Type: text/csv
Content-Disposition: attachment; filename="results_123.csv"

email,validation_result,result
user1@example.com,good,
user2@example.com,bad,mailbox_not_found

Скачать good и bad списками

Параметры

• taskIdnumber· в пути· обязательный

  Идентификатор задачи.

Ответ 200

Content-Type: application/zip
Content-Disposition: attachment; filename="task_123.zip"

task_123.zip
├── good.txt
└── bad.txt

Аналитика по задаче

Параметры

• taskIdnumber· в пути· обязательный

  Идентификатор задачи.

Ответ 200

{
  "total": 100,
  "good": 80,
  "bad": 15,
  "unknown": 5,
  "deliverability": 80,
  "reasons": [
    { "key": "smtp_reject", "count": 12 },
    { "key": "domain_not_found", "count": 3 }
  ]
}

Список задач

Параметры

• pagenumber· в строке запроса· необязательный· по умолчанию: 1

  Номер страницы, нумерация с единицы.

• limitnumber· в строке запроса· необязательный· по умолчанию: 10

  Задач на страницу: от 1 до 100.

Ответ 200

{
  "success": true,
  "tasks": [
    {
      "task_id": 123,
      "fileName": "bulk_100_emails",
      "status": "completed",
      "created_at": "2024-01-01T12:00:00.000Z",
      "finished_at": "2024-01-01T12:01:35.000Z"
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 10
}

Баланс аккаунта

Параметры

Параметров нет.

Ответ 200

{
  "success": true,
  "account_id": 123456,
  "credits_remaining": 1000,
  "api_key": "uk_xxxxx..."
}

Статистика аккаунта

Параметры

Параметров нет.

Ответ 200

{
  "tasks_count": 42,
  "emails_checked": 12500,
  "avg_deliverability": 78,
  "last_list": { "total": 100, "good": 80, "bad": 15, "unknown": 5 }
}

История платежей

Параметры

• pagenumber· в строке запроса· необязательный· по умолчанию: 1

  Номер страницы, нумерация с единицы.

• limitnumber· в строке запроса· необязательный· по умолчанию: 10

  Записей на страницу.

Ответ 200

{
  "data": [
    {
      "id": 1,
      "amount": 1000,
      "status": "completed",
      "product_details": "5000 addresses (5k) via freekassa from web",
      "creation_date": "2024-01-01T12:00:00.000Z",
      "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 5, "totalPages": 1 }
}

Рассчитать стоимость кредитов

Параметры

• x-esp-tokenstring· заголовок· обязательный

  Токен партнёра, выдаётся при подключении.

• countnumber· в строке запроса· обязательный

  Количество кредитов, минимум 1.

Ответ 200

{
  "success": true,
  "credits": 10000,
  "price": 2000,
  "price_per_email": 0.2,
  "currency": "RUB"
}

Создать аккаунт или пополнить кредиты

Параметры

• x-esp-tokenstring· заголовок· обязательный

  Токен партнёра, выдаётся при подключении.

• emailstring· в теле· обязательный

  Адрес будущего или существующего аккаунта.

• creditsnumber· в теле· обязательный

  Сколько кредитов зачислить.

• external_idstring· в теле· необязательный

  Идентификатор заказа на стороне партнёра. Защищает от двойного зачисления.

Запрос

{
  "email": "user@example.com",
  "credits": 10000,
  "external_id": "order_12345"
}

Ответ 200

{
  "success": true,
  "account_id": 123,
  "email": "user@example.com",
  "api_key": "uk_xxxxxxxxxxxxx",
  "credits_added": 10000,
  "total_credits": 10000,
  "is_new_account": true,
  "is_duplicate": false
}