Statystyki e-mail API

API statystyk e-mail zwraca zagregowane dane widoczne na dashboardzie Metrics oraz obliczoną na ich podstawie ocenę kondycji wysyłki. Używaj go do budowania dashboardów, eksportu danych lub monitorowania kondycji e-mail. Żądania wymagają dostępu do odczytu w zakresie emails.

Aby tworzyć raporty z połączonymi filtrami, wybranymi metrykami i pełnymi seriami czasowymi na grupę, użyj elastycznego endpointu zapytań. Aby eksplorować te raporty za pomocą asystenta, zobacz Zapytania o analitykę e-mail z AI.

Typowane metody są dostępne w SDK dla TypeScript, Python, PHP i Go pod email.stats i email.health, bird CLI udostępnia je jako bird email stats i bird email health, a agent dociera do nich przez email_stats_* i email_health narzędzia MCP. Pełne schematy żądań i odpowiedzi znajdziesz w dokumentacji API.

Agregat i serie czasowe

Trzy endpointy pokrywają górną część dashboardu:

• GET /v1/email/stats/summary zwraca jeden wiersz zagregowany dla całego okna. Zawiera liczniki cyklu życia: accepted, delivered, bounced, complained, opened, clicked i ich podtypy. Zawiera też pochodne delivery_rate, bounce_rate, complaint_rate, open_rate i click_rate. Percentyle opóźnień przetwarzania, dostarczania i całkowite obejmują p50, p95 i p99. Przekaż compare=previous_period, a odpowiedź uwzględni też poprzednie okno o równej długości i zmianę względem niego.
• GET /v1/email/stats/daily i GET /v1/email/stats/hourly zwracają te same liczniki po jednym wierszu na dzień lub na godzinę, z zerami w lukach, aby wykres nigdy nie miał przerw.

Wskaźniki są zwracane jako ułamki, więc delivery_rate równe 0.9939 to 99,39%. Wskaźnik, którego mianownik wynosi zero, ma wartość null, co pozwala okresowi bez dostarczeń raportować open_rate zamiast 0. Wskaźniki używają do atrybucji czasu zdarzenia. Czas wysyłki nie wpływa na to, które okno obejmuje zdarzenie, więc aktywność odnotowana w danym oknie dla starszej wiadomości jest uwzględniana. Wskaźniki otwarć i kliknięć mogą przekroczyć 1, gdy aktywność i dostarczenie wypadają w różnych oknach. Dokładna formuła każdego wskaźnika, w tym sposób, w jaki opóźniony bounce out-of-band zmienia efektywną liczbę dostarczeń, jest udokumentowana dla każdego pola w dokumentacji summary.

Odpowiedzi summary, daily i hourly zawierają okno czasowe oraz data_as_of, ostatnie udane odświeżenie agregatu, jeśli jest dostępne. Może mieć wartość null, a znacznik czasu nie gwarantuje, że wszystkie zdarzenia dotarły. Elastyczny endpoint zapytań zawsze zwraca data_as_of: null. Wyświetlaj dostępny znacznik czasu odświeżenia na dashboardzie, nie przedstawiając go jako dowodu kompletności danych.

Wybór okna

from i to przyjmują dzień kalendarzowy (YYYY-MM-DD) lub moment RFC 3339, a akceptowane formy różnią się w zależności od endpointu:

Granice momentowe mają rozdzielczość godzinową, dlatego ruchome "last 24 hours" to jedno żądanie. W /summary połączenie dnia z momentem zwraca 422.

Ustaw timezone na identyfikator IANA, np. America/New_York, aby granice dni i godzin oraz wartości domyślne stosowane przy pominięciu from i to były obliczane w tej strefie zamiast UTC. Gdy timezone jest ustawione, from i to nie mogą zawierać własnego przesunięcia UTC.

Rozkłady

13 endpointów rozkładów dzieli te same liczby dostarczeń i aktywności według jednego wymiaru:

• Nadawcy: /sending-domains, /sending-ips i /recipient-domains (domena skrzynki, do której wysłano).
• Gdzie trafiło: /mailbox-providers (Gmail, Outlook itp.) i /mailbox-provider-regions.
• Co wysłano: /tags (tagi ustawione w momencie wysyłki, najbardziej elastyczny przekrój), /categories, /templates i /broadcasts.
• Kontekst aktywności: /locations (geografia odbiorców) i /clients (klient poczty, w którym wyrenderowano otwarcie).
• Błędy: /bounce-codes (zgrupowane według odpowiedzi serwera odbiorczego) i /complaint-types.

