Developer API

One REST API for lists, campaigns, transactional email — and the AI.

Getting started

Every paid plan includes full REST API access. Generate a key in your account under Account → API keys, then send it with every request:

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

Base URL: https://mailflow.top/api/index.php · Responses are JSON with a status field of success or error. The API is not available on the Free plan.

Core resources

The platform is MailWizz-compatible, so the complete core API — lists, subscribers, segments, custom fields, campaigns, tracking, templates, transactional email, bounces, unsubscribes — is documented interactively (OpenAPI), together with every MailFlow endpoint on this page, at:

→ Interactive API reference (OpenAPI)

Existing MailWizz SDKs (e.g. the official PHP SDK) work out of the box — point them at the base URL above.

AI endpoints

The AI features are first-class API citizens. Same key, same auth, and the same plan limits and credit metering as the web app.

GET /ai/credits

Your AI credit meter for the current month. Credits are per billing month and unused credits do not carry over.

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

GET /ai/replies

Smart Replies classifications for your campaigns — feed your CRM with who is interested, who asked a question, who complained. Filters: category (interested, question, complaint, unsubscribe_request, auto_reply, out_of_office, bounce, other), campaign_uid, since (YYYY-MM-DD), page, per_page (max 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 engagement tiers (vip, engaged, passive, at_risk, dormant) per list — the same scoring that drives autopilot and win-back.

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

POST /ai/subject-lines

Generate subject lines in any language. Body: topic (required), count (1–5, default 3), language (optional). Spends AI credits like the web editor.

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 Flow Builder over the API: list your flows with live counters; have the AI author a complete flow from a plain-language goal ({"goal":"...","list_uid":"..."} — returns a draft you activate with {"status":"active"}); push a subscriber into a flow ({"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

Build your own app on MailFlow

Everything you do in the web app can be done over the API, so you can run MailFlow from your own software. A typical flow:

  1. Create a list and add contacts: POST /lists, POST /lists/<list_uid>/subscribers/bulk.
  2. Find new contacts with DataStack: POST /datastack/import.
  3. Create a campaign yourself (POST /campaigns) or let the AI write it: POST /ai/campaigns.
  4. Review and schedule the AI draft: GET /ai/campaigns/<run_id>, POST /ai/campaigns/<run_id>/approve.
  5. Read the results: GET /analytics/campaigns, GET /campaigns/<campaign_uid>/clicks.

Long tasks (AI writing, website reading, DataStack imports) run in the background: the call answers 202 with a job_id, and GET /ai/jobs/<job_id> tells you when it is done.

Analytics

The same numbers as your dashboard and campaign reports. Dates are UTC; from and to (YYYY-MM-DD) default to the last 30 days. Account totals are refreshed every few minutes.

  • GET /analytics/overview — lists, subscribers, campaigns and sending results for a period: sent, delivered, opens, clicks, bounces, complaints, unsubscribes and their rates.
  • GET /analytics/timeline — the same results per day (or per hour with interval=hour), plus new subscribers.
  • GET /analytics/campaigns — one row per campaign with its results; filter with status.
  • GET /campaigns/<campaign_uid>/opens and /clicks — who opened or clicked, when, from where and on which device (unique=1 for first events only).
  • GET /campaigns/<campaign_uid>/links, /locations, /devices, /timeline, /abuse-reports — clicks per link, results per country and city, per device type, per hour, and abuse reports.
  • GET /campaigns/<campaign_uid>/stats, /bounces, /unsubscribes, /complaints, /delivery-logs — the core campaign reports.
  • GET /lists/<list_uid>/stats — subscribers per status and source, daily growth, and the campaigns sent to the list.
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}}}

Account & sending setup

  • GET /account · PUT /account — your profile, plan, sending quota and limits; update your name, phone or timezone.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> — campaign groups.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails — suppression lists (up to 10,000 emails per call).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= — your blacklist, and whether an address is blocked anywhere.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify — sending domains with the DKIM, SPF and DMARC records to publish.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify — your own link-tracking domains.
  • GET /delivery-servers · GET /countries — the servers you can send through, and countries with their zones.

AI campaigns

