API per sviluppatori

Un'unica API REST per liste, campagne, email transazionali e IA.

Per iniziare

Ogni piano a pagamento include l'accesso completo all'API REST. Genera una chiave nel tuo account in Account → Chiavi API, poi inviala con ogni richiesta:

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

URL di base: https://mailflow.top/api/index.php · Le risposte sono in JSON con un campo status pari a success o error. L'API non è disponibile con il piano gratuito.

Risorse principali

La piattaforma è compatibile con MailWizz, quindi l'intera API di base (liste, iscritti, segmenti, campi personalizzati, campagne, tracciamento, template, email transazionali, bounce, disiscrizioni) è documentata in modo interattivo (OpenAPI), insieme a tutti gli endpoint MailFlow di questa pagina, all'indirizzo:

→ Riferimento API interattivo (OpenAPI)

Gli SDK MailWizz esistenti (ad es. l'SDK PHP ufficiale) funzionano subito: basta puntarli all'URL di base indicato sopra.

Endpoint IA

Le funzionalità IA sono pienamente integrate nell'API: stessa chiave, stessa autenticazione, stessi limiti del piano e stesso conteggio dei crediti dell'app web.

GET /ai/credits

Il contatore dei tuoi crediti IA per il mese in corso. I crediti valgono per mese di fatturazione e quelli non utilizzati non vengono riportati.

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

GET /ai/replies

Classificazioni Smart Replies per le tue campagne: alimenta il tuo CRM con chi è interessato, chi ha fatto una domanda, chi ha presentato un reclamo. Filtri: 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

Livelli di coinvolgimento IA (vip, engaged, passive, at_risk, dormant) per lista: lo stesso punteggio che alimenta il pilota automatico e la riconquista.

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

POST /ai/subject-lines

Genera oggetti in qualsiasi lingua. Corpo: topic (obbligatorio), count (1–5, predefinito 3), language (facoltativo). Consuma crediti IA come l'editor 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

Il Generatore di flussi con IA via API: elenca i tuoi flussi con i contatori in tempo reale; fai creare all'IA un flusso completo a partire da un obiettivo espresso in linguaggio naturale ({"goal":"...","list_uid":"..."}, che restituisce una bozza da attivare con {"status":"active"}); inserisci un iscritto in un flusso ({"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

Crea la tua app su MailFlow

Tutto ciò che fai nell'app web si può fare tramite API, così puoi gestire MailFlow dal tuo software. Un flusso tipico:

  1. Crea una lista e aggiungi contatti: POST /lists, POST /lists/<list_uid>/subscribers/bulk.
  2. Trova nuovi contatti con DataStack: POST /datastack/import.
  3. Crea tu una campagna (POST /campaigns) oppure lascia che la scriva l'IA: POST /ai/campaigns.
  4. Rivedi e programma la bozza dell'IA: GET /ai/campaigns/<run_id>, POST /ai/campaigns/<run_id>/approve.
  5. Leggi i risultati: GET /analytics/campaigns, GET /campaigns/<campaign_uid>/clicks.

Le operazioni lunghe (scrittura con IA, lettura del sito web, importazioni DataStack) vengono eseguite in background: la chiamata risponde 202 con un job_id e GET /ai/jobs/<job_id> ti dice quando l'operazione è completata.

Statistiche

Gli stessi numeri della dashboard e dei report delle campagne. Le date sono in UTC; from e to (YYYY-MM-DD) coprono per impostazione predefinita gli ultimi 30 giorni. I totali dell'account vengono aggiornati ogni pochi minuti.

  • GET /analytics/overview — liste, iscritti, campagne e risultati di invio in un periodo: invii, consegne, aperture, clic, bounce, segnalazioni, disiscrizioni e relativi tassi.
  • GET /analytics/timeline — gli stessi risultati per giorno (o per ora con interval=hour), più i nuovi iscritti.
  • GET /analytics/campaigns — una riga per campagna con i relativi risultati; filtra con status.
  • GET /campaigns/<campaign_uid>/opens e /clicks — chi ha aperto o cliccato, quando, da dove e con quale dispositivo (unique=1 solo per i primi eventi).
  • GET /campaigns/<campaign_uid>/links, /locations, /devices, /timeline, /abuse-reports — clic per link, risultati per paese e città, per tipo di dispositivo e per ora, e segnalazioni di abuso.
  • GET /campaigns/<campaign_uid>/stats, /bounces, /unsubscribes, /complaints, /delivery-logs — i report di base delle campagne.
  • GET /lists/<list_uid>/stats — iscritti per stato e origine, crescita giornaliera e campagne inviate alla lista.
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 e configurazione dell'invio

  • GET /account · PUT /account — il tuo profilo, piano, quota di invio e limiti; aggiorna nome, telefono o fuso orario.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> — gruppi di campagne.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails — liste di soppressione (fino a 10.000 email per chiamata).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= — la tua blacklist e se un indirizzo è bloccato da qualche parte.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify — domini di invio con i record DKIM, SPF e DMARC da pubblicare.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify — i tuoi domini di tracciamento dei link.
  • GET /delivery-servers · GET /countries — i server tramite cui puoi inviare e i paesi con le rispettive zone.

Campagne IA

Lascia che l'IA scriva le campagne per te, con o senza la tua revisione. L'IA usa il tuo profilo aziendale, sceglie il pubblico e l'orario di invio, verifica l'email con i filtri antispam e la scrive nella lingua di ogni iscritto.

  • POST /ai/campaigns — di' all'IA cosa inviare: goal (obbligatorio), list_uid (una lista, auto o prospects), audience, business, template_uid, follow_up, auto_send.
  • POST /ai/campaigns/prepare — l'IA decide cosa inviare dopo (fino a 3 al giorno); hint facoltativo.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — campagne IA con oggetti, pubblico, orario proposto e controllo antispam (html=1 aggiunge l'email).
  • POST /ai/campaigns/<run_id>/approve — programmala: when = proposed, now o custom con send_at; max_send facoltativo.
  • POST /ai/campaigns/<run_id>/revise (con feedback) · POST /ai/campaigns/<run_id>/discard — chiedi modifiche o scarta la bozza.
  • GET /ai/jobs/<job_id> — stato di un'operazione in background e campagne IA che ha creato.
  • GET|PUT /ai/hands-off — modalità autonoma: l'IA pianifica, scrive e invia senza aspettarti ({"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}}

