Statistiques e-mail API

API de statistiques e-mail renvoie les agrégats affichés sur le tableau de bord Metrics, ainsi que le verdict de santé d'envoi calculé à partir de ceux-ci. Utilisez-le pour créer des tableaux de bord, exporter des données ou surveiller la santé de vos e-mails. Il nécessite une clé API avec un accès en lecture au scope emails.

Des méthodes typées sont disponibles dans les SDK TypeScript, Python, PHP et Go sous email.stats et email.health, le bird CLI les expose sous bird email stats et bird email health, et un agent y accède via les outils MCP email_stats_* et email_health. Les schémas complets de requête et de réponse se trouvent dans la référence API.

L'agrégat et la série temporelle

Trois endpoints couvrent le haut du tableau de bord :

GET /v1/email/stats/summary renvoie une seule ligne agrégée pour toute la fenêtre. Elle inclut les compteurs de cycle de vie pour les e-mails acceptés, livrés, rejetés, signalés, ouverts, cliqués, ainsi que leurs sous-types. Elle inclut également les valeurs dérivées delivery_rate, bounce_rate, complaint_rate, open_rate et click_rate. Les percentiles de latence de traitement, de livraison et totale couvrent p50, p95 et p99. Passez compare=previous_period et la réponse inclut aussi la fenêtre précédente de même durée et l'écart par rapport à celle-ci.
GET /v1/email/stats/daily et GET /v1/email/stats/hourly renvoient les mêmes compteurs à raison d'une ligne par jour ou par heure, avec des lignes à zéro pour combler les trous afin qu'un graphique ne présente jamais de lacunes.

Chaque taux est renvoyé sous forme de fraction entre 0 et 1 : un delivery_rate de 0.9939 correspond à 99,39 %. Un taux dont le dénominateur est zéro vaut null, ce qui permet à une période sans aucune livraison d'afficher open_rate au lieu de 0. Les taux utilisent le temps de l'événement pour l'attribution. Le moment de l'envoi n'influe pas sur la fenêtre dans laquelle un événement est comptabilisé : l'engagement arrivant pendant la fenêtre pour un message plus ancien est donc inclus. La formule exacte de chaque taux, y compris la façon dont un rebond hors bande tardif retire un destinataire du compteur de livraisons, est documentée champ par champ dans la référence du résumé.

Chaque réponse reprend la fenêtre sur laquelle elle a été calculée, plus data_as_of : l'instant auquel les chiffres sont à jour. L'agrégation se rafraîchit toutes les quelques secondes, la réponse est donc quasi temps réel plutôt qu'en direct. Affichez data_as_of sur votre tableau de bord plutôt que de présenter les chiffres comme étant à la seconde près.

Choisir la fenêtre

from et to acceptent soit un jour calendaire (YYYY-MM-DD), soit un instant RFC 3339, et les formes acceptées varient selon l'endpoint :

Endpoint	Bornes	Fenêtre maximale
/summary	Deux jours, ou deux instants	365 jours, ou 720 heures avec des instants
/daily	Jours calendaires	365 jours
/hourly	Instants RFC 3339	720 heures (30 jours)

Les bornes en instants sont à la granularité horaire, ce qui permet d'obtenir un "last 24 hours" glissant en une seule requête. Sur /summary, mélanger un jour et un instant renvoie une 422.

Définissez timezone avec un identifiant IANA tel que America/New_York pour que les limites de jour et d'heure, ainsi que les valeurs par défaut utilisées lorsque vous omettez from et to, soient calculées dans ce fuseau au lieu d'UTC. Tant que timezone est défini, from et to ne doivent pas inclure de décalage UTC.

Ventilations

Les 13 endpoints de ventilation découpent les mêmes chiffres de livraison et d'engagement selon une dimension :

Expéditeurs : /sending-domains, /sending-ips et /recipient-domains (le domaine de la boîte aux lettres destinataire).
Destination : /mailbox-providers (Gmail, Outlook, etc.) et /mailbox-provider-regions.
Contenu envoyé : /tags (les tags que vous définissez à l'envoi, la coupe la plus flexible), /categories, /templates et /broadcasts.
Contexte d'engagement : /locations (géographie du destinataire) et /clients (le client de messagerie qui a rendu l'ouverture).
Échecs : /bounce-codes (groupés par réponse du serveur destinataire) et /complaint-types.

