E-Mail-Statistik API

Die E-Mail-Statistik-API liefert die Aggregatwerte des Metrics-Dashboards sowie die daraus berechnete Sendezustandsbewertung. Nutzen Sie sie, um Dashboards zu erstellen, Daten zu exportieren oder die E-Mail-Zustellbarkeit zu überwachen. Sie erfordern einen API-Schlüssel mit Lesezugriff auf den emails-Scope.

Typisierte Methoden sind in den TypeScript-, Python-, PHP- und Go-SDKs unter email.stats und email.health verfügbar. Die bird CLI stellt sie als bird email stats und bird email health bereit, und ein Agent erreicht sie über die email_stats_*- und email_health-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.

Sendezustand

GET /v1/email/health beantwortet die Frage, die die Aggregatwerte Ihnen überlassen: ob Ihr Versand auf Probleme zusteuert. Der Endpunkt liefert eine Bewertung für das Zeitfenster sowie Signale für Zustellung, Öffnungen, Bounces und Beschwerden. Jedes Signal enthält seine Rate und Bewertung. Die Signale für Zustellung, Bounces und Beschwerden enthalten zusätzlich die Grenzwerte, die ihre Bewertungen bestimmen; die Öffnungsrate hat keine Risikogrenzwerte. So kann ein Statusindikator unseren Stufen folgen, ohne dass eine Kopie davon in Ihren eigenen Client kompiliert ist.

Codebeispiel

{
  "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
      }
    }
  ]
}

Gleichen Sie jedes Signal anhand seines metric ab. Die übergeordnete status ist die schlechteste der Bewertungen für Zustellung, Bounces und Beschwerden: healthy, watching oder throttled. open_rate liegt außerhalb dieser Zusammenfassung, weil eine hohe Öffnungsrate nie ein Risiko ist und es das einzige Signal ist, das strong annehmen kann.

Zwei Felder eines Signals werden leicht verwechselt. limit ist der Referenz-Zustellbarkeitswert für die Rate und ist null bei Raten, die keinen haben. thresholds gibt an, wo sich die Bewertung selbst ändert: watching und throttled sind die beiden Grenzwerte, und direction benennt die riskante Seite davon, above für Bounce- und Beschwerderaten und below für die Zustellrate. Die Grenzwerte sind exklusiv, sodass eine Rate, die genau auf einem liegt, den besseren Status behält.

Da die Grenzwerte in der Antwort enthalten sind, können Sie Segmente bewerten, die dieser Endpunkt nicht berechnet: Sortieren Sie Ihre Absender mit /sending-domains und klassifizieren Sie jede Zeile anhand der Bounce-Rate-Grenzwerte aus der Health-Antwort. Das Metrics-Dashboard verwendet separate Warnstufen für Hard-Bounce- und Beschwerderaten. Dieser API bewertet aggregierte Bounce-, Beschwerde- und Zustellraten, sodass seine Bewertung von einer Dashboard-Warnung abweichen kann.

Eine throttled-Bewertung meldet ein Zustellbarkeitsrisiko. Sie pausiert Ihren Versand nicht.

Das Zeitfenster funktioniert anders als bei den obigen Endpunkten. from und to sind Kalendertage in UTC, es gibt keinen timezone-Parameter, und kein Dimensionsfilter greift. Lassen Sie beide weg, endet das Fenster heute und beginnt 7 Tage früher. Das Maximum beträgt 365 Tage.

Testverkehr in den Zahlen

Sendungen an Sandbox-Adressen durchlaufen dieselbe Aggregation, sodass Testverkehr in jedem Endpunkt 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: alle Felder, Filter und Ratenformeln
Sending-Health-Referenz: die Bewertung, ihre ratenbezogenen Signale und deren Grenzwerte
Events und Webhooks: der Empfänger-Stream, wenn ein Aggregatwert nicht ausreicht