E-mailstatistieken API

De e-mailstatistieken-API retourneert de aggregaten die op het Metrics-dashboard worden getoond, plus het verzondgezondheid-oordeel dat daaruit wordt berekend. Gebruik het om dashboards te bouwen, data te exporteren of de e-mailgezondheid te bewaken. Je hebt een API-sleutel nodig met leestoegang tot het emails-bereik.

Getypeerde methoden zitten in de TypeScript-, Python-, PHP- en Go-SDK's onder email.stats en email.health, de bird CLI toont ze als bird email stats en bird email health, en een agent bereikt ze via de email_stats_*- en email_health-MCP-tools. Volledige request- en responseschema's staan in de API-referentie.

Het aggregaat en de tijdreeks

Drie endpoints dekken het bovenste deel van het dashboard:

GET /v1/email/stats/summary retourneert één aggregaatrij voor het hele venster. Het bevat lifecyclusaantallen voor accepted, delivered, bounced, complained, opened, clicked en hun subtypes. Het bevat ook de afgeleide delivery_rate, bounce_rate, complaint_rate, open_rate en click_rate. Verwerkings-, afleverings- en totale latentiepercentilen dekken p50, p95 en p99. Geef compare=previous_period mee en de response bevat ook het voorafgaande venster van gelijke lengte en de verandering ten opzichte daarvan.
GET /v1/email/stats/daily en GET /v1/email/stats/hourly retourneren dezelfde aantallen met één rij per dag of per uur, opgevuld met nulrijen zodat een grafiek nooit gaten vertoont.

Elk percentage komt terug als een breuk tussen 0 en 1, dus een delivery_rate van 0.9939 is 99,39%. Een percentage waarvan de noemer nul is, is null. Zo rapporteert een periode zonder afleveringen open_rate in plaats van 0. Percentages gebruiken eventtijd voor toewijzing. Verzendtijd bepaalt niet in welk venster een event valt, dus engagement dat tijdens het venster binnenkomt voor een ouder bericht wordt meegenomen. De exacte formule achter elk percentage, inclusief hoe een late out-of-band bounce een ontvanger uit het afleveringsaantal haalt, is per veld gedocumenteerd op de samenvattingsreferentie.

Elke response bevat het venster waartegen is berekend, plus data_as_of: het moment tot waarop de cijfers actueel zijn. De aggregatie ververst elke paar seconden, dus een response is near-real-time in plaats van live. Label je eigen dashboard met data_as_of in plaats van de cijfers als sekundenauwkeurig te presenteren.

Het venster kiezen

from en to accepteren een kalenderdag (YYYY-MM-DD) of een RFC 3339-tijdstip, en welke vormen een endpoint accepteert verschilt:

Endpoint	Grenzen	Maximaal venster
/summary	Beide dagen, of beide tijdstippen	365 dagen, of 720 uur bij tijdstippen
/daily	Kalenderdagen	365 dagen
/hourly	RFC 3339-tijdstippen	720 uur (30 dagen)

Tijdstipgrenzen zijn op uurniveau, waardoor een rollende "last 24 hours" één enkel request is. Bij /summary levert het combineren van een dag met een tijdstip een 422 op.

Stel timezone in op een IANA-identifier zoals America/New_York om dag- en uurgrenzen, en de standaardwaarden die worden gebruikt als je from en to weglaat, in die tijdzone te berekenen in plaats van UTC. Zolang timezone is ingesteld, mogen from en to geen eigen UTC-offset bevatten.

Uitsplitsingen

De 13 uitsplitsingsendpoints verdelen dezelfde afleverings- en engagementcijfers over één dimensie:

Afzenders: /sending-domains, /sending-ips en /recipient-domains (het mailboxdomein waarnaar je hebt verzonden).
Waar het terechtkwam: /mailbox-providers (Gmail, Outlook enzovoort) en /mailbox-provider-regions.
Wat je hebt verzonden: /tags (de tags die je bij verzending instelt, de meest flexibele doorsnede), /categories, /templates en /broadcasts.
Engagementcontext: /locations (geografie van de ontvanger) en /clients (de mailclient die de open heeft weergegeven).
Fouten: /bounce-codes (gegroepeerd op de respons van de ontvangende server) en /complaint-types.

