Statistiche email API

L'API delle statistiche email restituisce gli aggregati mostrati sulla dashboard Metrics, più il verdetto sullo stato di invio calcolato a partire da essi. Usalo per costruire dashboard, esportare dati o monitorare lo stato delle email. Richiede una chiave API con accesso in lettura allo scope emails.

I metodi tipizzati sono disponibili negli SDK TypeScript, Python, PHP e Go sotto email.stats e email.health; la bird CLI li espone come bird email stats e bird email health; un agent li raggiunge tramite i tool MCP email_stats_* e email_health. Gli schemi completi di request e response sono nel reference API.

L'aggregato e la serie temporale

Tre endpoint coprono la parte superiore della dashboard:

GET /v1/email/stats/summary restituisce una singola riga aggregata per l'intera finestra. Include i conteggi del ciclo di vita per accepted, delivered, bounced, complained, opened, clicked e i relativi sotto-tipi. Include anche i valori derivati delivery_rate, bounce_rate, complaint_rate, open_rate e click_rate. I percentili di latenza per processing, delivery e totale coprono p50, p95 e p99. Passa compare=previous_period e la risposta includerà anche la finestra precedente di pari durata e la variazione rispetto a essa.
GET /v1/email/stats/daily e GET /v1/email/stats/hourly restituiscono gli stessi conteggi con una riga per giorno o per ora, riempiendo i vuoti con righe a zero in modo che un grafico non abbia mai buchi.

Ogni rate viene restituito come frazione tra 0 e 1, quindi un delivery_rate di 0.9939 equivale al 99,39 %. Un rate il cui denominatore è zero è null: è così che un periodo senza consegne riporta open_rate anziché indicare 0. I rate usano l'event time per l'attribuzione. Il send time non influisce sulla finestra che include un evento, quindi l'engagement che arriva durante la finestra per un messaggio precedente viene incluso. La formula esatta di ciascun rate, incluso il modo in cui un bounce out-of-band tardivo sposta un destinatario fuori dal conteggio dei delivered, è documentata campo per campo nel reference summary.

Ogni risposta riporta la finestra su cui è stata calcolata, più data_as_of: l'istante a cui i dati sono aggiornati. L'aggregazione si aggiorna ogni pochi secondi, quindi la risposta è near-real-time, non live. Mostra data_as_of nella tua dashboard invece di presentare i numeri come aggiornati al secondo.

Scegliere la finestra

from e to accettano un giorno di calendario (YYYY-MM-DD) oppure un istante RFC 3339, e le forme accettate variano da endpoint a endpoint:

Endpoint	Limiti	Finestra massima
/summary	Entrambi giorni, o entrambi istanti	365 giorni, o 720 ore con istanti
/daily	Giorni di calendario	365 giorni
/hourly	Istanti RFC 3339	720 ore (30 giorni)

I limiti basati su istanti hanno granularità oraria, ed è per questo che un "last 24 hours" rolling è una singola richiesta. Su /summary, mischiare un giorno con un istante restituisce un 422.

Imposta timezone su un identificatore IANA come America/New_York per avere i confini di giorno e ora, e i valori predefiniti usati quando ometti from e to, calcolati in quel fuso orario anziché in UTC. Finché timezone è impostato, from e to non devono includere un offset UTC proprio.

Breakdown

I 13 endpoint di breakdown suddividono gli stessi numeri di consegna ed engagement per una dimensione:

