La tua applicazione invia dati strutturati a un endpoint HTTP e riceve una risposta con il risultato del messaggio o un errore. Quella richiesta e risposta sono la superficie operativa di un API email.
Cosa gestisce un API email?
Un endpoint di invio accetta destinatari, un oggetto e contenuto testuale o HTML. Può anche accettare header, tag, template e allegati quando il provider li supporta.
Un endpoint di eventi o webhook riporta cosa è successo dopo l'accettazione. Gli eventi comuni includono consegna, bounce, reclamo, apertura e clic. Un API di ricezione trasforma la posta in entrata in messaggi strutturati per la tua applicazione, evitandoti di interrogare una casella di posta.
In cosa differisce un API email da SMTP?
SMTP richiede che la tua applicazione apra una connessione, si autentichi, invii comandi e legga i codici di risposta. Un API email usa invece richieste HTTP, così una libreria client può gestire il riutilizzo delle connessioni, la codifica JSON, i tentativi e il parsing delle risposte.
Scegli un API quando la tua applicazione usa già HTTP, ha bisogno di eventi strutturati o gira in ambienti dove aprire connessioni SMTP è scomodo. Scegli un relay SMTP quando una libreria mail esistente o un mail server parla già SMTP. I due percorsi possono consegnare lo stesso messaggio.
| Operazione | API di invio | Relay SMTP | API mailbox |
|---|---|---|---|
| Inviare un messaggio | Sì | Sì | Risposta o composizione |
| Ricevere posta elaborata | Alcuni provider | No | Sì |
| Leggere la cronologia | Alcuni provider | No | Sì |
| Osservare la consegna | Eventi o webhook | Codici di risposta ed eventi | Stato del messaggio ed eventi |
I prodotti usano il termine API email per insiemi di funzionalità diversi. Verifica lo schema del provider prima di dare per scontato che un singolo API copra ogni riga.
Cosa deve includere una richiesta API?
Invia i campi richiesti dal tuo provider. Registra l'identificativo del messaggio restituito. Mantieni una tua chiave di idempotenza quando un nuovo tentativo non deve creare un invio duplicato. Valida i destinatari prima dell'invio. Tieni i segreti sul tuo server.
Un esempio di richiesta transazionale contiene from, to, subject, text, category: transactional e una chiave di idempotenza conservata sul server. Usa un dominio di invio verificato prima di inviarla.
La risposta HTTP indica che il servizio ha accettato la richiesta. Gli eventi di consegna, bounce e reclamo arrivano dopo, quindi una risposta di accettazione non garantisce il recapito nella casella di posta.
Usa i webhook per gli eventi successivi invece di trattare una richiesta accettata come prova che il messaggio sia arrivato nella casella di posta. Gli eventi di consegna e reclamo descrivono cosa è successo dopo l'accettazione.
Come invio con Bird?
Chiami createEmailMessage API di Bird con la chiave API del tuo spazio di lavoro, il mittente, i destinatari, il contenuto e metadati opzionali. La guida all'invio email mostra i campi della richiesta e della risposta.
Per risposte e posta in entrata, crea una mailbox e consuma i relativi eventi di messaggio e consegna. La guida alle mailbox descrive quegli endpoint e i nomi dei webhook.
In sintesi
- Un API email espone l'invio e gli eventi dei messaggi tramite HTTP.
- La risposta conferma l'accettazione da parte di API, non il recapito nella casella di posta.
- Le chiavi di idempotenza rendono possibili nuovi tentativi sicuri.
- Bird offre API di invio e mailbox con guide per ciascun percorso.