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

Единый REST API для списков, кампаний, транзакционных писем — и AI.

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

Каждый платный тариф включает полный доступ к 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) вместе со всеми эндпоинтами MailFlow с этой страницы по адресу:

→ Интерактивный справочник 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

Создайте собственное приложение на базе MailFlow

Всё, что вы делаете в веб-приложении, можно сделать через API, поэтому MailFlow можно управлять из вашего собственного ПО. Типичный сценарий:

  1. Создайте список и добавьте контакты: POST /lists, POST /lists/<list_uid>/subscribers/bulk.
  2. Найдите новые контакты с помощью DataStack: POST /datastack/import.
  3. Создайте кампанию самостоятельно (POST /campaigns) или поручите её написание AI: POST /ai/campaigns.
  4. Проверьте черновик AI и запланируйте отправку: GET /ai/campaigns/<run_id>, POST /ai/campaigns/<run_id>/approve.
  5. Получите результаты: GET /analytics/campaigns, GET /campaigns/<campaign_uid>/clicks.

Длительные задачи (написание текстов AI, чтение сайтов, импорт из DataStack) выполняются в фоне: запрос возвращает 202 с job_id, а GET /ai/jobs/<job_id> сообщает, когда задача завершена.

Аналитика

Те же цифры, что в панели управления и отчётах по кампаниям. Даты указываются в UTC; по умолчанию from и to (YYYY-MM-DD) охватывают последние 30 дней. Итоги по аккаунту обновляются каждые несколько минут.

  • GET /analytics/overview — списки, подписчики, кампании и результаты отправки за период: отправлено, доставлено, открытия, клики, возвраты, жалобы, отписки и их процентные показатели.
  • GET /analytics/timeline — те же результаты по дням (или по часам с interval=hour), а также новые подписчики.
  • GET /analytics/campaigns — по одной строке на кампанию с её результатами; фильтр — status.
  • GET /campaigns/<campaign_uid>/opens и /clicks — кто открыл письмо или кликнул, когда, откуда и с какого устройства (unique=1 — только первые события).
  • GET /campaigns/<campaign_uid>/links, /locations, /devices, /timeline, /abuse-reports — клики по каждой ссылке, результаты по странам и городам, по типам устройств и по часам, а также жалобы на злоупотребления.
  • GET /campaigns/<campaign_uid>/stats, /bounces, /unsubscribes, /complaints, /delivery-logs — основные отчёты по кампании.
  • GET /lists/<list_uid>/stats — подписчики по статусам и источникам, ежедневный прирост и кампании, отправленные по списку.
curl -H "X-Api-Key: YOUR_KEY" \
  "https://mailflow.top/api/index.php/analytics/overview?from=2026-09-01&to=2026-09-30"

{"status":"success","data":{"period":{"from":"2026-09-01","to":"2026-09-30","timezone":"UTC"},
  "lists":9,"subscribers":{"total":52040,"confirmed":50102,"unsubscribed":311},
  "campaigns":{"total":24,"sent":20,"draft":4},
  "activity":{"sent":48210,"delivered":47650,"unique_opens":14230,"unique_clicks":2210,
    "bounces":402,"complaints":3,"unsubscribes":95,"open_rate":29.86,"click_rate":4.64}}}

Аккаунт и настройка отправки

  • GET /account · PUT /account — ваш профиль, тариф, лимит отправки и другие ограничения; изменение имени, телефона или часового пояса.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> — группы кампаний.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails — списки исключений (до 10 000 адресов за один запрос).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= — ваш чёрный список и проверка, заблокирован ли адрес где-либо.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify — домены отправки с записями DKIM, SPF и DMARC, которые нужно опубликовать.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify — ваши собственные домены для отслеживания ссылок.
  • GET /delivery-servers · GET /countries — серверы, через которые вы можете отправлять письма, и страны с их зонами.

AI-кампании

