Entwickler-API

Eine REST-API für Listen, Kampagnen, Transaktions-E-Mails – und die KI.

Erste Schritte

Jeder kostenpflichtige Tarif beinhaltet vollen Zugriff auf die REST-API. Erstellen Sie in Ihrem Konto unter Konto → API-Schlüssel einen Schlüssel und senden Sie ihn mit jeder Anfrage mit:

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

Basis-URL: https://mailflow.top/api/index.php · Antworten erfolgen im JSON-Format mit einem status-Feld mit dem Wert success oder error. Im kostenlosen Tarif ist die API nicht verfügbar.

Kernressourcen

Die Plattform ist MailWizz-kompatibel, daher ist die komplette Kern-API – Listen, Abonnenten, Segmente, benutzerdefinierte Felder, Kampagnen, Tracking, Vorlagen, Transaktions-E-Mails, Bounces, Abmeldungen – zusammen mit allen MailFlow-Endpunkten dieser Seite interaktiv (OpenAPI) dokumentiert unter:

→ Interaktive API-Referenz (OpenAPI)

Bestehende MailWizz-SDKs (z. B. das offizielle PHP SDK) funktionieren sofort – richten Sie sie einfach auf die oben genannte Basis-URL aus.

KI-Endpunkte

Die KI-Funktionen sind vollwertige Bestandteile der API. Derselbe Schlüssel, dieselbe Authentifizierung sowie dieselben Tariflimits und dieselbe Credit-Abrechnung wie in der Web-App.

GET /ai/credits

Ihr KI-Credit-Zähler für den aktuellen Monat. Credits gelten pro Abrechnungsmonat; nicht genutzte Credits werden nicht übertragen.

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

GET /ai/replies

Smart-Replies-Klassifizierungen für Ihre Kampagnen – versorgen Sie Ihr CRM mit Informationen darüber, wer interessiert ist, wer eine Frage gestellt und wer sich beschwert hat. Filter: 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

KI-Engagement-Stufen (vip, engaged, passive, at_risk, dormant) pro Liste – dasselbe Scoring, das Autopilot und Rückgewinnung steuert.

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

POST /ai/subject-lines

Erzeugt Betreffzeilen in jeder Sprache. Body: topic (erforderlich), count (1–5, Standard 3), language (optional). Verbraucht KI-Credits wie der 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

KI-Flow-Builder über die API: Listen Sie Ihre Workflows mit Live-Zählern auf; lassen Sie die KI aus einem in Alltagssprache formulierten Ziel einen kompletten Workflow erstellen ({"goal":"...","list_uid":"..."} – liefert einen Entwurf, den Sie mit {"status":"active"} aktivieren); fügen Sie einen Abonnenten in einen Workflow ein ({"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

Eigene App auf Basis von MailFlow entwickeln

Alles, was Sie in der Web-App tun, lässt sich auch über die API erledigen – so können Sie MailFlow aus Ihrer eigenen Software steuern. Ein typischer Ablauf:

  1. Liste anlegen und Kontakte hinzufügen: POST /lists, POST /lists/<list_uid>/subscribers/bulk.
  2. Neue Kontakte mit DataStack finden: POST /datastack/import.
  3. Kampagne selbst erstellen (POST /campaigns) oder von der KI schreiben lassen: POST /ai/campaigns.
  4. KI-Entwurf prüfen und einplanen: GET /ai/campaigns/<run_id>, POST /ai/campaigns/<run_id>/approve.
  5. Ergebnisse abrufen: GET /analytics/campaigns, GET /campaigns/<campaign_uid>/clicks.

Lange Aufgaben (KI-Texterstellung, Auslesen von Websites, DataStack-Importe) laufen im Hintergrund: Der Aufruf antwortet mit 202 und einer job_id, und GET /ai/jobs/<job_id> zeigt Ihnen, wann die Aufgabe erledigt ist.

Analysen

Dieselben Zahlen wie in Ihrem Dashboard und Ihren Kampagnenberichten. Datumsangaben sind in UTC; from und to (YYYY-MM-DD) umfassen standardmäßig die letzten 30 Tage. Die Kontosummen werden alle paar Minuten aktualisiert.

  • GET /analytics/overview – Listen, Abonnenten, Kampagnen und Versandergebnisse für einen Zeitraum: gesendet, zugestellt, Öffnungen, Klicks, Bounces, Beschwerden, Abmeldungen und die jeweiligen Raten.
  • GET /analytics/timeline – dieselben Ergebnisse pro Tag (oder pro Stunde mit interval=hour), dazu neue Abonnenten.
  • GET /analytics/campaigns – eine Zeile pro Kampagne mit ihren Ergebnissen; filtern Sie mit status.
  • GET /campaigns/<campaign_uid>/opens und /clicks – wer geöffnet oder geklickt hat, wann, von wo und auf welchem Gerät (unique=1 nur für erste Ereignisse).
  • GET /campaigns/<campaign_uid>/links, /locations, /devices, /timeline, /abuse-reports – Klicks pro Link, Ergebnisse nach Land und Stadt, nach Gerätetyp und pro Stunde sowie Missbrauchsmeldungen.
  • GET /campaigns/<campaign_uid>/stats, /bounces, /unsubscribes, /complaints, /delivery-logs – die grundlegenden Kampagnenberichte.
  • GET /lists/<list_uid>/stats – Abonnenten nach Status und Quelle, tägliches Wachstum und die an die Liste gesendeten Kampagnen.
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}}}