Wszystkie znajdują się w /v1/email/stats/. Wiersze są zwracane malejąco według metryki sort i ograniczone do limit (domyślnie 50, maksymalnie 200). Odpowiedź zawiera też total, czyli liczbę unikalnych wartości wymiaru w oknie. Porównaj total z liczbą zwróconych wierszy, aby rozpoznać wynik obcięty limitem. Wiersze, których metryka sortowania jest wskaźnikiem z zerowym mianownikiem, trafiają na koniec.

Domyślna wartość sort każdego endpointu to metryka, według której ma on rankingować:

include_trend=true dodaje do każdego wiersza serię wskaźników w przedziałach, gotową do sparkline'ów. Dotyczy rozkładów tag, category, template, sending-domain, sending-IP, recipient-domain, mailbox-provider i mailbox-provider-region.

Endpointy summary i serii czasowych przyjmują też jeden filtr wymiarowy na żądanie. Wybierz category, sending_domain, sending_ip, recipient_domain, tag lub template. Filtr zawęża agregat do jednego nadawcy lub kampanii bez przechodzenia do rozkładu. Przekazanie więcej niż jednego zwraca 422.

Kondycja wysyłki

GET /v1/email/health odpowiada na pytanie, które zagregowane dane pozostawiają Tobie: czy Twoja wysyłka zmierza ku problemom. Zwraca jedną ocenę dla okna czasowego oraz sygnały dotyczące dostarczenia, otwarć, odrzuceń i skarg. Każdy sygnał zawiera swój wskaźnik i ocenę. Sygnały dostarczenia, odrzuceń i skarg zawierają też progi, na których opierają się ich oceny; wskaźnik otwarć nie ma progów ryzyka. Dzięki temu badge statusu może śledzić nasze pasma bez ich kopii wkompilowanej w Twojego klienta.

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

Dopasowuj każdy sygnał po jego metric. status najwyższego poziomu to najgorsza z ocen dostarczenia, odrzuceń i skarg: healthy, watching lub throttled. open_rate znajduje się poza tym zestawieniem, ponieważ wysoki wskaźnik otwarć nigdy nie stanowi ryzyka i jest jedynym sygnałem, który może przyjąć wartość strong.

Dwa pola sygnału łatwo pomylić. limit to referencyjna granica dostarczalności dla danego wskaźnika i wynosi null dla wskaźników, które takiej granicy nie mają. thresholds to miejsce, w którym zmienia się sama ocena: watching i throttled to dwa progi, a direction wskazuje ich ryzykowną stronę, czyli above dla wskaźników odrzuceń i skarg oraz below dla wskaźnika dostarczenia. Progi są wykluczające, więc wskaźnik dokładnie na progu zachowuje lepszy status.

Ponieważ progi wracają w odpowiedzi, możesz oceniać segmenty, których ten endpoint nie oblicza: uszereguj nadawców za pomocą /sending-domains, a następnie sklasyfikuj każdy wiersz względem progów wskaźnika odrzuceń zwróconych w odpowiedzi o kondycji. Dashboard Metrics używa osobnych pasm ostrzegawczych dla wskaźników twardych odrzuceń i skarg. Ten API ocenia zagregowane wskaźniki odrzuceń, skarg i dostarczenia, więc jego ocena może różnić się od ostrzeżenia na dashboardzie.

Ocena throttled informuje o ryzyku dostarczalności. Nie wstrzymuje wysyłki.

Okno czasowe działa inaczej niż w powyższych endpointach. from i to to dni kalendarzowe w UTC, nie ma parametru timezone i nie stosuje się filtr wymiaru. Pomiń oba, a okno zakończy się dzisiaj i zacznie 7 dni wcześniej. Maksimum to 365 dni.

Ruch testowy w liczbach

Wysyłki na adresy sandbox przechodzą przez tę samą agregację, więc ruch testowy pojawia się w każdym endpoincie dokładnie tak samo jak na dashboardzie.

Następne kroki

• Zapytania do analityki e-mail z AI: przykładowe prompty dotyczące raportów dostarczenia, aktywności i opóźnień przez MCP
• Metryki e-mail: jak dashboard prezentuje te liczby i kiedy reagować
• Dokumentacja podsumowania statystyk: każde pole, filtr i formuła wskaźnika
• Dokumentacja kondycji wysyłki: ocena, sygnały poszczególnych wskaźników i ich progi
• Zdarzenia i webhooki: strumień per odbiorca, gdy agregat nie wystarcza