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. Les requêtes nécessitent un accès en lecture au scope emails.

Pour des rapports avec des filtres combinés, des métriques sélectionnées et des séries temporelles complètes par groupe, utilisez l'endpoint de requête flexible. Pour explorer ces rapports via un assistant, consultez Interroger les analytics e-mail avec l'IA.

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.

Les taux sont renvoyés sous forme de fractions : 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. Les taux d'ouverture et de clic peuvent dépasser 1 lorsque l'engagement et la livraison tombent dans des fenêtres différentes. La formule exacte de chaque taux, y compris la façon dont un rebond hors bande tardif modifie les livraisons effectives, est documentée champ par champ dans la référence du résumé.

Les réponses de résumé, journalières et horaires reprennent la fenêtre et incluent data_as_of, le dernier rafraîchissement d'agrégat réussi lorsqu'il est disponible. Cette valeur peut être null, et un horodatage ne garantit pas que tous les événements sont arrivés. L'endpoint de requête flexible renvoie toujours data_as_of: null. Affichez un horodatage de rafraîchissement disponible sur votre tableau de bord sans le présenter comme preuve de données complètes.

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 :

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 :

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.

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

• Interroger les analytics e-mail avec l'IA : exemples de prompts pour des rapports de livraison, d'engagement et de latence via MCP
• 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