Documentazione API per sviluppatori

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) 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

Errori e limiti

401 — X-Api-Key mancante o non valido
403 — la funzionalità non è inclusa nel tuo piano
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.

API per sviluppatori