Let the AI write campaigns for you, with or without your review. The AI uses your business profile, picks the audience and the send time, checks the email against spam filters and writes it in each subscriber’s language.

  • POST /ai/campaigns — tell the AI what to send: goal (required), list_uid (a list, auto or prospects), audience, business, template_uid, follow_up, auto_send. How to send it goes in settings_brief in plain words (a date, each reader’s local time, a daily sending window, a weekly repeat, a limit, a subject A/B test, your tracking domain, moving openers to a list, tagging them, a webhook, extra tags) or as explicit settings.
  • POST /ai/campaigns/prepare — the AI decides what to send next (up to 3 per day); optional hint.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — AI campaigns with subjects, audience, proposed time, spam check and the settings the AI chose with its reasons (html=1 adds the email).
  • GET|PUT /ai/campaigns/<run_id>/settings — every MailWizz campaign setting of the draft with its allowed values: options (tracking_domain_id, max_send_count, max_send_count_random, embed_images, plain_text_email, preheader, email_stats…), tracking (open_tracking, url_tracking, smart_open_tracking, smart_click_tracking, crawler exclusion), the A/B test (ab_enabled, ab_subjects, winner criteria), actions upon open/sent (open_actions, sent_actions, open_field_actions, sent_field_actions, open_webhooks, extra_tags, open/unopen filter, suppression lists) and the confirmation step (send_at, cronjob recurring, send_between_start/send_between_interval, timewarp_enabled/timewarp_hour/timewarp_minute). PUT changes any of them, validated by MailWizz’s own rules. Delivery servers are always chosen by MailWizz itself.
  • POST /ai/campaigns/<run_id>/approve — schedule it: when = proposed, now or custom with send_at; optional max_send. The same checks as the campaign confirmation step apply (template, verified sending domain when your plan requires it, active-campaign limit, blacklisted words).
  • POST /ai/campaigns/<run_id>/revise (with feedback) · POST /ai/campaigns/<run_id>/discard — ask for changes, or drop the draft.
  • GET /ai/jobs/<job_id> — state of a background job and the AI campaigns it created.
  • GET|PUT /ai/hands-off — hands-off mode: the AI plans, writes and sends without waiting for you ({"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}}

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"Invite our customers to the autumn webinar",
       "settings_brief":"Send Tuesday at 9 in the morning at each reader\u2019s local time, only 5000 people, A/B test the subject",
       "settings":{"tracking_domain_id":"7"}}' \
  https://mailflow.top/api/index.php/ai/campaigns

curl -X PUT -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"settings":{"smart_open_tracking":"yes","send_between_start":"09:00:00","send_between_interval":"8"}}' \
  https://mailflow.top/api/index.php/ai/campaigns/331/settings

Business profiles

The AI writes as your business. Keep one profile per website:

  • GET|POST /ai/businesses — your businesses; add one with website.
  • GET|PUT|DELETE /ai/businesses/<domain> — profile, sender (from_name, from_email, reply_to) and company details (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main — let the AI read the website and fill the profile; make it your main business.

DataStack prospects

Find fresh business and personal email addresses and import them straight into your lists. Imports are metered by your plan; counts are free.

  • GET /datastack/credits — how many addresses your plan still lets you import this month.
  • GET /datastack/count — how many addresses exist for country, niche (business categories), keyword and role (personal). Free.
  • POST /datastack/import — import business and/or personal addresses into list_uid (background job). New addresses are checked before any campaign sends to them.
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"}}

Support tickets

  • GET|POST /support-tickets — your tickets; open one with subject, message, category and priority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close — read the conversation, reply, close.

API key permissions

A key can be limited to certain endpoints. Under Account → API keys, edit the key, enable permissions and tick what it may use. The endpoints on this page are listed with the prefix MailFlow.

Errors & limits

  • 400 — missing or invalid X-Api-Key, or the key has no permission for this endpoint
  • 402 — not enough DataStack credits this month
  • 403 — the feature is not included in your plan, or a plan limit is reached
  • 404 — the list, campaign or other item does not exist in your account
  • 409 — the item is not in the right state (for example, only drafts can be approved)
  • 422 — missing/invalid parameters
  • 429 — AI credit limit or monthly AI allowance reached; resets on your next billing date

Bursts are throttled per key — implement exponential backoff on 429. Questions? Contact us or open a support ticket.