Mittenti: /sending-domains, /sending-ips e /recipient-domains (il dominio della casella a cui hai inviato).
Dove è arrivato: /mailbox-providers (Gmail, Outlook e così via) e /mailbox-provider-regions.
Cosa hai inviato: /tags (i tag impostati al momento dell'invio, il taglio più flessibile), /categories, /templates e /broadcasts.
Contesto di engagement: /locations (area geografica del destinatario) e /clients (il client di posta che ha renderizzato l'apertura).
Errori: /bounce-codes (raggruppati per risposta del server ricevente) e /complaint-types.

Tutti si trovano sotto /v1/email/stats/. Le righe vengono restituite in ordine decrescente per una metrica sort e limitate a limit (predefinito 50, massimo 200). La risposta include anche total, il numero di valori distinti della dimensione nella finestra. Confronta total con il conteggio delle righe restituite per identificare un risultato troncato. Le righe il cui rate di ordinamento ha denominatore zero vanno per ultime.

Il valore predefinito di sort di ogni endpoint è la metrica per cui è pensato ordinare:

Predefinito	Breakdown
processed	/tags, /categories, /templates, /broadcasts, /sending-domains, /recipient-domains
delivered	/sending-ips, /mailbox-providers, /mailbox-provider-regions
unique_opens	/locations, /clients
bounced	/bounce-codes
complained	/complaint-types

include_trend=true aggiunge una serie di rate per bucket a ogni riga, pronta per sparkline. Si applica ai breakdown tag, category, template, sending-domain, sending-IP, recipient-domain, mailbox-provider e mailbox-provider-region.

Gli endpoint di riepilogo e serie temporale accettano anche un filtro per dimensione per richiesta. Scegli tra category, sending_domain, sending_ip, recipient_domain, tag o template. Il filtro circoscrive un aggregato a un mittente o una campagna senza passare a un breakdown. Passarne più di uno restituisce un 422.

Stato di invio

GET /v1/email/health risponde alla domanda che gli aggregati lasciano a te: se il tuo invio si sta avviando verso problemi. Restituisce un verdetto per la finestra temporale più segnali per consegna, aperture, bounce e reclami. Ogni segnale include il proprio tasso e verdetto. I segnali di consegna, bounce e reclamo includono anche le soglie che determinano i rispettivi verdetti; il tasso di apertura non ha soglie di rischio. Questo permette a un badge di stato di seguire le nostre fasce senza una copia compilata nel tuo client.

Esempio di codice

{
  "period": {
    "data_as_of": null,
    "from": "2026-05-25",
    "to": "2026-06-01"
  },
  "status": "watching",
  "signals": [
    {
      "metric": "delivery_rate",
      "value": 0.995,
      "limit": null,
      "status": "healthy",
      "thresholds": {
        "direction": "below",
        "throttled": 0.984,
        "watching": 0.99
      }
    },
    {
      "metric": "open_rate",
      "value": 0.20100503,
      "limit": null,
      "status": "healthy"
    },
    {
      "metric": "bounce_rate",
      "value": 0.005,
      "limit": 0.005,
      "status": "watching",
      "thresholds": {
        "direction": "above",
        "throttled": 0.006,
        "watching": 0.004
      }
    },
    {
      "metric": "complaint_rate",
      "value": 0.00010050251,
      "limit": 0.003,
      "status": "healthy",
      "thresholds": {
        "direction": "above",
        "throttled": 0.001,
        "watching": 0.0006
      }
    }
  ]
}

Confronta ogni segnale sul suo metric. Il status di primo livello è il peggiore tra i verdetti di consegna, bounce e reclamo: healthy, watching o throttled. open_rate è escluso da questo riepilogo, perché un tasso di apertura alto non è mai un rischio, ed è l'unico segnale che può restituire strong.

Due campi di un segnale sono facili da confondere. limit è il limite di deliverability di riferimento per il tasso, ed è null sui tassi che non ne hanno uno. thresholds indica dove cambia il verdetto stesso: watching e throttled sono le due soglie, e direction indica il lato rischioso, above per i tassi di bounce e reclamo e below per il tasso di consegna. Le soglie sono esclusive, quindi un tasso che cade esattamente su una di esse mantiene lo stato migliore.

Poiché le soglie vengono restituite nella risposta, puoi valutare segmenti che questo endpoint non calcola: ordina i tuoi mittenti con /sending-domains, poi classifica ogni riga confrontandola con le soglie del tasso di bounce restituite dalla risposta health. La dashboard Metrics usa fasce di avviso separate per i tassi di hard-bounce e reclamo. Questo API valuta i tassi aggregati di bounce, reclamo e consegna, quindi il suo verdetto può differire da un avviso della dashboard.

Un verdetto throttled segnala un rischio di deliverability. Non mette in pausa il tuo invio.

La finestra temporale funziona diversamente dagli endpoint precedenti. from e to sono giorni di calendario in UTC, non esiste il parametro timezone e nessun filtro per dimensione si applica. Se li ometti entrambi, la finestra termina oggi e inizia 7 giorni prima. Il massimo è 365 giorni.

Traffico di test nei numeri

Gli invii agli indirizzi sandbox passano attraverso la stessa aggregazione, quindi il traffico di test compare in ogni endpoint esattamente come sulla dashboard.

Passaggi successivi

Metriche email: come la dashboard presenta questi numeri e quando intervenire
Reference del riepilogo statistiche: ogni campo, filtro e formula dei tassi
Reference dello stato di invio: il verdetto, i segnali per tasso e le relative soglie
Eventi e webhook: il flusso per destinatario quando un aggregato non è sufficiente

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaGetting started with email Esplora la funzionalitàEmail Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Prova l'esercitazione e ottieni un brief di implementazione