API документация
API ключи

Base URL + Bearer authentication

Все эндпоинты принимают JSON и требуют API-ключ в заголовке Authorization. Создайте ключ на странице API ключи.

Base URL:  https://<your-host>/api
Format:    JSON request / JSON response
Auth:      Authorization: Bearer ck_xxxxxxxxxxxx

Authentication

Пользовательский API-ключ выдаётся на /api-keys.html. Ключ показывается один раз при создании — сохраните его. Скомпрометированный ключ отзовите на той же странице и создайте новый.

# bash
curl -H "Authorization: Bearer ck_abc123..." \
     https://your-host/api/lists
Внимание: ключи имеют полный доступ к вашему аккаунту. Не коммитьте их в репозитории и не шарьте публично. Максимум 10 активных ключей на аккаунт.

Rate limits

Глобально 300 запросов в минуту на IP. Отдельные эндпоинты имеют per-user лимиты (указаны ниже).

В ответ на каждый запрос сервер возвращает заголовки:

  • X-RateLimit-Limit — потолок для этого окна
  • X-RateLimit-Remaining — сколько осталось
  • X-RateLimit-Reset — UNIX-время сброса счётчика

При превышении — 429 Too Many Requests.

Error format

Ошибки возвращают не-2xx статус и JSON-тело { "error": "message" }. 402 может содержать { "buy_tokens": true } — клиенту следует перенаправить на биллинг.

{
  "error": "Insufficient tokens",
  "buy_tokens": true
}
  • 400 — невалидный запрос (обязательные поля, формат)
  • 401 — нет или истёк токен/ключ
  • 402 — недостаточно токенов на балансе
  • 404 — ресурс не найден или не принадлежит вам
  • 429 — rate limit
  • 5xx — серверная ошибка

Lists

Управление email-базами. Всё ограничено вашим аккаунтом — чужие списки возвращают 404.

GET /api/lists

Список всех ваших баз с агрегированными счётчиками valid / risky / invalid и статусом.
curl -H "Authorization: Bearer $CK" https://your-host/api/lists

GET /api/lists/:id

Метаданные одной базы: имя, статус, теги, счётчики, источник (upload / collect / dork), настройки SMTP-верификации.

POST /api/lists/upload

Загрузить CSV или TXT файл. Фоновая задача распарсит его, провалидирует синтаксис, отфильтрует disposable/role, проверит MX и обогатит (geo/gender по домену и имени).
Content-Type
multipart/form-data
Поля
file (файл), name (опционально — имя базы)
Лимит
20 загрузок в час на пользователя, до 50 МБ
curl -X POST \
  -H "Authorization: Bearer $CK" \
  -F "[email protected]" \
  -F "name=Campaign Q2" \
  https://your-host/api/lists/upload

GET /api/lists/:id/contacts

Постраничный список контактов. Поддерживает фильтры по статусу, поиск, пагинацию.
Query
page, limit (до 200), status (valid/risky/invalid/pending), search

GET /api/lists/:id/export

Экспорт базы в CSV. Возвращает файл напрямую.
Query
status (фильтр, по умолчанию all), columns (csv-список полей)
Лимит
10 экспортов в минуту

DELETE /api/lists/:id

Удаляет базу и все её контакты (cascade). Необратимо.

POST /api/lists/validate-single

Разовая проверка одного email без создания базы. Списывает 1 токен.
curl -X POST \
  -H "Authorization: Bearer $CK" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}' \
  https://your-host/api/lists/validate-single

Parser / Collect

Асинхронный сбор баз по дорк-запросам / ключевым словам. Результат оседает как обычная база (source = 'dork' | 'collect').

POST /api/parser

Создаёт задачу парсинга. Резервирует токены наперёд — недостающие возвращаются после выполнения.
Body
query, source, limit, name
Лимит
5 задач в час на пользователя

GET /api/parser

Все ваши задачи парсинга со статусом (pending / running / done / error).

GET /api/parser/:id

Статус конкретной задачи + ссылка на получившуюся базу (когда готова).

Suppress list

Глобальное исключение: email в suppress-листе автоматически помечается как invalid при любой валидации и пропускается при сборе и парсинге. Идеально для отписавшихся, жалоб на спам и известных bounces.

GET /api/suppress/list

Постраничный список suppress-записей. 100 записей на страницу.
Query
page (default 1)
Response
{ total, page, limit, emails: [{ email, added_at }] }

POST /api/suppress/add

Батч-добавление адресов. Дубликаты и невалидные форматы отбрасываются серверсайдом.
Body
{ "emails": ["[email protected]", "[email protected]"] }, до 10 000 за вызов
Response
{ added, total_sent }
Лимит
30 операций в час на пользователя
curl -X POST \
  -H "Authorization: Bearer $CK" \
  -H "Content-Type: application/json" \
  -d '{"emails":["[email protected]","[email protected]"]}' \
  https://your-host/api/suppress/add

DELETE /api/suppress/remove

Удалить один адрес из suppress-листа.
Body
{ "email": "[email protected]" }

DELETE /api/suppress/clear

Полностью очистить suppress-лист аккаунта. Необратимо.
Response
{ deleted: N }