Transactional webhooks

Τα webhooks επιτρέπουν στην εφαρμογή σας να λαμβάνει ειδοποιήσεις σε πραγματικό χρόνο όταν κάτι συμβαίνει σε transactional email μετά την αποστολή του. Αντί να ζητάτε επαναλαμβανόμενα το API για έλεγχο κατάστασης παράδοσης, το Flexmail αποστέλλει αίτημα HTTP POST στο endpoint σας τη στιγμή που εμφανίζεται συμβάν.

Αυτό είναι ιδιαίτερα πολύτιμο για transactional email: μπορείτε να αναλάβετε άμεσα δράση όταν αναπηδά επαναφορά κωδικού πρόσβασης, όταν παραδοθεί επιβεβαίωση παραγγελίας ή όταν παραλήπτης αναφέρει μήνυμα ως spam.

Συμβάντα webhook

Το Flexmail αποστέλλει ειδοποίηση webhook για κάθε ένα από τα ακόλουθα συμβάντα:

• Απεστάλη — το μήνυμα έγινε αποδεκτό και παραδόθηκε στον διακομιστή email λήψης.
• Παραδόθηκε — ο διακομιστής email λήψης επιβεβαίωσε παράδοση στο mailbox του παραλήπτη.
• Αναπήδηση — η παράδοση απέτυχε. Τα hard bounces υποδηλώνουν μόνιμο πρόβλημα (η διεύθυνση δεν υπάρχει)· τα soft bounces υποδηλώνουν προσωρινό ζήτημα (mailbox γεμάτο, διακομιστής μη διαθέσιμος).
• Άνοιξε — ο παραλήπτης άνοιξε το μήνυμα.
• Έκανε κλικ — ο παραλήπτης έκανε κλικ σε παρακολουθούμενο σύνδεσμο στο μήνυμα.
• Παράπονο — ο παραλήπτης επισήμανε το μήνυμα ως spam.

Σημείωση

Η παρακολούθηση ανοίγματος και κλικ απαιτεί ενεργοποίηση pixel παρακολούθησης και αναδίπλωσης συνδέσμων. Τα συμβάντα παράδοσης εξαρτώνται από τον διακομιστή email λήψης που επιβεβαιώνει παράδοση — δεν το κάνουν όλοι οι διακομιστές.

Ρύθμιση endpoint webhook

Το endpoint webhook σας είναι URL στον διακομιστή σας που δέχεται αιτήματα HTTP POST και επιστρέφει response 200 για επιβεβαίωση λήψης.

Απαιτήσεις για το endpoint σας

• Δέχεται αιτήματα HTTP POST.
• Είναι δημόσια προσβάσιμο μέσω HTTPS.
• Επιστρέφει κωδικό κατάστασης HTTP 2xx εντός εύλογου χρονικού ορίου για επιβεβαίωση λήψης.
• Επεξεργάζεται το payload ασύγχρονα εάν η λογική διαχείρισής σας είναι αργή — ανταποκρίνεστε αμέσως και επεξεργάζεστε στο παρασκήνιο για αποφυγή timeouts.

Καταχώρηση endpoint στο Flexmail

Η διαμόρφωση endpoint webhook γίνεται μέσω του API. Η πλήρης διαδικασία καταχώρησης και οι διαθέσιμες επιλογές τεκμηριώνονται στην τεκμηρίωση API στο email-api.flexmail.eu/documentation, στην ενότητα Webhooks.

Payload webhook

Κάθε ειδοποίηση webhook είναι αίτημα HTTP POST με σώμα JSON. Το payload περιέχει τον τύπο συμβάντος, χρονική σφραγίδα, το message ID και τη διεύθυνση email παραλήπτη. Ανάλογα με το συμβάν, περιλαμβάνονται επιπλέον πεδία — για παράδειγμα, ένα συμβάν αναπήδησης περιλαμβάνει τον τύπο και λόγο αναπήδησης, και ένα συμβάν κλικ περιλαμβάνει τη URL που επισκέφτηκαν.

Ένα τυπικό payload μοιάζει ως εξής:

{ "event": "delivered", "timestamp": "2024-11-15T09:32:00Z", "messageId": "abc123", "recipient": "customer@example.com" }

Η πλήρης προδιαγραφή payload για κάθε τύπο συμβάντος βρίσκεται στην τεκμηρίωση API.

Τι να κάνετε με τα συμβάντα webhook

Αναπηδήσεις

Όταν λαμβάνετε συμβάν hard bounce, σημαιοδοτήστε αυτή τη διεύθυνση email στο σύστημά σας. Σταματήστε να της αποστέλλετε και ελέγξτε εάν η διεύθυνση εισήχθη σωστά. Η συνέχιση αποστολής σε διευθύνσεις hard bounce βλάπτει τη φήμη αποστολέα σας.

Παράπονα spam

Όταν ένας παραλήπτης επισημάνει transactional email ως spam, αποκλείστε αμέσως αυτή τη διεύθυνση. Ακόμα και εάν το email ήταν πράγματι transactional (επιβεβαίωση παραγγελίας, για παράδειγμα), ο παραλήπτης έχει σηματοδοτήσει ότι δεν θέλει να λαμβάνει email από εσάς. Η συνέχιση αποστολής είναι και βλαβερή για τη φήμη σας και ενδεχομένως νομικό ζήτημα.

Επιβεβαιώσεις παράδοσης

Για μηνύματα χρονικά κρίσιμα όπως επαναφορές κωδικού πρόσβασης ή κωδικούς δύο παραγόντων, μπορείτε να χρησιμοποιήσετε το συμβάν παράδοσης για επιβεβαίωση ότι το email έφτασε στο inbox. Εάν δεν φτάσει επιβεβαίωση παράδοσης εντός εύλογου χρονικού παραθύρου, μπορείτε να εμφανίσετε μήνυμα στο UI σας που προτείνει στον χρήστη να ελέγξει τον φάκελο spam ή να δοκιμάσει ξανά.

Συμβουλή

Επιβεβαιώνετε τα αιτήματα webhook αμέσως με response 200, στη συνέχεια επεξεργαστείτε το payload σε εργασία παρασκηνίου ή ουρά. Εάν ο χειριστής σας αργεί να ανταποκριθεί, το Flexmail μπορεί να λήξει και να επαναλάβει το αίτημα, κάτι που μπορεί να οδηγήσει σε διπλή επεξεργασία.

Επαναλήψεις

Εάν το endpoint σας δεν επιστρέψει επιτυχές response, το Flexmail επαναλαμβάνει την ειδοποίηση webhook. Κάντε την επεξεργασία συμβάντων σας idempotent — η επεξεργασία του ίδιου συμβάντος δύο φορές πρέπει να παράγει το ίδιο αποτέλεσμα με την επεξεργασία του μία φορά. Χρησιμοποιήστε το message ID και τον τύπο συμβάντος μαζί για αποεπανάληψη.

Επόμενα βήματα

• Δείτε "Ξεκινώντας με το transactional API" για ρύθμιση λογαριασμού.
• Ανατρέξτε στην ενότητα Webhooks στην τεκμηρίωση API στο email-api.flexmail.eu/documentation για την πλήρη προδιαγραφή payload και οδηγίες καταχώρησης.
• Δείτε "Αντιμετώπιση προβλημάτων transactional" εάν τα webhooks δεν φτάνουν ή η παραδοσιμότητά σας είναι κάτω από τις προσδοκίες.