API développeur

Une seule API REST pour les listes, les campagnes, les e-mails transactionnels — et l'IA.

Premiers pas

Chaque forfait payant inclut un accès complet à l'API REST. Générez une clé dans votre compte sous Compte → Clés API, puis envoyez-la avec chaque requête :

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

URL de base : https://mailflow.top/api/index.php · Les réponses sont au format JSON, avec un champ status valant success ou error. L'API n'est pas disponible avec le forfait gratuit.

Ressources principales

La plateforme est compatible MailWizz : l'ensemble de l'API principale — listes, abonnés, segments, champs personnalisés, campagnes, suivi, modèles, e-mails transactionnels, rebonds, désabonnements — est documenté de manière interactive (OpenAPI), avec tous les endpoints MailFlow de cette page, à l'adresse :

→ Référence interactive de l'API (OpenAPI)

Les SDK MailWizz existants (par ex. le SDK PHP officiel) fonctionnent immédiatement — il suffit de les pointer vers l'URL de base ci-dessus.

Endpoints IA

Les fonctionnalités IA sont pleinement intégrées à l'API : même clé, même authentification, mêmes limites de forfait et même décompte des crédits que dans l'application web.

GET /ai/credits

Votre compteur de crédits IA pour le mois en cours. Les crédits sont alloués par mois de facturation et les crédits non utilisés ne sont pas reportés.

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

GET /ai/replies

Classifications Smart Replies pour vos campagnes — alimentez votre CRM : qui est intéressé, qui a posé une question, qui s'est plaint. Filtres : category (interested, question, complaint, unsubscribe_request, auto_reply, out_of_office, bounce, other), campaign_uid, since (YYYY-MM-DD), page, per_page (50 max).

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

Niveaux d'engagement IA (vip, engaged, passive, at_risk, dormant) par liste — le même scoring qui alimente le pilote automatique et la reconquête.

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

POST /ai/subject-lines

Générez des objets d'e-mail dans n'importe quelle langue. Corps : topic (obligatoire), count (1–5, 3 par défaut), language (facultatif). Consomme des crédits IA comme l'éditeur web.

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

Le créateur de workflows IA via l'API : listez vos workflows avec leurs compteurs en direct ; laissez l'IA créer un workflow complet à partir d'un objectif formulé en langage courant ({"goal":"...","list_uid":"..."} — renvoie un brouillon que vous activez avec {"status":"active"}) ; ajoutez un abonné à un workflow ({"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

Créez votre propre application sur MailFlow

Tout ce que vous faites dans l'application web peut se faire via l'API : vous pouvez ainsi piloter MailFlow depuis votre propre logiciel. Un parcours type :

  1. Créez une liste et ajoutez des contacts : POST /lists, POST /lists/<list_uid>/subscribers/bulk.
  2. Trouvez de nouveaux contacts avec DataStack : POST /datastack/import.
  3. Créez une campagne vous-même (POST /campaigns) ou laissez l'IA la rédiger : POST /ai/campaigns.
  4. Vérifiez et programmez le brouillon de l'IA : GET /ai/campaigns/<run_id>, POST /ai/campaigns/<run_id>/approve.
  5. Consultez les résultats : GET /analytics/campaigns, GET /campaigns/<campaign_uid>/clicks.

Les tâches longues (rédaction par l'IA, lecture de site web, importations DataStack) s'exécutent en arrière-plan : l'appel répond 202 avec un job_id, et GET /ai/jobs/<job_id> vous indique quand la tâche est terminée.

Statistiques

Les mêmes chiffres que dans votre tableau de bord et vos rapports de campagne. Les dates sont en UTC ; par défaut, from et to (YYYY-MM-DD) couvrent les 30 derniers jours. Les totaux du compte sont actualisés à quelques minutes d'intervalle.

  • GET /analytics/overview — listes, abonnés, campagnes et résultats d'envoi sur une période : envoyés, délivrés, ouvertures, clics, rebonds, plaintes, désabonnements et leurs taux.
  • GET /analytics/timeline — les mêmes résultats par jour (ou par heure avec interval=hour), plus les nouveaux abonnés.
  • GET /analytics/campaigns — une ligne par campagne avec ses résultats ; filtrez avec status.
  • GET /campaigns/<campaign_uid>/opens et /clicks — qui a ouvert ou cliqué, quand, d'où et sur quel appareil (unique=1 pour les premiers événements uniquement).
  • GET /campaigns/<campaign_uid>/links, /locations, /devices, /timeline, /abuse-reports — clics par lien, résultats par pays et par ville, par type d'appareil, par heure, et signalements d'abus.
  • GET /campaigns/<campaign_uid>/stats, /bounces, /unsubscribes, /complaints, /delivery-logs — les rapports de campagne de base.
  • GET /lists/<list_uid>/stats — abonnés par statut et par source, croissance quotidienne et campagnes envoyées à la liste.
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}}}

