Документация API uChecker
uChecker проверяет существование ящика через API: на уровне DNS/MX, SMTP-подключения и конкретного провайдера. На каждый адрес приходит одно из трёх значений: good, если ящик принимает почту, bad, если не принимает, или unknown, если выяснить не удалось. Третье значение отделено, чтобы догадка не выдавалась за факт.
API нужен там, где проверка должна идти без человека: в форме регистрации в момент ввода адреса, при синхронизации CRM, перед автоматической рассылкой. Разовую чистку базы проще сделать в веб-кабинете.
Это обычный email rest api. Все запросы уходят на https://api.uchecker.net, проверить любой эндпоинт можно поштучно или пакетом до миллионов адресов за одну задачу.
Быстрый старт
1. Получите API-ключ
Ключ появляется в личном кабинете сразу после регистрации, отдельно запрашивать его не нужно.
2. Отправьте адрес на проверку
curl -X POST https://api.uchecker.net/api/v1/validate/single \ -H "x-api-key: uk_ВАШ_КЛЮЧ" \ -H "Content-Type: application/json" \ -d '{"email": "user@example.com"}'3. Заберите результат по task_id из ответа
curl https://api.uchecker.net/api/v1/tasks/123/results \ -H "x-api-key: uk_ВАШ_КЛЮЧ"
Аутентификация
Способа два, и они равноправны: оба дают полный доступ ко всем эндпоинтам. Выбор зависит от того, откуда идёт запрос.
API-ключ
Ключ передаётся в заголовке x-api-key, не истекает и живёт до ручного сброса. Для серверных интеграций брать стоит именно его — не нужно следить за сроками жизни токенов.
x-api-key: uk_xxxxxxxxxxxxxBearer-токен
JWT выдаётся методом POST /auth/login и передаётся в заголовке Authorization. Вариант для фронтенда, где вечный ключ в браузер класть нельзя.
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...| Токен | Время жизни | Назначение |
|---|---|---|
access_token | 1 час | Аутентификация запросов |
refresh_token | 7 дней | Обновление access_token через POST /auth/refresh |
Ключ виден в личном кабинете и там же сбрасывается, если его скомпрометировали. Старый ключ перестаёт работать сразу. app.uchecker.net
Кредиты и лимиты
Тарификация кредитная: одна проверка одного адреса стоит 1 кредит. Кредит списывается в момент постановки адреса в очередь, а не по факту ответа SMTP-сервера.
- Ограничений на частоту запросов нет — отправляйте с той скоростью, которая нужна.
- Адреса, не прошедшие синтаксическую проверку, при пакетной отправке не тарифицируются: они возвращаются в поле
invalid_details, и платить за них не придётся. - Текущий остаток отдаёт
GET /api/v1/account/balance.
Что означает результат
Каждый адрес получает одно из трёх значений в поле validation_result. Пока адрес не проверен, там null, а в CSV-выгрузках pending.
Третье значение, unknown, нужно потому, что на часть адресов однозначного ответа не существует. Если MX-серверы домена не отвечают, честно сказать можно только одно: выяснить не удалось. Такие адреса разумно не отправлять сразу и перепроверить позже.
| Значение | Что это значит |
|---|---|
good | Ящик существует и принимает почту. Адрес можно оставлять в рассылке. |
bad | Ящик не существует, отключён или домен почту не принимает. Причина — в поле result. |
unknown | Доставляемость определить не удалось: у домена нет MX-записей, MX-серверы не отвечают, домен выглядит подозрительно или числится в чёрных списках. |
Поле result содержит ответ проверяющего сервера в виде SMTP-строки, например 550-5.1.1 The email account is currently not functioning или 550 5.1.2 <risk> No MX records found. Это свободный текст, а не перечисление, сравнивать его на точное равенство нельзя. Метка <risk> служебная: по ней адрес и получает unknown. Сводку по причинам отдаёт GET /api/v1/tasks/{taskId}/analytics.
Жизненный цикл задачи
Любой запрос на валидацию создаёт задачу. Результаты доступны только после того, как она дойдёт до состояния completed.
pending → processing → completed
↘ failed| Состояние | Что происходит |
|---|---|
pending | Задача создана и ждёт очереди. Код 0. |
processing | Адреса проверяются, прогресс виден в progress_percent. Код 1. |
completed | Все адреса проверены, результаты можно забирать. Код 3. |
failed | Задача упала — напишите в поддержку и приложите task_id. Код −1. |
Опрашивать статус имеет смысл раз в 5–10 секунд. Либо передайте webhook_url при создании задачи — тогда мы сами postим результат, когда всё посчитается, и опрос не нужен вовсе.
Пример интеграции
Полный цикл: отправить список, дождаться задачи и забрать результат. Ключ берётся из переменной окружения, в код и репозиторий его класть не нужно.
Python (requests)
import os
import time
import requests
BASE = "https://api.uchecker.net"
HEADERS = {"x-api-key": os.environ["UCHECKER_API_KEY"]}
task = requests.post(
f"{BASE}/api/v1/validate/bulk",
headers=HEADERS,
json={"emails": ["anna@example.com", "boris@example.org"]},
).json()
task_id = task["task_id"]
while True:
state = requests.get(f"{BASE}/api/v1/tasks/{task_id}", headers=HEADERS).json()
if state["status"] == "completed":
break
if state["status"] == "failed":
raise RuntimeError(f"task {task_id} failed")
time.sleep(10)
results = requests.get(
f"{BASE}/api/v1/tasks/{task_id}/results", headers=HEADERS
).json()
for row in results["data"]:
print(row["email"], row["validation_result"], row.get("result", ""))Node.js 18+ (встроенный fetch)
const BASE = "https://api.uchecker.net";
const headers = {
"x-api-key": process.env.UCHECKER_API_KEY,
"Content-Type": "application/json",
};
const task = await fetch(`${BASE}/api/v1/validate/bulk`, {
method: "POST",
headers,
body: JSON.stringify({ emails: ["anna@example.com", "boris@example.org"] }),
}).then((r) => r.json());
for (;;) {
const state = await fetch(`${BASE}/api/v1/tasks/${task.task_id}`, { headers })
.then((r) => r.json());
if (state.status === "completed") break;
if (state.status === "failed") throw new Error(`task ${task.task_id} failed`);
await new Promise((resolve) => setTimeout(resolve, 10_000));
}
const results = await fetch(`${BASE}/api/v1/tasks/${task.task_id}/results`, { headers })
.then((r) => r.json());
for (const row of results.data) {
console.log(row.email, row.validation_result, row.result ?? "");
}- Перед большой задачей сверьте
credits_remainingизGET /api/v1/account/balanceс размером списка. - Вместо опроса можно передать
webhook_url: когда задача закончится, на него придёт POST со сводкой. - При повторной отправке того же списка передавайте
idempotency_key, тогда случайный повтор не создаст вторую задачу. - Очень большую базу удобнее отправлять несколькими задачами: проще следить за прогрессом и перезапускать упавшую часть.
- Результат стоит сохранять у себя. Повторная проверка того же адреса через день тратит кредит и почти никогда не меняет ответ.
Ошибки
Коды стандартные, тело ошибки всегда содержит success: false и человекочитаемое поле error.
| Код | Когда приходит |
|---|---|
400 | Невалидные параметры или неверный формат данных. |
401 | Ключ или токен отсутствует, просрочен либо неверен. |
403 | На балансе не хватает кредитов. |
404 | Задачи не существует или она принадлежит другому аккаунту. |
500 | Ошибка на нашей стороне — повторите запрос. |
Справочник эндпоинтов
Ниже — все публичные методы с параметрами и примерами. Адреса указаны без базового URL.
https://api.uchecker.netВалидация и задачи
Постановка адресов в очередь, отслеживание прогресса и получение результатов.
Проверить один адрес
/api/v1/validate/singleНужен ключАдрес проходит синтаксическую проверку, встаёт в очередь и проверяется через DNS/MX, SMTP и провайдер-специфичные методы.
Если формат заведомо неверный, ответ приходит мгновенно со status: "invalid" и кредит не списывается. Иначе списывается 1 кредит и возвращается task_id. Проверка занимает от нескольких секунд до двух минут — дольше всего отвечают домены с жёсткими антиспам-политиками.
Параметры
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"
}Проверить список адресов
/api/v1/validate/bulkНужен ключОсновной способ работы с базами. Перед постановкой в очередь каждый адрес проверяется на синтаксис: кривые отсеиваются, не тарифицируются и возвращаются в invalid_details с причиной. Платите только за те, что реально ушли на проверку.
Передайте idempotency_key, если запрос может повториться из-за сетевого таймаута: повторный вызов с тем же ключом вернёт уже созданную задачу вместо второй такой же.
Параметры
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
}Статус и прогресс задачи
/api/v1/tasks/{taskId}Нужен ключПоказывает, на каком этапе задача и сколько адресов уже обработано. Результаты доступны только у задач в статусе completed, так что этот метод — то, что опрашивают между постановкой и выгрузкой.
Задача видна только тому аккаунту, который её создал.
Параметры
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
}Результаты валидации
/api/v1/tasks/{taskId}/resultsНужен ключОтдаёт результат по каждому адресу задачи. У адресов со статусом bad и unknown заполнено поле result с ответом сервера.
Параметры
taskIdnumber· в пути· обязательныйИдентификатор задачи.
formatstring· в строке запроса· необязательный· по умолчанию:jsonjson | csv
jsonотдаёт структуру,csv— тот же набор строкой с заголовками.
Ответ 200
{
"success": true,
"format": "json",
"data": [
{ "email": "user1@example.com", "validation_result": "good" },
{
"email": "user2@example.com",
"validation_result": "bad",
"result": "550-5.1.1 The email account is currently not functioning and is unable to receive messages."
},
{
"email": "user3@example.org",
"validation_result": "unknown",
"result": "550 5.1.2 <risk> No MX records found"
}
]
}Скачать результаты в CSV
/api/v1/tasks/{taskId}/results/csvНужен ключФайл с заголовком Content-Disposition: attachment, удобно отдавать прямо в браузер пользователя. В отличие от format=csv у предыдущего метода, колонок три: email, validation_result и reason с текстом ответа сервера.
Параметры
taskIdnumber· в пути· обязательныйИдентификатор задачи.
Ответ 200
Content-Type: text/csv
Content-Disposition: attachment; filename="task_123_results.csv"
email,validation_result,reason
user1@example.com,good,
user2@example.com,bad,"550-5.1.1 The email account is currently not functioning and is unable to receive messages."
user3@example.org,unknown,"550 5.1.2 <risk> No MX records found"
user4@example.com,pending,Скачать good, bad и unknown списками
/api/v1/tasks/{taskId}/downloadНужен ключZIP с тремя файлами: good.txt, bad.txt и unknown.txt, по адресу на строку. В unknown.txt попадают и адреса, которые ещё не проверены. Такой формат сразу принимают почти все ESP при импорте, разбирать CSV не нужно.
Параметры
taskIdnumber· в пути· обязательныйИдентификатор задачи.
Ответ 200
Content-Type: application/zip
Content-Disposition: attachment; filename="task_123_results.zip"
task_123_results.zip
├── good.txt
├── bad.txt
└── unknown.txtАналитика по задаче
/api/v1/tasks/{taskId}/analyticsНужен ключСводка по завершённой задаче: сколько адресов живых, сколько отсеяно, какой процент доставляемости получился и по каким причинам адреса не прошли.
Поле reasons показывает распределение отказов — по нему видно, что именно не так с базой: массовый domain_not_found означает опечатки в домене при сборе, а smtp_reject чаще говорит о старой базе.
Параметры
taskIdnumber· в пути· обязательныйИдентификатор задачи.
Ответ 200
{
"total": 100,
"good": 80,
"bad": 15,
"unknown": 5,
"deliverability": 80,
"reasons": [
{ "key": "smtp_reject", "count": 12 },
{ "key": "domain_not_found", "count": 3 }
]
}Список задач
/api/v1/tasksНужен ключИстория задач аккаунта с пагинацией, новые первыми.
Параметры
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
}Аккаунт и биллинг
Остаток кредитов, сводная статистика и история платежей.
Баланс аккаунта
/api/v1/account/balanceНужен ключОстаток кредитов, идентификатор аккаунта и маскированный ключ. Вызывайте перед большой выгрузкой, чтобы не упереться в 403 на середине.
Параметры
Параметров нет.
Ответ 200
{
"success": true,
"account_id": 123456,
"credits_remaining": 1000,
"api_key": "uk_xxxxx..."
}Статистика аккаунта
/api/v1/account/statsНужен ключСколько задач создано, сколько адресов проверено за всё время и какая средняя доставляемость получилась. В last_list — разбивка по последней задаче.
Параметры
Параметров нет.
Ответ 200
{
"tasks_count": 42,
"emails_checked": 12500,
"avg_deliverability": 78,
"last_list": { "total": 100, "good": 80, "bad": 15, "unknown": 5 }
}История платежей
/api/v1/billing/historyНужен ключСписок транзакций с пагинацией, новые первыми: сумма, статус, что именно куплено и идентификатор платежа.
Параметры
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 }
}ESP-провайдеры
Интерфейс для партнёров, которые заводят аккаунты и продают кредиты своим клиентам. Авторизация отдельным токеном, а не ключом аккаунта.
Рассчитать стоимость кредитов
/api/v1/esp/priceТокен ESPВозвращает цену за указанный объём с учётом действующей для партнёра сетки. Считать на своей стороне не нужно — цена за адрес зависит от объёма.
Параметры
x-esp-tokenstring· заголовок· обязательныйТокен партнёра, выдаётся при подключении.
countnumber· в строке запроса· обязательныйКоличество кредитов, минимум 1.
Ответ 200
{
"success": true,
"credits": 10000,
"price": 2000,
"price_per_email": 0.2,
"currency": "RUB"
}Создать аккаунт или пополнить кредиты
/api/v1/esp/provisionТокен ESPОдин метод на оба случая: если аккаунта с таким адресом нет — он создаётся и получает ключ, если есть — кредиты просто зачисляются. Что именно произошло, видно по флагу is_new_account.
Передавайте external_id — номер заказа на вашей стороне. По нему мы отсекаем повторную обработку того же платежа и возвращаем is_duplicate: true вместо второго зачисления.
Параметры
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
}Попробовать вживую
Эта страница — справочник для чтения и поиска. Если нужно отправить запрос прямо из браузера и посмотреть на настоящий ответ, откройте интерактивную песочницу: там подставляется ваш ключ, а каждый эндпоинт можно вызвать кнопкой.
Открыть песочницу APIЧастые вопросы
Сколько стоит проверка одного адреса через API?
Одна проверка — 1 кредит. Кредит списывается в момент постановки адреса в очередь. Адреса с неверным синтаксисом при пакетной отправке не тарифицируются: они отсеиваются до очереди и возвращаются в поле invalid_details.
Есть ли ограничение на частоту запросов?
Нет. Rate limits не выставлены, отправлять можно с любой скоростью. Упереться можно только в остаток кредитов — тогда придёт 403.
Сколько адресов можно отправить за один раз?
Пакетный метод принимает до миллионов адресов в одной задаче. Разбивать список на части ради обхода лимитов не нужно.
Как узнать, что проверка закончилась, не опрашивая статус?
Передайте webhook_url при создании задачи — когда все адреса проверены, на этот адрес уйдёт POST с результатами. Если webhook не подходит, опрашивайте GET /api/v1/tasks/:taskId раз в 5–10 секунд.
Чем API-ключ отличается от Bearer-токена?
Возможности одинаковые, разница в сроке жизни. Ключ в заголовке x-api-key не истекает и удобен для серверных интеграций. JWT живёт час, обновляется refresh-токеном и нужен там, где вечный ключ нельзя отдавать в браузер.
Что делать, если задача завершилась со статусом failed?
Напишите на support@uchecker.net и приложите task_id — по нему видно, на каком этапе задача упала. Кредиты за неотработавшую задачу возвращаются.
Можно ли протестировать API до оплаты?
Да. После регистрации на балансе есть бесплатные кредиты, а любой эндпоинт можно вызвать прямо из браузера в интерактивной песочнице.
Поддержка
Вопросы по интеграции — на support@uchecker.net. Если задача упала со статусом failed, приложите к письму task_id: по нему видно, что именно пошло не так.
