Eventi email
Emettiamo eventi man mano che ogni destinatario avanza nella consegna. Un invio a tre indirizzi produce tre flussi indipendenti, correlati da email_id e recipient_id. Questa pagina definisce i tipi di evento email. Consulta Webhook per firme, nuovi tentativi, ordinamento e replay.
Ogni destinatario parte da email.accepted, poi email.processed. Un destinatario broadcast è un messaggio a sé, quindi riceve anche il proprio email.accepted, anche se solo negli eventi API e nel log email anziché come webhook. Da lì il messaggio viene accettato dal server ricevente (email.delivered), viene differito e riprovato (email.deferred, che si risolve in consegnato o rimbalzato), viene rifiutato dal server ricevente (email.bounced), oppure non riceve mai un tentativo di consegna (email.rejected). Dopo una consegna il flusso può proseguire con email.out_of_band_bounce, email.complained, email.opened, email.clicked, email.unsubscribed e email.list_unsubscribed.
Ogni destinatario termina in esattamente uno stato terminale, delivered, bounced, complained o rejected, restituito come status per destinatario da GET /v1/email/messages/{message_id}/recipients. Gli eventi di coinvolgimento non lo cambiano mai: un destinatario che ha aperto resta comunque delivered. Un bounce report tardivo invece lo cambia, perché il server ricevente sta ritrattando un'accettazione già data, quindi il destinatario passa da delivered a bounced. Il messaggio nel suo complesso ha un proprio stato aggregato e conteggi per stato su GET /v1/email/messages/{message_id}.
L'envelope dell'evento
Gli eventi arrivano come l'envelope a tre campi usato da ogni webhook: type, timestamp (quando l'evento si è verificato, RFC 3339) e un oggetto data specifico per tipo.
{
"type": "email.delivered",
"timestamp": "2026-07-23T14:51:47.107Z",
"data": {
"email_id": "em_01ky7qc398fmxraqtxn604zeq9",
"recipient_id": "er_01ky7qc398fmwsc96nt6anrbqs",
"workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
"recipient": "delivered@messagebird.dev",
"recipient_role": "to",
"tags": [{ "name": "category", "value": "welcome" }],
"metadata": { "order_id": "ord_123" },
"broadcast_id": null,
"brand_id": null
}
}Ogni evento in uscita a livello di destinatario include email_id, recipient_id, workspace_id, l'indirizzo recipient e il suo envelope recipient_role (to, cc o bcc). Quando invii, memorizza una corrispondenza tra spazio di lavoro e ID del messaggio e i tuoi record. tags e metadata riportano il contesto dell'invio quando disponibile. Sono null quando non è stato fornito alcun contesto, e su email.unsubscribed e email.list_unsubscribed provenienti da link di disiscrizione Bird per singoli invii. Anche gli eventi di disiscrizione dei broadcast possono restituire null quando il loro contesto non è disponibile.
broadcast_id indica il broadcast di cui l'invio faceva parte ed è null su un invio senza broadcast associato. Un link di disiscrizione da mail inviata prima dell'aggiunta del campo non indica alcun broadcast, quindi un opt-out tramite quel link riporta null indipendentemente dal fatto che un broadcast abbia inviato la mail. Tratta null su email.unsubscribed e email.list_unsubscribed come non conclusivo. broadcast_id ti raggiunge solo sul webhook: gli eventi API qui sotto restituiscono ogni evento senza di esso. I tipi di evento aggiungono i campi descritti nelle sezioni seguenti.
I webhook delle email in uscita includono anche il campo facoltativo brand_id. L’API degli eventi dei messaggi omette questo campo.
Gli stessi eventi sono interrogabili a posteriori da GET /v1/email/messages/{message_id}/events, dove ciascuno ha anche un id (prefisso ev_) e un occurred_at. Usali per backfill, replay o riconciliazione rispetto a ciò che il tuo endpoint ha ricevuto. Alcuni campi ti raggiungono solo tramite quell'API anziché tramite il webhook; la descrizione dell'evento pertinente li identifica.
Eventi del ciclo di vita
email.accepted
Abbiamo accettato l'invio e iniziato a preparare la consegna. Si attiva una volta per destinatario richiesto ed è il primo evento di quel flusso. Anche un destinatario broadcast ne riceve uno, perché ogni destinatario è un messaggio a sé, ma viene registrato anziché consegnato: leggilo dagli eventi API o dall'email log, non dal tuo endpoint webhook. Payload: solo la base identità.
email.processed
Il messaggio è stato costruito e messo in coda per la consegna al mail server del destinatario. Payload: solo la base identità sul webhook; gli eventi API aggiungono mailbox_provider e mailbox_provider_region, la classificazione del sistema di posta ricevente (ad esempio gmail, NA), presente quando è stato possibile determinarla e null altrimenti. Confrontare il timestamp di questo evento con quello di email.accepted ti dà il nostro tempo di elaborazione su un singolo invio. Un broadcast non ha tale intervallo: la sua accettazione e la sua elaborazione condividono lo stesso istante di dispatch, quindi i due timestamp coincidono anziché delimitare un'elaborazione, e l'accettazione ti raggiunge solo tramite gli eventi API, come occurred_at.
email.delivered
Il mail server ricevente ha accettato il messaggio e se ne è preso la responsabilità. Questo evento non attesta il posizionamento in inbox né la lettura. Inbox Insights fornisce stime campionate di posizionamento; gli eventi di apertura e clic registrano le richieste di tracking. Payload: solo la base identità sul webhook; gli eventi API aggiungono sending_ip, l'indirizzo da cui il messaggio è stato inviato, utile quando un problema di deliverability riguarda un singolo IP, più mailbox_provider e mailbox_provider_region.
email.deferred
Un errore temporaneo: il server ricevente ha chiesto di riprovare più tardi (casella piena, greylisting, limitazione delle richieste). Riproviamo automaticamente, e il destinatario alla fine si risolve in email.delivered o email.bounced, quindi questo evento è informativo anziché terminale, e un destinatario può essere differito più volte prima. Payload: bounce_type, bounce_class, defer_reason (il motivo fornito dal server) e sending_ip sul webhook; gli eventi API aggiungono mailbox_provider e mailbox_provider_region.
Eventi di errore
email.bounced
Un errore permanente al momento di SMTP: il server ricevente ha rifiutato il messaggio e lo stato terminale del destinatario diventa bounced. Payload: bounce_type (vedi la tabella di classificazione), bounce_class, bounce_code (il codice di risposta SMTP, ad esempio 550), bounce_description (il motivo fornito dal server) e sending_ip sul webhook; gli eventi API aggiungono mailbox_provider e mailbox_provider_region. Un hard bounce sopprime l'indirizzo.
email.out_of_band_bounce
Un bounce tardivo: il server ricevente ha accettato il messaggio al momento di SMTP e poi ha inviato un bounce report successivamente. Ha la stessa classificazione di email.bounced (bounce_type, bounce_class, bounce_code, bounce_description, sending_ip sul webhook; mailbox_provider e mailbox_provider_region dagli eventi API). Quando il report viene classificato come bounce (qualsiasi classe nella tabella), il server ha ritrattato la sua accettazione precedente, quindi il destinatario passa da delivered a bounced. I report la cui classe non è nella tabella, come le risposte automatiche, vengono registrati nella timeline e non modificano lo stato. Un hard out-of-band bounce sopprime anch'esso l'indirizzo.
email.rejected
Il messaggio destinato al destinatario non ha mai raggiunto il server di posta remoto, quindi non è stata tentata alcuna consegna. È questo che distingue un rifiuto da un bounce, in cui è il server ricevente a rifiutare il messaggio. Payload: rejection_reason, presente anche nel record del destinatario:
rejection_reason | Significato |
|---|---|
recipient_suppressed | Il destinatario è bloccato dalla lista di soppressione o da una preferenza dichiarata, quindi la consegna non è mai stata tentata |
transmission_failed | Il messaggio non è stato trasmesso per la consegna |
generation_failure | Il messaggio non è stato costruito per la consegna, a causa di un problema di template o contenuto |
policy_rejection | La policy di invio ha rifiutato il messaggio |
domain_unverified | Il dominio di invio non era verificato |
quota_exceeded | La quota di invio dell'organizzazione è stata raggiunta |
recipient_not_allowed | Il destinatario non era consentito per questo invio; gli invii su un dominio di onboarding condiviso raggiungono solo i membri verificati del tuo spazio di lavoro |
workspace_suspended | Lo spazio di lavoro è sospeso, quindi questa email non è stata inviata e non verrà inviata dopo la riattivazione |
Bird aggiunge nel tempo nuovi motivi di rifiuto, quindi un webhook o un record del destinatario può contenerne uno non ancora presente in questa tabella. Gestisci un motivo sconosciuto come un rifiuto con causa non elencata e conserva il valore per poterlo consultare in seguito.
Gli eventi API aggiungono anche mailbox_provider e mailbox_provider_region quando il sistema di posta ricevente è stato classificabile prima del rifiuto.
email.complained
Il destinatario ha contrassegnato il messaggio come spam e il provider di posta lo ha segnalato tramite il proprio feedback loop. I reclami arrivano dopo la consegna e impostano lo stato terminale a complained. Payload: feedback_type, il tipo di segnalazione inviata dal provider, come abuse o fraud, oppure null quando il provider non lo ha specificato, più mailbox_provider e mailbox_provider_region dagli eventi API. Un reclamo blocca la mail di marketing per il Brand a cui è attribuito, oppure in tutto lo spazio di lavoro quando non è disponibile un'attribuzione affidabile a un Brand. Mantieni basso il tasso di reclami: i provider limitano i mittenti che accumulano segnalazioni.
Eventi di coinvolgimento
email.opened
Il pixel di tracking nel corpo del messaggio è stato caricato. Payload: ip_address e user_agent quando noti; gli eventi API aggiungono is_prefetched, country (ISO 3166-1 alpha-2, derivato dall'IP del client), mailbox_provider e mailbox_provider_region. Controlla is_prefetched prima di contare un'apertura. È true quando una funzionalità di privacy dell'inbox ha recuperato il pixel automaticamente anziché una persona che apre il messaggio, e contarli gonfia il tasso di apertura. Tracking di apertura e clic descrive la strumentazione.
email.clicked
Il destinatario ha cliccato un link tracciato. Payload: url (il link cliccato), ip_address e user_agent quando noti; gli eventi API aggiungono country, mailbox_provider e mailbox_provider_region. I clic sono generalmente un segnale di coinvolgimento più forte delle aperture, perché i proxy di privacy possono caricare i pixel di tracking automaticamente.
email.unsubscribed
Il destinatario ha usato il link di disiscrizione nel corpo del messaggio. Payload: solo la base identità sul webhook; gli eventi API aggiungono mailbox_provider e mailbox_provider_region. Registra una preferenza di opt-out che blocca la mail di marketing. Link di disiscrizione descrive come il link viene inserito nella tua mail.
email.list_unsubscribed
Il destinatario ha usato il pulsante di disiscrizione one-click che il provider di posta mostra nella propria UI, guidato dagli header List-Unsubscribe del messaggio. Payload: solo la base identità sul webhook (più mailbox_provider e mailbox_provider_region dagli eventi API); il meccanismo è il tipo di evento stesso, ed è per questo che è separato da email.unsubscribed. Registra anch'esso una preferenza di opt-out che blocca la mail di marketing.
Eventi a livello di messaggio
Due eventi descrivono il messaggio nel suo complesso anziché un singolo destinatario. Il loro data contiene quindi email_id, workspace_id, brand_id, tags e metadata, ma nessuna identità del destinatario. Entrambi appartengono all’invio programmato.
email.scheduled
Abbiamo accettato un invio con un scheduled_at nel futuro. Payload: la base a livello di messaggio più scheduled_at. Quando quel momento arriva, il ciclo di vita per destinatario inizia da email.accepted.
email.canceled
Un messaggio programmato è stato annullato prima della partenza, quindi non produce alcun evento del ciclo di vita per destinatario. Payload: solo la base a livello di messaggio.
Eventi inbound e mailbox
email.received copre la posta in arrivo. Si attiva quando riceviamo e analizziamo un messaggio inbound. Il suo payload include inbound_message_id, indirizzamento, oggetto e verdetti di autenticazione. Setup, payload e l'API di fetch-back sono in Ricezione email. Una mailbox ha la propria famiglia email_mailbox.* in aggiunta, documentata nella guida alle mailbox.
Classificazione dei bounce
bounce_class è la classificazione numerica dei bounce inclusa in email.bounced, email.out_of_band_bounce e email.deferred. Si aggrega nella categoria grossolana bounce_type e conserva il codice di dettaglio, così puoi distinguere una casella piena da un errore di routing anche se entrambi risultano come soft:
bounce_class | bounce_type | Significato |
|---|---|---|
1 | undetermined | La risposta del server ricevente era ambigua |
10, 30 | hard | Errore permanente: indirizzo non valido o dominio inesistente |
20 a 24, 40, 70, 100 | soft | Errore transitorio: casella piena, server temporaneamente non disponibile, problema DNS o di routing |
25 | admin | Rifiuto amministrativo: relay negato, dominio in blocklist |
50 a 54 | block | Il server ricevente ha rifiutato l'IP di invio |
Qualsiasi classe fuori da questa lista corrisponde a undetermined. Solo i bounce hard sopprimono l'indirizzo; soft, block, admin e undetermined no, perché l'indirizzo potrebbe essere ancora raggiungibile.
Soppressione automatica
Gli hard bounce creano soppressioni valide per l'intero spazio di lavoro. I reclami per spam con un'attribuzione affidabile a un Brand registrano preferenze email protette per quel Brand; i reclami senza un'attribuzione affidabile creano soppressioni valide per l'intero spazio di lavoro.
| Evento | Risultato | Cosa blocca |
|---|---|---|
email.bounced o email.out_of_band_bounce con bounce_type: "hard" | Soppressione con reason: hard_bounce | Tutte le categorie, per tutti i Brand |
email.complained con attribuzione affidabile a un Brand | Preferenza con origin: complaint | Mail non transazionale di quel Brand |
email.complained senza attribuzione affidabile a un Brand | Soppressione con reason: complaint | Mail non transazionale di tutti i Brand |
email.complained resta l'evento di reclamo a livello di messaggio. Un reclamo su un Brand che porta la preferenza effettiva a revocata emette anche preference.revoked, con preference_id e brand_id. I reclami ripetuti non producono necessariamente un'altra transizione di preferenza. Recupera la preferenza per conoscerne l'origine attuale, lo stato e l'complaint_message_id conservato.
Iscriviti a preference.revoked, preference.granted e preference.deleted quando sincronizzi le scelte dei destinatari, anche in uno spazio di lavoro con un solo Brand. Usali per aggiornare la preferenza attuale e il suo ambito: canale, handle, Brand, mittente e argomento. I timestamp delle preferenze indicano il momento effettivo del consenso, non l'ordine delle modifiche, quindi ordinarli non permette di ricostruire lo stato o la copertura attuali. Conferma le eliminazioni tramite riconciliazione, conservando le preferenze indipendenti e le soppressioni dello spazio di lavoro.
Un reclamo limitato a un Brand non emette email_suppression.created. Quell'evento descrive le aggiunte alla lista di soppressione dello spazio di lavoro, con suppression_id, email, reason e workspace_id. Le rimozioni di soppressioni non hanno un webhook per i clienti, quindi una copia richiede anche una riconciliazione periodica dell'intera lista paginata. Le soppressioni per reclamo già esistenti a livello di spazio di lavoro mantengono il proprio ambito. Segui la procedura di sincronizzazione della guida alla migrazione, incluso riprovare le letture che non riescono o che non riflettono ancora una modifica.
Anche email.unsubscribed e email.list_unsubscribed registrano preferenze. Link di disiscrizione ne spiega l'effetto. Soppressioni spiega come verificare la protezione da reclami e registrare un nuovo opt-in individuale più recente.
Gli invii successivi a un indirizzo soppresso vengono rifiutati in anticipo come email.rejected con rejection_reason: "recipient_suppressed", e non incidono mai sulla tua deliverability.
Prossimi passi
- Webhook ed eventi: configurazione dell'endpoint, verifica della firma, nuovi tentativi e replay
- Soppressioni: come funziona la lista di soppressione e come gestirla
- Link di disiscrizione: configurare i percorsi dietro
email.unsubscribedeemail.list_unsubscribed - Testing e sandbox: gli invii sandbox emettono eventi reali attraverso il percorso normale, il modo più economico per testare il tuo handler
- Webhook fatti bene: eventi di consegna affidabili: un video che crea un webhook e mostra gli eventi in arrivo
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.