Webhook transazionali

I webhook consentono all'applicazione di ricevere notifiche in tempo reale quando accade qualcosa a un'email transazionale dopo l'invio. Invece di interrogare l'API per verificare lo stato di consegna, Flexmail invia una richiesta HTTP POST all'endpoint nel momento in cui si verifica un evento.

Questo è particolarmente prezioso per l'email transazionale: è possibile agire immediatamente quando un reset della password rimbalza, quando una conferma d'ordine viene consegnata o quando un destinatario segnala un messaggio come spam.

Eventi webhook

Flexmail invia una notifica webhook per ciascuno dei seguenti eventi:

• Inviato — il messaggio è stato accettato e consegnato al server di posta del destinatario.
• Consegnato — il server di posta del destinatario ha confermato la consegna nella casella di posta del destinatario.
• Rimbalzato — la consegna non è riuscita. Gli hard bounce indicano un problema permanente (l'indirizzo non esiste); i soft bounce indicano un problema temporaneo (casella piena, server non disponibile).
• Aperto — il destinatario ha aperto il messaggio.
• Cliccato — il destinatario ha cliccato su un link tracciato nel messaggio.
• Segnalato — il destinatario ha contrassegnato il messaggio come spam.

Nota

Il tracciamento delle aperture e dei clic richiede che i pixel di tracciamento e il wrapping dei link siano abilitati. Gli eventi di consegna dipendono dalla conferma da parte del server di posta del destinatario — non tutti i server lo fanno.

Configurare un endpoint webhook

L'endpoint webhook è un URL sul server che accetta richieste HTTP POST e restituisce una risposta 200 per confermare la ricezione.

Requisiti per l'endpoint

• Accetta richieste HTTP POST.
• È accessibile pubblicamente tramite HTTPS.
• Restituisce un codice di stato HTTP 2xx entro un timeout ragionevole per confermare la ricezione.
• Elabora il payload in modo asincrono se la logica di gestione è lenta — rispondere immediatamente ed elaborare in background per evitare timeout.

Registrare l'endpoint in Flexmail

La configurazione dell'endpoint webhook viene eseguita tramite l'API. Il processo di registrazione completo e le opzioni disponibili sono documentati nella documentazione API su email-api.flexmail.eu/documentation, nella sezione Webhook.

Payload del webhook

Ogni notifica webhook è una richiesta HTTP POST con un corpo JSON. Il payload contiene il tipo di evento, un timestamp, l'ID messaggio e l'indirizzo email del destinatario. A seconda dell'evento, vengono inclusi campi aggiuntivi — ad esempio, un evento di bounce include il tipo di bounce e il motivo, e un evento di clic include l'URL su cui si è cliccato.

Un payload tipico si presenta così:

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

La specifica completa del payload per ogni tipo di evento è nella documentazione API.

Cosa fare con gli eventi webhook

Bounce

Quando si riceve un evento di hard bounce, contrassegnare quell'indirizzo email nel sistema. Smettere di inviare e verificare se l'indirizzo è stato inserito correttamente. Continuare a inviare a indirizzi con hard bounce danneggia la reputazione del mittente.

Segnalazioni spam

Quando un destinatario segna un'email transazionale come spam, sopprimere immediatamente quell'indirizzo. Anche se l'email era genuinamente transazionale (una conferma d'ordine, ad esempio), il destinatario ha segnalato che non vuole ricevere email dal mittente. Continuare a inviare è sia dannoso per la reputazione che potenzialmente un problema legale.

Conferme di consegna

Per i messaggi sensibili al tempo come i reset della password o i codici di autenticazione a due fattori, è possibile usare l'evento di consegna per confermare che l'email ha raggiunto la casella di posta. Se non arriva nessuna conferma di consegna entro un intervallo di tempo ragionevole, è possibile mostrare nell'interfaccia un messaggio che suggerisce all'utente di controllare la cartella spam o di riprovare.

Consiglio

Rispondere alle richieste webhook immediatamente con una risposta 200, poi elaborare il payload in un job o coda in background. Se il gestore impiega troppo tempo a rispondere, Flexmail potrebbe andare in timeout e riprovare la richiesta, il che può portare a elaborazioni duplicate.

Tentativi

Se l'endpoint non restituisce una risposta positiva, Flexmail ritenta la notifica webhook. Rendere la gestione degli eventi idempotente — elaborare lo stesso evento due volte dovrebbe produrre lo stesso risultato che elaborarlo una volta. Usare l'ID messaggio e il tipo di evento insieme per deduplicare.

Passi successivi

• Si consulti "Iniziare con l'API transazionale" per la configurazione dell'account.
• Rivedere la sezione Webhook nella documentazione API su email-api.flexmail.eu/documentation per la specifica completa del payload e le istruzioni di registrazione.
• Si consulti "Risoluzione dei problemi transazionali" se i webhook non arrivano o la recapitabilità è inferiore alle aspettative.