Profili aziendali

L'IA scrive a nome della tua attività. Tieni un profilo per ogni sito web:

  • GET|POST /ai/businesses — le tue attività; aggiungine una con website.
  • GET|PUT|DELETE /ai/businesses/<domain> — profilo, mittente (from_name, from_email, reply_to) e dati aziendali (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main — fai leggere il sito all'IA e compilare il profilo; imposta l'attività come principale.

Nuovi contatti DataStack

Trova indirizzi email aziendali e personali aggiornati e importali direttamente nelle tue liste. Le importazioni vengono scalate dal tuo piano; il conteggio degli indirizzi è gratuito.

  • GET /datastack/credits — quanti indirizzi il tuo piano ti consente ancora di importare questo mese.
  • GET /datastack/count — quanti indirizzi esistono per country, niche (categorie di attività), keyword e role (personali). Gratuito.
  • POST /datastack/import — importa indirizzi business e/o personal in list_uid (operazione in background). I nuovi indirizzi vengono verificati prima che una campagna li raggiunga.
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"}}

Ticket di assistenza

  • GET|POST /support-tickets — i tuoi ticket; aprine uno con subject, message, category e priority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close — leggi la conversazione, rispondi, chiudi.

Autorizzazioni delle chiavi API

Una chiave può essere limitata a determinati endpoint. In Account → Chiavi API, modifica la chiave, abilita le autorizzazioni e seleziona cosa può usare. Gli endpoint di questa pagina sono elencati con il prefisso MailFlow.

Errori e limiti

  • 400 — X-Api-Key mancante o non valido, oppure la chiave non ha l'autorizzazione per questo endpoint
  • 402 — crediti DataStack insufficienti per questo mese
  • 403 — la funzionalità non è inclusa nel tuo piano, oppure è stato raggiunto un limite del piano
  • 404 — la lista, la campagna o un altro elemento non esiste nel tuo account
  • 409 — l'elemento non è nello stato corretto (ad esempio, solo le bozze possono essere approvate)
  • 422 — parametri mancanti/non validi
  • 429 — raggiunto il limite di crediti IA o la quota IA mensile; si azzera alla prossima data di fatturazione

I picchi di richieste sono limitati per chiave: implementa un backoff esponenziale sui 429. Domande? Contattaci o apri un ticket di assistenza.