Документация API для разработчиков

Начало работы

Каждый платный тариф включает полный доступ к REST API. Создайте ключ в своём аккаунте в разделе Аккаунт → API-ключи и передавайте его в каждом запросе:

curl -H "X-Api-Key: YOUR_KEY" https://mailflow.top/api/index.php/lists

Базовый URL: https://mailflow.top/api/index.php · Ответы приходят в формате JSON с полем status, равным success или error. API недоступен на бесплатном тарифе.

Основные ресурсы

Платформа совместима с MailWizz, поэтому полный базовый API — списки, подписчики, сегменты, пользовательские поля, кампании, отслеживание, шаблоны, транзакционные письма, возвраты, отписки — интерактивно задокументирован (OpenAPI) по адресу:

→ Интерактивный справочник API (OpenAPI)

Существующие SDK для MailWizz (например, официальный PHP SDK) работают сразу — просто укажите в них базовый URL, приведённый выше.

AI-эндпоинты

AI-функции — полноправная часть API. Тот же ключ, та же аутентификация, те же лимиты тарифа и учёт кредитов, что и в веб-приложении.

GET /ai/credits

Ваш счётчик AI-кредитов за текущий месяц. Кредиты начисляются на расчётный месяц, неиспользованные кредиты не переносятся.

{"status":"success","data":{"unlimited":false,"limit":750,"used":112,"remaining":638}}

GET /ai/replies

Классификация Smart Replies для ваших кампаний: передавайте в CRM, кто заинтересован, кто задал вопрос, кто пожаловался. Фильтры: category (interested, question, complaint, unsubscribe_request, auto_reply, out_of_office, bounce, other), campaign_uid, since (YYYY-MM-DD), page, per_page (не более 50).

curl -H "X-Api-Key: YOUR_KEY" \
  "https://mailflow.top/api/index.php/ai/replies?category=interested&since=2026-08-01"

{"status":"success","data":{"count":42,"current_page":1,"per_page":20,"total_pages":3,
  "records":[{"from_email":"[email protected]","subject":"RE: your offer",
    "category":"interested","confidence":98,"engine":"embeddings",
    "summary":"...","suggested_reply":"...","date_added":"2026-08-24 18:21:19",
    "campaign_uid":"py794hjqk8a8d"}]}}

GET /ai/tiers

AI-уровни вовлечённости (vip, engaged, passive, at_risk, dormant) для каждого списка — та же оценка, на которой работают автопилот и возврат подписчиков.

{"status":"success","data":{"records":[
  {"list_uid":"qk661oq7nl8c1","name":"Main list","tiers":{"engaged":1200,"passive":3400,"dormant":900}}]}}

POST /ai/subject-lines

Генерация тем писем на любом языке. Тело запроса: topic (обязательно), count (1–5, по умолчанию 3), language (необязательно). Расходует AI-кредиты так же, как веб-редактор.

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"topic":"Summer sale for B2B customers","count":3,"language":"Greek"}' \
  https://mailflow.top/api/index.php/ai/subject-lines

{"status":"success","data":{"subjects":["...","...","..."],"credits_remaining":636}}

GET /ai/flows · POST /ai/flows/author · POST /ai/flows/<uid>/enroll · POST /ai/flows/<uid>/status

AI-конструктор сценариев через API: получайте список своих сценариев с живыми счётчиками; поручите AI создать полный сценарий по цели, сформулированной простым языком ({"goal":"...","list_uid":"..."} — возвращает черновик, который вы активируете через {"status":"active"}); добавляйте подписчика в сценарий ({"email":"..."}).

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"When someone replies interested, notify me, wait 2 days, then send a case study"}' \
  https://mailflow.top/api/index.php/ai/flows/author

Ошибки и лимиты

401 — отсутствует или недействителен X-Api-Key
403 — эта функция не входит в ваш тариф
422 — отсутствующие или недопустимые параметры
429 — достигнут лимит AI-кредитов или месячная норма AI; сбрасывается в вашу следующую дату списания оплаты

Всплески запросов ограничиваются для каждого ключа — реализуйте экспоненциальную задержку (backoff) при ответе 429. Есть вопросы? Свяжитесь с нами или создайте обращение в поддержку.

API для разработчиков