Dopo il checkout, la tua applicazione ha un ordine e un destinatario che ha bisogno di una ricevuta. Usa un API email per inviare il messaggio. Registra la risposta associandola all'ordine.
L'invio è solo il primo passo. La tua applicazione ha anche bisogno di un modo per riprovare una richiesta. Deve sapere cosa è successo al messaggio dopo l'invio.
Come diventa un'email un evento dell'applicazione?
La tua applicazione trasforma una transazione completata o una richiesta dell'account in un'operazione di invio. Il servizio email gestisce la consegna dopo l'invio.
Per una ricevuta, la sequenza è:
- La tua applicazione conferma che l'ordine è pronto per una ricevuta.
- Seleziona il destinatario e fornisce i dettagli dell'ordine come contenuto o valori del template.
- Invia la richiesta e salva l'ID del messaggio restituito associandolo all'ordine.
- Aggiorna il record di invio quando arrivano gli eventi di consegna.
Un API email può supportare sia messaggi transazionali che di marketing. Usare un API non rende transazionale un contenuto promozionale né rimuove gli obblighi CAN-SPAM.
Cosa significa una risposta di successo?
Una risposta di invio riuscito registra ciò che il servizio ha accettato. È separata dalla decisione successiva del mail server di destinazione.
Lo status 202 di HTTP significa che la richiesta è stata accettata per l'elaborazione. L'elaborazione non è terminata, quindi quella risposta non può stabilire la consegna.
La risposta esatta dipende dall'API. L'endpoint di invio di Bird, ad esempio, restituisce un messaggio in coda con un id. Conserva quell'ID insieme all'ordine o all'evento dell'account, in modo da poter associare i risultati successivi alla richiesta originale.
Se la validazione fallisce, Bird restituisce 422 con un errore che spiega perché la richiesta è stata rifiutata.
Come evitano i tentativi i messaggi duplicati?
Una chiave di idempotenza identifica un'unica operazione di invio logica attraverso i tentativi. Un API che la supporta può riconoscere una richiesta ripetuta invece di creare un altro invio.
Ad esempio, una ricevuta per l'ordine 8472 può usare la chiave receipt/order-8472. Riprova la stessa richiesta con quella chiave se la connessione cade prima di ricevere la risposta.
Una chiave nuova identifica un'operazione diversa. La tua applicazione deve quindi preservare la chiave originale attraverso i propri tentativi e riavvii.
L'idempotenza ha una finestra di conservazione definita dal provider. Una volta scaduta quella finestra, la stessa chiave può essere elaborata come una nuova richiesta.
Come riportano la consegna i webhook?
Un webhook invia un evento alla tua applicazione quando lo stato del messaggio cambia. Permette alla tua applicazione di aggiornare i propri record dopo la risposta iniziale dell'API.
Gli eventi email di Bird distinguono questi esiti:
| Evento | Cosa stabilisce |
|---|---|
email.delivered | Il mail server di destinazione ha accettato la responsabilità del messaggio |
email.deferred | Un errore di consegna temporaneo verrà ritentato |
email.bounced | Il server di destinazione ha rifiutato la consegna |
email.rejected | Il messaggio non ha raggiunto un tentativo di consegna |
L'accettazione da parte del server non stabilisce il posizionamento nella casella di posta né la lettura. Un server di destinazione può anche segnalare un bounce successivo dopo aver accettato il messaggio.
Il tuo handler del webhook deve verificare la firma del mittente e gestire le consegne duplicate. Il contratto webhook di Bird richiede la deduplicazione tramite webhook-id.
Cosa cambiano i template?
Un template salvato separa il contenuto riutilizzabile del messaggio dai valori forniti per ogni invio. La tua applicazione può fornire un numero d'ordine e il nome del cliente senza assemblare l'intero corpo dell'email.
Con i template di Bird, un invio indica un template pubblicato e ne fornisce i parametri. Il template fornisce l'oggetto e il corpo.
Un template non decide quando un ordine è completo o se un reset di password è autorizzato. Quelle decisioni restano nella tua applicazione.
In cosa si distingue dal relay SMTP o da una piattaforma di marketing?
Un API HTTP e un relay SMTP sono interfacce di invio diverse. Una piattaforma di marketing gestisce anche il lavoro sulle campagne, come la selezione del pubblico e la pianificazione di un invio.
| Interfaccia o prodotto | Cosa fornisce la tua applicazione |
|---|---|
| API email | Una richiesta HTTP strutturata contenente destinatari e contenuto o un template |
| Relay SMTP | Una conversazione SMTP che invia destinatari e un messaggio email formattato |
| Piattaforma di marketing | Contenuto della campagna, selezione del pubblico e istruzioni di invio |
SMTP definisce lo scambio per l'invio di un messaggio e dei suoi destinatari. Può trasportare email transazionali o di marketing.
Il relay SMTP di Bird e HTTP API usano lo stesso prodotto di consegna, inclusi eventi e gestione delle soppressioni. Scegliere SMTP non rimuove quelle funzionalità.
Come si invia un'email transazionale tramite Bird?
Chiama POST /v1/email/messages con un mittente verificato, i destinatari e contenuto inline o un template pubblicato. Imposta category: "transactional" per la posta operativa. La risposta è 202 Accepted con un ID messaggio; la consegna procede in modo asincrono.
Usa un Idempotency-Key per ogni invio logico. Bird conserva una risposta completata per tre ore. Un tentativo dopo quella finestra può creare un altro messaggio, quindi mantieni un tuo record degli eventi di business completati.
Iscriviti agli eventi email e associa email_id e recipient_id ai tuoi record. Un messaggio con più destinatari ha esiti separati per ogni destinatario.
Per la scelta del provider, la checklist per servizi di email transazionali copre le funzionalità di consegna e operative da confrontare.