Tous se trouvent sous /v1/email/stats/. Les lignes sont renvoyées triées par ordre décroissant selon une métrique sort et limitées à limit (50 par défaut, 200 maximum). La réponse inclut également total, le nombre de valeurs distinctes de la dimension dans la fenêtre. Comparez total au nombre de lignes renvoyées pour détecter un résultat tronqué. Les lignes dont la métrique de tri est un taux à dénominateur zéro apparaissent en dernier.

La valeur par défaut de sort de chaque endpoint est la métrique pour laquelle il est conçu :

Par défaut	Ventilations
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 ajoute une série de taux par intervalle à chaque ligne, prête pour des sparklines. Elle s'applique aux ventilations par tag, catégorie, template, domaine d'envoi, IP d'envoi, domaine destinataire, fournisseur de boîte aux lettres et région du fournisseur de boîte aux lettres.

Les endpoints de résumé et de série temporelle acceptent également un filtre par dimension et par requête. Choisissez category, sending_domain, sending_ip, recipient_domain, tag ou template. Le filtre restreint un agrégat à un expéditeur ou une campagne sans passer par une ventilation. Passer plus d'un filtre renvoie une 422.

Santé d'envoi

GET /v1/email/health répond à la question que les agrégats vous laissent résoudre : si votre envoi se dirige vers des problèmes. Il renvoie un verdict pour la fenêtre ainsi que des signaux pour la livraison, les ouvertures, les rebonds et les plaintes. Chaque signal porte son taux et son verdict. Les signaux de livraison, de rebond et de plainte portent aussi les seuils qui déterminent leurs verdicts ; le taux d'ouverture n'a pas de seuils de risque. C'est ce qui permet à un badge de statut de suivre nos bandes sans en avoir une copie compilée dans votre propre client.

Exemple de code

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

Faites correspondre chaque signal sur son metric. Le status de niveau supérieur est le pire des verdicts de livraison, de rebond et de plainte : healthy, watching ou throttled. open_rate se situe en dehors de ce calcul, car un taux d'ouverture élevé n'est jamais un risque, et c'est le seul signal qui peut afficher strong.

Deux champs d'un signal sont faciles à confondre. limit est la limite de délivrabilité de référence pour le taux, et sa valeur est null pour les taux qui n'en ont pas. thresholds indique où le verdict lui-même change : watching et throttled sont les deux seuils, et direction nomme le côté risqué, above pour les taux de rebond et de plainte et below pour le taux de livraison. Les seuils sont exclusifs : un taux situé exactement sur l'un d'eux conserve le meilleur statut.

Comme les seuils sont renvoyés dans la réponse, vous pouvez évaluer des segments que cet endpoint ne calcule pas : classez vos expéditeurs avec /sending-domains, puis comparez chaque ligne aux seuils de taux de rebond renvoyés par la réponse de santé. Le tableau de bord Metrics utilise des bandes d'avertissement distinctes pour les taux de hard-bounce et de plainte. Cet API évalue les taux agrégés de rebond, de plainte et de livraison, donc son verdict peut différer d'un avertissement du tableau de bord.

Un verdict throttled signale un risque de délivrabilité. Il ne suspend pas votre envoi.

La fenêtre fonctionne différemment des endpoints ci-dessus. from et to sont des jours calendaires en UTC, il n'y a pas de paramètre timezone, et aucun filtre de dimension ne s'applique. Si vous omettez les deux, la fenêtre se termine aujourd'hui et commence 7 jours plus tôt. Le maximum est de 365 jours.

Trafic de test dans les chiffres

Les envois vers des adresses sandbox passent par la même agrégation : le trafic de test apparaît donc dans chaque endpoint ici exactement comme sur le tableau de bord.

Étapes suivantes

Métriques e-mail : comment le tableau de bord présente ces chiffres et quand agir
Référence du résumé des statistiques : chaque champ, filtre et formule de taux
Référence de la santé d'envoi : le verdict, ses signaux par taux et leurs seuils
Événements et webhooks : le flux par destinataire quand un agrégat ne suffit pas

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideGetting started with email Explorer la fonctionnalitéEmail Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Essayez la pratique et obtenez un guide d'implémentation