Compte et configuration de l'envoi

  • GET /account · PUT /account — votre profil, votre forfait, votre quota d'envoi et vos limites ; modifiez votre nom, votre téléphone ou votre fuseau horaire.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> — groupes de campagnes.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails — listes de suppression (jusqu'à 10 000 e-mails par appel).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= — votre liste noire, et si une adresse est bloquée quelque part.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify — domaines d'envoi avec les enregistrements DKIM, SPF et DMARC à publier.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify — vos propres domaines de suivi des liens.
  • GET /delivery-servers · GET /countries — les serveurs par lesquels vous pouvez envoyer, et les pays avec leurs zones.

Campagnes IA

Laissez l'IA rédiger vos campagnes, avec ou sans votre validation. L'IA utilise votre profil d'entreprise, choisit l'audience et l'heure d'envoi, vérifie l'e-mail face aux filtres anti-spam et le rédige dans la langue de chaque abonné.

  • POST /ai/campaigns — indiquez à l'IA quoi envoyer : goal (obligatoire), list_uid (une liste, auto ou prospects), audience, business, template_uid, follow_up, auto_send.
  • POST /ai/campaigns/prepare — l'IA décide quoi envoyer ensuite (jusqu'à 3 par jour) ; hint facultatif.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — campagnes IA avec objets, audience, heure proposée et contrôle anti-spam (html=1 ajoute l'e-mail).
  • POST /ai/campaigns/<run_id>/approve — programmez l'envoi : when = proposed, now ou custom avec send_at ; max_send facultatif.
  • POST /ai/campaigns/<run_id>/revise (avec feedback) · POST /ai/campaigns/<run_id>/discard — demandez des modifications ou abandonnez le brouillon.
  • GET /ai/jobs/<job_id> — état d'une tâche en arrière-plan et campagnes IA qu'elle a créées.
  • GET|PUT /ai/hands-off — mode autonome : l'IA planifie, rédige et envoie sans attendre votre intervention ({"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}}

Profils d'entreprise

L'IA écrit au nom de votre entreprise. Gardez un profil par site web :

  • GET|POST /ai/businesses — vos entreprises ; ajoutez-en une avec website.
  • GET|PUT|DELETE /ai/businesses/<domain> — profil, expéditeur (from_name, from_email, reply_to) et coordonnées de l'entreprise (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main — laissez l'IA lire le site web et remplir le profil ; faites-en votre entreprise principale.

Prospects DataStack

Trouvez de nouvelles adresses e-mail professionnelles et personnelles, et importez-les directement dans vos listes. Les importations sont décomptées de votre forfait ; le comptage des adresses est gratuit.

  • GET /datastack/credits — le nombre d'adresses que votre forfait vous permet encore d'importer ce mois-ci.
  • GET /datastack/count — nombre d'adresses disponibles pour country, niche (catégories d'activité), keyword et role (personnelles). Gratuit.
  • POST /datastack/import — importe des adresses business et/ou personal dans list_uid (tâche en arrière-plan). Les nouvelles adresses sont vérifiées avant qu'une campagne ne leur soit envoyée.
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"}}

Tickets d'assistance

  • GET|POST /support-tickets — vos tickets ; ouvrez-en un avec subject, message, category et priority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close — lire la conversation, répondre, clôturer.

Autorisations des clés API

Une clé peut être limitée à certains endpoints. Sous Compte → Clés API, modifiez la clé, activez les autorisations et cochez ce qu'elle peut utiliser. Les endpoints de cette page sont listés avec le préfixe MailFlow.

Erreurs et limites

  • 400 — X-Api-Key manquant ou invalide, ou la clé n'a pas l'autorisation d'utiliser cet endpoint
  • 402 — crédits DataStack insuffisants ce mois-ci
  • 403 — la fonctionnalité n'est pas incluse dans votre forfait, ou une limite du forfait est atteinte
  • 404 — la liste, la campagne ou tout autre élément n'existe pas dans votre compte
  • 409 — l'élément n'est pas dans le bon état (par exemple, seuls les brouillons peuvent être approuvés)
  • 422 — paramètres manquants/invalides
  • 429 — limite de crédits IA ou quota IA mensuel atteint ; réinitialisation à votre prochaine date de facturation

Les rafales de requêtes sont limitées par clé — implémentez un backoff exponentiel en cas de 429. Des questions ? Contactez-nous ou ouvrez un ticket d'assistance.