E-Mail-Statistik API
Die E-Mail-Statistik API liefert die Aggregate, die auf dem Metrics-Dashboard angezeigt werden. Nutzen Sie sie, um Dashboards zu erstellen, Daten zu exportieren oder die E-Mail-Zustellqualität zu überwachen. Sie erfordern einen API-Schlüssel mit Lesezugriff auf den Scope emails.
Typisierte Methoden sind in den TypeScript-, Python- und Go-SDKs unter email.stats verfügbar, die bird CLI stellt sie als bird email stats bereit, und ein Agent erreicht sie über die email_stats_* MCP-Tools. Vollständige Request- und Response-Schemas finden Sie in der API-Referenz.
Das Aggregat und die Zeitreihe
Drei Endpoints decken den oberen Bereich des Dashboards ab:
- GET /v1/email/stats/summary gibt eine einzelne Aggregatzeile für das gesamte Zeitfenster zurück. Enthalten sind Lifecycle-Zähler für accepted, delivered, bounced, complained, opened, clicked und deren Untertypen. Ebenfalls enthalten sind die abgeleiteten delivery_rate, bounce_rate, complaint_rate, open_rate und click_rate. Latenz-Perzentile für Processing, Delivery und Gesamt decken p50, p95 und p99 ab. Übergeben Sie compare=previous_period, und die Antwort enthält zusätzlich das vorangehende gleich lange Zeitfenster sowie die Veränderung dazu.
- GET /v1/email/stats/daily und GET /v1/email/stats/hourly geben dieselben Zähler mit einer Zeile pro Tag oder pro Stunde zurück, aufgefüllt mit Nullzeilen, damit ein Diagramm keine Lücken hat.
Jede Rate wird als Bruch zwischen 0 und 1 zurückgegeben, d. h. ein delivery_rate von 0.9939 entspricht 99,39 %. Eine Rate mit dem Nenner null ist null – so meldet ein Zeitraum ohne Zustellungen open_rate, statt 0 anzuzeigen. Raten verwenden die Ereigniszeit zur Zuordnung. Die Sendezeit beeinflusst nicht, in welches Zeitfenster ein Ereignis fällt; Engagement, das während des Zeitfensters für eine ältere Nachricht eintrifft, wird einbezogen. Die genaue Formel hinter jeder Rate, einschließlich des Falls, dass ein verspäteter Out-of-Band-Bounce einen Empfänger aus der Zustellzählung entfernt, ist pro Feld in der Summary-Referenz dokumentiert.
Jede Antwort enthält das berechnete Zeitfenster sowie data_as_of: den Zeitpunkt, bis zu dem die Zahlen aktuell sind. Die Aggregation wird alle paar Sekunden aktualisiert, daher ist eine Antwort nahezu in Echtzeit, nicht live. Beschriften Sie Ihr eigenes Dashboard mit data_as_of, statt die Zahlen als sekundengenau darzustellen.
Das Zeitfenster wählen
from und to akzeptieren entweder einen Kalendertag (YYYY-MM-DD) oder einen RFC-3339-Zeitstempel; welche Formen ein Endpoint annimmt, unterscheidet sich:
| Endpoint | Grenzen | Maximales Zeitfenster |
|---|---|---|
| /summary | Beide Tage oder beide Zeitstempel | 365 Tage oder 720 Stunden bei Zeitstempeln |
| /daily | Kalendertage | 365 Tage |
| /hourly | RFC-3339-Zeitstempel | 720 Stunden (30 Tage) |
Zeitstempel-Grenzen haben Stundengenauigkeit, weshalb ein rollierendes "last 24 hours" mit einem einzigen Request möglich ist. Bei /summary gibt die Kombination aus Tag und Zeitstempel einen 422 zurück.
Setzen Sie timezone auf einen IANA-Bezeichner wie America/New_York, damit Tages- und Stundengrenzen sowie die Standardwerte, die beim Weglassen von from und to gelten, in dieser Zeitzone statt in UTC berechnet werden. Solange timezone gesetzt ist, dürfen from und to keinen eigenen UTC-Offset enthalten.
Aufschlüsselungen
Die 13 Aufschlüsselungs-Endpoints teilen dieselben Zustell- und Engagement-Zahlen nach jeweils einer Dimension auf:
- Absender: /sending-domains, /sending-ips und /recipient-domains (die Mailbox-Domain, an die Sie gesendet haben).
- Zielort: /mailbox-providers (Gmail, Outlook usw.) und /mailbox-provider-regions.
- Was Sie gesendet haben: /tags (die Tags, die Sie beim Senden gesetzt haben – die flexibelste Aufteilung), /categories, /templates und /broadcasts.
- Engagement-Kontext: /locations (Geografie des Empfängers) und /clients (der E-Mail-Client, der das Öffnen gerendert hat).
- Fehler: /bounce-codes (gruppiert nach der Antwort des empfangenden Servers) und /complaint-types.
Alle befinden sich unter /v1/email/stats/. Zeilen werden absteigend nach einer sort-Metrik sortiert und auf limit begrenzt (Standard 50, Maximum 200). Die Antwort enthält außerdem total, die Anzahl unterschiedlicher Dimensionswerte im Zeitfenster. Vergleichen Sie total mit der zurückgegebenen Zeilenanzahl, um ein gedeckeltes Ergebnis zu erkennen. Zeilen, deren Sortiermetrik eine Rate mit dem Nenner null ist, stehen am Ende.
Der sort-Standard jedes Endpoints ist die Metrik, nach der er sortieren soll:
| Standard | Aufschlüsselungen |
|---|---|
| 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 fügt jeder Zeile eine Rate-Reihe pro Bucket hinzu, bereit für Sparklines. Es gilt für die Aufschlüsselungen nach Tag, Kategorie, Template, Sende-Domain, Sende-IP, Empfänger-Domain, Mailbox-Provider und Mailbox-Provider-Region.
Die Summary- und Zeitreihen-Endpoints akzeptieren außerdem einen Dimensions-Filter pro Request. Wählen Sie category, sending_domain, sending_ip, recipient_domain, tag oder template. Der Filter beschränkt ein Aggregat auf einen Absender oder eine Kampagne, ohne zu einer Aufschlüsselung zu wechseln. Die Angabe von mehr als einem gibt einen 422 zurück.
Testverkehr in den Zahlen
Sendungen an Sandbox-Adressen durchlaufen dieselbe Aggregation, sodass Testverkehr in jedem Endpoint hier genauso erscheint wie im Dashboard.
Nächste Schritte
- E-Mail-Metriken: wie das Dashboard diese Zahlen darstellt und wann Sie handeln sollten
- Stats-Summary-Referenz: jedes Feld, jeder Filter und jede Rate-Formel
- Events und Webhooks: der Empfänger-bezogene Stream, wenn ein Aggregat nicht ausreicht
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.
Watch the guideGetting started with emailExplore the capabilityEmailFollow the learning pathBuild your first integrationImplementation guideSend your first email
Try the practice and get an implementation brief