Konto & Versandeinrichtung

  • GET /account · PUT /account – Ihr Profil, Tarif, Versandkontingent und Ihre Limits; ändern Sie Ihren Namen, Ihre Telefonnummer oder Ihre Zeitzone.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> – Kampagnengruppen.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails – Sperrlisten (bis zu 10.000 E-Mails pro Aufruf).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= – Ihre Blockliste und ob eine Adresse irgendwo gesperrt ist.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify – Versanddomains mit den zu veröffentlichenden DKIM-, SPF- und DMARC-Einträgen.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify – Ihre eigenen Tracking-Domains für Links.
  • GET /delivery-servers · GET /countries – die Server, über die Sie versenden können, und Länder mit ihren Zonen.

KI-Kampagnen

Lassen Sie die KI Kampagnen für Sie schreiben – mit oder ohne Ihre Prüfung. Die KI nutzt Ihr Unternehmensprofil, wählt Zielgruppe und Versandzeitpunkt, prüft die E-Mail gegen Spamfilter und schreibt sie in der Sprache jedes Abonnenten.

  • POST /ai/campaigns — sagen Sie der KI, was gesendet werden soll: goal (Pflicht), list_uid (eine Liste, auto oder prospects), audience, business, template_uid, follow_up, auto_send. Wie gesendet wird, steht in settings_brief in einfachen Worten (ein Datum, die Ortszeit jedes Lesers, ein tägliches Sendefenster, eine wöchentliche Wiederholung, ein Limit, ein A/B-Test der Betreffzeile, Ihre Tracking-Domain, Öffner in eine Liste verschieben, sie markieren, ein Webhook, zusätzliche Tags) oder als explizite settings.
  • POST /ai/campaigns/prepare – die KI entscheidet, was als Nächstes versendet wird (bis zu 3 pro Tag); optional hint.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — KI-Kampagnen mit Betreffzeilen, Zielgruppe, vorgeschlagener Zeit, Spam-Prüfung und den von der KI gewählten Einstellungen samt Begründung (html=1 fügt die E-Mail hinzu).
  • GET|PUT /ai/campaigns/<run_id>/settings — jede MailWizz-Kampagneneinstellung des Entwurfs mit ihren erlaubten Werten: Optionen (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-Ausschluss), der A/B-Test (ab_enabled, ab_subjects, Gewinnerkriterien), Aktionen beim Öffnen/Senden (open_actions, sent_actions, open_field_actions, sent_field_actions, open_webhooks, extra_tags, Filter geöffnet/nicht geöffnet, Sperrlisten) und der Bestätigungsschritt (send_at, cronjob wiederkehrend, send_between_start/send_between_interval, timewarp_enabled/timewarp_hour/timewarp_minute). PUT ändert jede davon, geprüft nach MailWizz’ eigenen Regeln. Die Zustellserver wählt immer MailWizz selbst.
  • POST /ai/campaigns/<run_id>/approve — planen: when = proposed, now oder custom mit send_at; optional max_send. Es gelten dieselben Prüfungen wie im Bestätigungsschritt der Kampagne (Vorlage, verifizierte Absenderdomain, wenn Ihr Tarif sie verlangt, Limit aktiver Kampagnen, Wörter auf der Sperrliste).
  • POST /ai/campaigns/<run_id>/revise (mit feedback) · POST /ai/campaigns/<run_id>/discard – Änderungen anfordern oder den Entwurf verwerfen.
  • GET /ai/jobs/<job_id> – Status eines Hintergrundjobs und die von ihm erstellten KI-Kampagnen.
  • GET|PUT /ai/hands-off – Vollautomatik-Modus: Die KI plant, schreibt und versendet, ohne auf Sie zu warten ({"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

Unternehmensprofile

Die KI schreibt im Namen Ihres Unternehmens. Legen Sie pro Website ein Profil an:

  • GET|POST /ai/businesses – Ihre Unternehmen; fügen Sie mit website eines hinzu.
  • GET|PUT|DELETE /ai/businesses/<domain> – Profil, Absender (from_name, from_email, reply_to) und Firmendaten (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main – die KI die Website lesen und das Profil ausfüllen lassen; als Hauptunternehmen festlegen.

DataStack-Leads

Finden Sie aktuelle geschäftliche und private E-Mail-Adressen und importieren Sie sie direkt in Ihre Listen. Importe werden über Ihren Tarif abgerechnet; Zählungen sind kostenlos.

  • GET /datastack/credits – wie viele Adressen Sie laut Ihrem Tarif in diesem Monat noch importieren können.
  • GET /datastack/count – wie viele Adressen es für country, niche (Branchen), keyword und role (privat) gibt. Kostenlos.
  • POST /datastack/import – importiert Adressen vom Typ business und/oder personal in list_uid (Hintergrundjob). Neue Adressen werden geprüft, bevor eine Kampagne an sie versendet wird.
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 – Ihre Tickets; eröffnen Sie eines mit subject, message, category und priority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close – Verlauf lesen, antworten, schließen.

Berechtigungen für API-Schlüssel

Ein Schlüssel kann auf bestimmte Endpunkte beschränkt werden. Bearbeiten Sie unter Konto → API-Schlüssel den Schlüssel, aktivieren Sie die Berechtigungen und haken Sie an, was er nutzen darf. Die Endpunkte dieser Seite sind mit dem Präfix MailFlow aufgeführt.

Fehler & Limits

  • 400 – X-Api-Key fehlt oder ist ungültig, oder der Schlüssel hat keine Berechtigung für diesen Endpunkt
  • 402 – nicht genügend DataStack-Credits in diesem Monat
  • 403 – die Funktion ist in Ihrem Tarif nicht enthalten, oder ein Tariflimit ist erreicht
  • 404 – die Liste, Kampagne oder ein anderes Element existiert in Ihrem Konto nicht
  • 409 – das Element hat nicht den passenden Status (zum Beispiel können nur Entwürfe freigegeben werden)
  • 422 – fehlende/ungültige Parameter
  • 429 – KI-Credit-Limit oder monatliches KI-Kontingent erreicht; wird zu Ihrem nächsten Abrechnungsdatum zurückgesetzt

Lastspitzen werden pro Schlüssel gedrosselt – implementieren Sie bei 429 ein exponentielles Backoff. Fragen? Kontaktieren Sie uns oder eröffnen Sie ein Support-Ticket.