API για developers

Ένα REST API για λίστες, καμπάνιες, email συναλλαγών — και την AI.

Πρώτα βήματα

Κάθε επί πληρωμή πακέτο περιλαμβάνει πλήρη πρόσβαση στο REST API. Δημιουργήστε ένα κλειδί στον λογαριασμό σας, στην ενότητα Λογαριασμός → Κλειδιά API, και στείλτε το με κάθε αίτημα:

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

Βασικό URL: https://mailflow.top/api/index.php · Οι απαντήσεις είναι σε JSON με πεδίο status με τιμή success ή error. Το API δεν είναι διαθέσιμο στο δωρεάν πακέτο.

Βασικοί πόροι

Η πλατφόρμα είναι συμβατή με το MailWizz, οπότε ολόκληρο το βασικό API — λίστες, συνδρομητές, τμήματα, προσαρμοσμένα πεδία, καμπάνιες, παρακολούθηση, πρότυπα, email συναλλαγών, επιστροφές, απεγγραφές — τεκμηριώνεται διαδραστικά (OpenAPI), μαζί με όλα τα endpoints του MailFlow που περιγράφονται σε αυτή τη σελίδα, στη διεύθυνση:

→ Διαδραστική τεκμηρίωση αναφοράς API (OpenAPI)

Τα υπάρχοντα SDK του MailWizz (π.χ. το επίσημο PHP SDK) λειτουργούν αμέσως — απλώς ορίστε σε αυτά το παραπάνω βασικό URL.

Endpoints AI

Οι λειτουργίες AI είναι πλήρως ενσωματωμένες στο API. Ίδιο κλειδί, ίδιος έλεγχος ταυτότητας, ίδια όρια πακέτου και ίδια μέτρηση μονάδων με την εφαρμογή web.

GET /ai/credits

Ο μετρητής μονάδων AI για τον τρέχοντα μήνα. Οι μονάδες ισχύουν ανά μήνα χρέωσης και οι αχρησιμοποίητες δεν μεταφέρονται.

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

GET /ai/replies