Поручите AI писать кампании за вас — с вашей проверкой или без неё. AI использует профиль вашего бизнеса, выбирает аудиторию и время отправки, проверяет письмо на прохождение спам-фильтров и пишет его на языке каждого подписчика.

  • POST /ai/campaigns — укажите AI, что отправить: goal (обязательно), list_uid (список, auto или prospects), audience, business, template_uid, follow_up, auto_send.
  • POST /ai/campaigns/prepare — AI решает, что отправить дальше (не более 3 в день); необязательный параметр hint.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — AI-кампании с темами писем, аудиторией, предложенным временем и проверкой на спам (html=1 добавляет само письмо).
  • POST /ai/campaigns/<run_id>/approve — запланировать отправку: when = proposed, now или custom с send_at; необязательный параметр max_send.
  • POST /ai/campaigns/<run_id>/revise (с feedback) · POST /ai/campaigns/<run_id>/discard — запросить изменения или отказаться от черновика.
  • GET /ai/jobs/<job_id> — состояние фоновой задачи и созданные ею AI-кампании.
  • GET|PUT /ai/hands-off — режим автопилота: AI планирует, пишет и отправляет кампании, не дожидаясь вас ({"enabled":true}).
curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"Invite our customers to the autumn webinar","list_uid":"auto"}' \
  https://mailflow.top/api/index.php/ai/campaigns

{"status":"success","data":{"job_id":512,"job_status":"queued","check":"/ai/jobs/512"}}

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

{"status":"success","data":{"job_id":512,"type":"autopilot","status":"done","ai_campaigns":[331],"sent":false}}

Профили бизнеса

AI пишет от имени вашего бизнеса. Заведите по одному профилю на каждый сайт:

  • GET|POST /ai/businesses — ваши бизнесы; чтобы добавить новый, передайте website.
  • GET|PUT|DELETE /ai/businesses/<domain> — профиль, отправитель (from_name, from_email, reply_to) и реквизиты компании (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main — поручить AI прочитать сайт и заполнить профиль; сделать бизнес основным.

Потенциальные клиенты из DataStack

Находите свежие рабочие и личные email-адреса и импортируйте их прямо в свои списки. Импорт учитывается в рамках вашего тарифа, а подсчёт бесплатный.

  • GET /datastack/credits — сколько адресов ваш тариф ещё позволяет импортировать в этом месяце.
  • GET /datastack/count — сколько адресов доступно по country, niche (категории бизнеса), keyword и role (личные адреса). Бесплатно.
  • POST /datastack/import — импорт адресов типа business и/или personal в list_uid (фоновая задача). Новые адреса проверяются до того, как на них будет отправлена какая-либо кампания.
curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"list_uid":"cr5899rtqe668","business":2000,"country":"Greece","niche":"dentist, hotel"}' \
  https://mailflow.top/api/index.php/datastack/import

{"status":"success","data":{"job_id":513,"job_status":"queued","check":"/ai/jobs/513","list_uid":"cr5899rtqe668"}}

Обращения в поддержку

  • GET|POST /support-tickets — ваши обращения; чтобы создать новое, передайте subject, message, category и priority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close — прочитать переписку, ответить, закрыть.

Права доступа API-ключей

Ключ можно ограничить определёнными эндпоинтами. В разделе Аккаунт → API-ключи откройте ключ для редактирования, включите права доступа и отметьте, что ему разрешено использовать. Эндпоинты с этой страницы перечислены там с префиксом MailFlow.

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

  • 400 — отсутствует или недействителен X-Api-Key, либо у ключа нет прав на этот эндпоинт
  • 402 — в этом месяце недостаточно кредитов DataStack
  • 403 — функция не входит в ваш тариф или достигнут лимит тарифа
  • 404 — список, кампания или другой объект не существует в вашем аккаунте
  • 409 — объект находится в неподходящем состоянии (например, утвердить можно только черновики)
  • 422 — отсутствующие или недопустимые параметры
  • 429 — достигнут лимит AI-кредитов или месячная норма AI; сбрасывается в вашу следующую дату списания оплаты

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