Ze vallen allemaal onder /v1/email/stats/. Rijen komen terug in aflopende volgorde op een sort-metric en zijn begrensd op limit (standaard 50, maximum 200). De response bevat ook total, het aantal unieke dimensiewaarden in het venster. Vergelijk total met het aantal geretourneerde rijen om een begrensd resultaat te herkennen. Rijen waarvan de sorteermetric een percentage met een nulnoemer is, komen onderaan.

De standaard van sort per endpoint is de metric waarvoor het endpoint bedoeld is om op te rangschikken:

Standaard	Uitsplitsingen
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 voegt een percentagereeks per bucket toe aan elke rij, klaar voor sparklines. Het is van toepassing op de uitsplitsingen tag, category, template, sending-domain, sending-IP, recipient-domain, mailbox-provider en mailbox-provider-region.

De samenvatting- en tijdreeksendpoints accepteren ook één dimensie-filter per request. Kies category, sending_domain, sending_ip, recipient_domain, tag of template. Het filter beperkt een aggregaat tot één afzender of campagne zonder over te schakelen naar een uitsplitsing. Meer dan één meegeven retourneert een 422.

Verzondgezondheid

GET /v1/email/health beantwoordt de vraag die de aggregaten aan jou overlaten: of je verzending op problemen afstevent. Het retourneert één oordeel voor het venster, plus signalen voor aflevering, opens, bounces en klachten. Elk signaal bevat zijn percentage en oordeel. Signalen voor aflevering, bounce en klacht bevatten ook de grenzen die hun oordeel bepalen; het openpercentage heeft geen risicogrenzen. Daardoor kan een statusbadge onze banden volgen zonder dat je er een kopie van in je eigen client hoeft in te bouwen.

Codevoorbeeld

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

Vergelijk elk signaal op zijn metric. Het status op het hoogste niveau is het slechtste van de oordelen voor aflevering, bounce en klacht: healthy, watching of throttled. open_rate valt buiten die samenvoeging, omdat een hoog openpercentage nooit een risico is, en het is het enige signaal dat strong kan bevatten.

Twee velden op een signaal zijn makkelijk te verwarren. limit is de referentielimiet voor afleveringspercentage, en het is null bij percentages die er geen hebben. thresholds is waar het oordeel zelf verandert: watching en throttled zijn de twee grenzen, en direction benoemt de risicovolle kant ervan, above voor bounce- en klachtpercentages en below voor het afleveringspercentage. De grenzen zijn exclusief, dus een percentage dat precies op een grens valt, behoudt de betere status.

Omdat de grenzen in de response meekomen, kun je segmenten beoordelen die dit endpoint niet berekent: rangschik je afzenders met /sending-domains en classificeer elke rij tegen de bouncepercentage-grenzen die de gezondheidsresponse retourneerde. Het Metrics-dashboard gebruikt aparte waarschuwingsbanden voor hard-bounce- en klachtpercentages. Dit API evalueert de totale bounce-, klacht- en afleveringspercentages, dus het oordeel kan afwijken van een dashboardwaarschuwing.

Een throttled-oordeel rapporteert afleveringsrisico. Het pauzeert je verzending niet.

Het venster werkt anders dan bij de bovenstaande endpoints. from en to zijn kalenderdagen in UTC, er is geen timezone-parameter en er geldt geen dimensiefilter. Laat je beide weg, dan eindigt het venster vandaag en begint het 7 dagen eerder. Het maximum is 365 dagen.

Testverkeer in de cijfers

Verzendingen naar sandbox-adressen doorlopen dezelfde aggregatie, dus testverkeer verschijnt in elk endpoint hier precies zoals op het dashboard.

Volgende stappen

E-mailstatistieken: hoe het dashboard deze cijfers presenteert en wanneer je actie moet ondernemen
Stats-samenvattingsreferentie: elk veld, filter en percentageformule
Verzondgezondheid-referentie: het oordeel, de signalen per percentage en hun grenzen
Events en webhooks: de stroom per ontvanger wanneer een aggregaat niet volstaat

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsGetting started with email Ontdek de mogelijkheidEmail Volg het leerpadBuild your first integration ImplementatiegidsSend your first email

Probeer de oefening en ontvang een implementatieoverzicht