Ταξινομήσεις Smart Replies για τις καμπάνιες σας — τροφοδοτήστε το CRM σας με το ποιος ενδιαφέρεται, ποιος έκανε ερώτηση, ποιος παραπονέθηκε. Φίλτρα: category (interested, question, complaint, unsubscribe_request, auto_reply, out_of_office, bounce, other), campaign_uid, since (YYYY-MM-DD), page, per_page (έως 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 (vip, engaged, passive, at_risk, dormant) ανά λίστα — η ίδια βαθμολόγηση που τροφοδοτεί τον αυτόματο πιλότο και την επαναφορά.

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

POST /ai/subject-lines

Δημιουργήστε θέματα σε οποιαδήποτε γλώσσα. Σώμα: topic (υποχρεωτικό), count (1–5, προεπιλογή 3), language (προαιρετικό). Καταναλώνει μονάδες AI όπως ο επεξεργαστής 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

Δημιουργία ροών με AI μέσω του API: εμφανίστε τις ροές σας με μετρητές σε πραγματικό χρόνο· αναθέστε στην AI να συντάξει μια ολοκληρωμένη ροή από έναν στόχο διατυπωμένο σε απλή γλώσσα ({"goal":"...","list_uid":"..."} — επιστρέφει ένα προσχέδιο που ενεργοποιείτε με {"status":"active"})· προσθέστε έναν συνδρομητή σε μια ροή ({"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

Φτιάξτε τη δική σας εφαρμογή πάνω στο MailFlow

Ό,τι κάνετε στην εφαρμογή web μπορεί να γίνει και μέσω του API, ώστε να διαχειρίζεστε το MailFlow από το δικό σας λογισμικό. Μια τυπική ροή:

  1. Δημιουργήστε μια λίστα και προσθέστε επαφές: POST /lists, POST /lists/<list_uid>/subscribers/bulk.
  2. Βρείτε νέες επαφές με το DataStack: POST /datastack/import.
  3. Δημιουργήστε μια καμπάνια μόνοι σας (POST /campaigns) ή αφήστε την AI να τη γράψει: POST /ai/campaigns.
  4. Ελέγξτε και προγραμματίστε το προσχέδιο της AI: GET /ai/campaigns/<run_id>, POST /ai/campaigns/<run_id>/approve.
  5. Δείτε τα αποτελέσματα: GET /analytics/campaigns, GET /campaigns/<campaign_uid>/clicks.

Οι χρονοβόρες εργασίες (σύνταξη από την AI, ανάγνωση ιστοτόπων, εισαγωγές DataStack) εκτελούνται στο παρασκήνιο: η κλήση απαντά 202 με ένα job_id, και το GET /ai/jobs/<job_id> σάς ενημερώνει πότε ολοκληρώθηκε.

Αναλυτικά στοιχεία

Τα ίδια νούμερα με τον πίνακα ελέγχου και τις αναφορές καμπανιών σας. Οι ημερομηνίες είναι σε UTC· τα from και to (YYYY-MM-DD) καλύπτουν από προεπιλογή τις τελευταίες 30 ημέρες. Τα σύνολα του λογαριασμού ανανεώνονται κάθε λίγα λεπτά.

  • GET /analytics/overview — λίστες, συνδρομητές, καμπάνιες και αποτελέσματα αποστολών για μια περίοδο: αποστολές, παραδόσεις, ανοίγματα, κλικ, επιστροφές, παράπονα, απεγγραφές και τα αντίστοιχα ποσοστά.
  • GET /analytics/timeline — τα ίδια αποτελέσματα ανά ημέρα (ή ανά ώρα με interval=hour), καθώς και οι νέοι συνδρομητές.
  • GET /analytics/campaigns — μία γραμμή ανά καμπάνια με τα αποτελέσματά της· φιλτράρισμα με status.
  • GET /campaigns/<campaign_uid>/opens και /clicks — ποιος άνοιξε ή έκανε κλικ, πότε, από πού και από ποια συσκευή (unique=1 μόνο για τα πρώτα συμβάντα).
  • GET /campaigns/<campaign_uid>/links, /locations, /devices, /timeline, /abuse-reports — κλικ ανά σύνδεσμο, αποτελέσματα ανά χώρα και πόλη, ανά τύπο συσκευής και ανά ώρα, καθώς και αναφορές κατάχρησης.
  • GET /campaigns/<campaign_uid>/stats, /bounces, /unsubscribes, /complaints, /delivery-logs — οι βασικές αναφορές καμπάνιας.
  • GET /lists/<list_uid>/stats — συνδρομητές ανά κατάσταση και πηγή, ημερήσια αύξηση και οι καμπάνιες που στάλθηκαν στη λίστα.
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}}}

Λογαριασμός και ρυθμίσεις αποστολής

  • GET /account · PUT /account — το προφίλ σας, το πακέτο, το όριο αποστολών και οι περιορισμοί του λογαριασμού· αλλάξτε το όνομα, το τηλέφωνο ή τη ζώνη ώρας σας.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> — ομάδες καμπανιών.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails — λίστες αποκλεισμού (έως 10.000 email ανά κλήση).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= — η μαύρη λίστα σας και αν μια διεύθυνση είναι αποκλεισμένη οπουδήποτε.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify — domains αποστολής με τις εγγραφές DKIM, SPF και DMARC που πρέπει να δημοσιεύσετε.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify — τα δικά σας domain παρακολούθησης συνδέσμων.
  • GET /delivery-servers · GET /countries — οι διακομιστές μέσω των οποίων μπορείτε να στέλνετε και οι χώρες με τις ζώνες τους.

Καμπάνιες AI

Αφήστε την AI να γράφει καμπάνιες για εσάς, με ή χωρίς τον δικό σας έλεγχο. Η AI χρησιμοποιεί το προφίλ της επιχείρησής σας, επιλέγει το κοινό και την ώρα αποστολής, ελέγχει το email απέναντι στα φίλτρα spam και το γράφει στη γλώσσα κάθε συνδρομητή.

  • POST /ai/campaigns — πείτε στην AI τι να στείλει: goal (υποχρεωτικό), list_uid (μια λίστα, auto ή prospects), audience, business, template_uid, follow_up, auto_send.
  • POST /ai/campaigns/prepare — η AI αποφασίζει τι θα σταλεί στη συνέχεια (έως 3 την ημέρα)· προαιρετικά hint.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — καμπάνιες AI με θέματα, κοινό, προτεινόμενη ώρα και έλεγχο spam (το html=1 προσθέτει και το email).
  • POST /ai/campaigns/<run_id>/approve — προγραμματίστε την καμπάνια: when = proposed, now ή custom με send_at· προαιρετικά max_send.
  • POST /ai/campaigns/<run_id>/revise (με feedback) · POST /ai/campaigns/<run_id>/discard — ζητήστε αλλαγές ή απορρίψτε το προσχέδιο.
  • GET /ai/jobs/<job_id> — η κατάσταση μιας εργασίας στο παρασκήνιο και οι καμπάνιες AI που δημιούργησε.
  • GET|PUT /ai/hands-off — πλήρως αυτόματη λειτουργία: η AI σχεδιάζει, γράφει και στέλνει χωρίς να περιμένει εσάς ({"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}}

Προφίλ επιχειρήσεων

Η AI γράφει εκ μέρους της επιχείρησής σας. Διατηρήστε ένα προφίλ για κάθε ιστότοπο:

  • GET|POST /ai/businesses — οι επιχειρήσεις σας· προσθέστε μία με το website.
  • GET|PUT|DELETE /ai/businesses/<domain> — προφίλ, αποστολέας (from_name, from_email, reply_to) και στοιχεία εταιρείας (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main — αφήστε την AI να διαβάσει τον ιστότοπο και να συμπληρώσει το προφίλ· ορίστε την επιχείρηση ως κύρια.

Υποψήφιοι πελάτες από το DataStack

Βρείτε νέες επαγγελματικές και προσωπικές διευθύνσεις email και εισαγάγετέ τες απευθείας στις λίστες σας. Οι εισαγωγές μετρώνται στο όριο του πακέτου σας· οι μετρήσεις διαθεσιμότητας είναι δωρεάν.

  • GET /datastack/credits — πόσες διευθύνσεις σάς επιτρέπει ακόμη να εισαγάγετε το πακέτο σας αυτόν τον μήνα.
  • GET /datastack/count — πόσες διευθύνσεις υπάρχουν για country, niche (επαγγελματικές κατηγορίες), keyword και role (προσωπικές). Δωρεάν.
  • POST /datastack/import — εισαγωγή διευθύνσεων business ή/και personal στο list_uid (εργασία στο παρασκήνιο). Οι νέες διευθύνσεις ελέγχονται πριν τους στείλει οποιαδήποτε καμπάνια.
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"}}

Αιτήματα υποστήριξης

  • GET|POST /support-tickets — τα αιτήματά σας· ανοίξτε νέο αίτημα με subject, message, category και priority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close — διαβάστε τη συνομιλία, απαντήστε, κλείστε το αίτημα.

Δικαιώματα κλειδιών API

Ένα κλειδί μπορεί να περιοριστεί σε συγκεκριμένα endpoints. Στην ενότητα Λογαριασμός → Κλειδιά API, επεξεργαστείτε το κλειδί, ενεργοποιήστε τα δικαιώματα και επιλέξτε τι επιτρέπεται να χρησιμοποιεί. Τα endpoints αυτής της σελίδας εμφανίζονται με το πρόθεμα MailFlow.

Σφάλματα και όρια

  • 400 — λείπει ή δεν είναι έγκυρο το X-Api-Key, ή το κλειδί δεν έχει δικαίωμα για αυτό το endpoint
  • 402 — δεν επαρκούν οι μονάδες DataStack αυτόν τον μήνα
  • 403 — η λειτουργία δεν περιλαμβάνεται στο πακέτο σας ή έχει εξαντληθεί κάποιο όριο του πακέτου
  • 404 — η λίστα, η καμπάνια ή το άλλο στοιχείο δεν υπάρχει στον λογαριασμό σας
  • 409 — το στοιχείο δεν βρίσκεται στη σωστή κατάσταση (για παράδειγμα, μόνο τα προσχέδια μπορούν να εγκριθούν)
  • 422 — ελλιπείς/μη έγκυρες παράμετροι
  • 429 — εξαντλήθηκε το όριο μονάδων AI ή το μηνιαίο περιθώριο AI· ανανεώνεται στην επόμενη ημερομηνία χρέωσης

Οι ριπές αιτημάτων περιορίζονται ανά κλειδί — εφαρμόστε εκθετική αναμονή (exponential backoff) στο 429. Ερωτήσεις; Επικοινωνήστε μαζί μας ή ανοίξτε αίτημα υποστήριξης.