Sign inGet Started

邮件统计 API

邮件统计 API 返回 Metrics 仪表盘上展示的聚合数据,以及据此计算的发送健康度判定。你可以用它构建仪表盘、导出数据或监控邮件健康状况。它们需要一个对 emails 作用域有读权限的 API 密钥。
类型化方法包含在 TypeScriptPythonPHPGo SDK 的 email.statsemail.health 下;bird CLI 将其暴露为 bird email statsbird email health;智能体则通过 email_stats_*email_health MCP 工具访问它们。完整的请求和响应模式见 API 参考文档

聚合与时间序列

三个端点覆盖仪表盘的顶部:
  • GET /v1/email/stats/summary 返回整个窗口的一行聚合数据。它包含 accepted、delivered、bounced、complained、opened、clicked 及其子类型的生命周期计数,还包含派生的 delivery_ratebounce_ratecomplaint_rateopen_rateclick_rate。处理、投递和总延迟的百分位数涵盖 p50、p95 和 p99。传入 compare=previous_period,响应还会包含前一个等长窗口及其变化量。
  • GET /v1/email/stats/dailyGET /v1/email/stats/hourly 返回相同的计数,每天或每小时一行,空缺时段用零值行填充,确保图表没有断点。
所有比率以 0 到 1 之间的小数 返回,因此 delivery_rate0.9939 表示 99.39%。分母为零的比率返回 null,这样一个没有投递记录的时段会报告 open_rate 而不是显示为 0。比率使用事件时间来归因。发送时间不影响事件归入哪个窗口,因此在窗口期间到达的、属于更早消息的互动数据也会被计入。每个比率的精确公式,包括延迟的带外退信如何将收件人从已投递计数中移除,均按字段记录在汇总参考文档中。
每个响应都会回显其计算所用的窗口,以及 data_as_of:数据截至的时刻。聚合每隔几秒刷新一次,因此响应是近实时而非实时的。在你自己的仪表盘上显示 data_as_of,而不是将数字表示为精确到秒。

选择窗口

fromto 接受日历日期(YYYY-MM-DD)或 RFC 3339 时刻,各端点接受的形式不同:
端点边界最大窗口
/summary两端均为日期,或两端均为时刻365 天,或时刻模式下 720 小时
/daily日历日期365 天
/hourlyRFC 3339 时刻720 小时(30 天)
时刻边界精确到小时,这使得滚动 "last 24 hours" 只需一次请求。在 /summary 上,将日期和时刻混用会返回 422
timezone 设置为 IANA 标识符(如 America/New_York),日和小时的边界以及省略 fromto 时使用的默认值将按该时区而非 UTC 计算。设置了 timezone 时,fromto 不得包含自己的 UTC 偏移量。

分组维度

13 个分组端点按单一维度切分相同的投递和互动数据:
  • 发件方/sending-domains/sending-ips/recipient-domains(你发送到的邮箱域名)。
  • 投递位置/mailbox-providers(Gmail、Outlook 等)和 /mailbox-provider-regions
  • 发送内容/tags(你在发送时设置的标签,最灵活的切分方式)、/categories/templates/broadcasts
  • 互动上下文/locations(收件人地理位置)和 /clients(渲染打开事件的邮件客户端)。
  • 失败/bounce-codes(按接收服务器的响应分组)和 /complaint-types
它们都位于 /v1/email/stats/ 下。行按 sort 指标降序排列,数量上限为 limit(默认 50,最大 200)。响应还包含 total,即窗口内不同维度值的数量。将 total 与返回的行数进行比较,即可判断结果是否被截断。排序指标为分母为零的比率的行排在最后。
每个端点的 sort 默认值是该端点用来排序的指标:
默认值分组维度
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 为每行添加按桶划分的比率序列,可直接用于迷你图。它适用于 tag、category、template、sending-domain、sending-IP、recipient-domain、mailbox-provider 和 mailbox-provider-region 分组。
汇总和时间序列端点还支持每次请求传入一个维度筛选条件。可选 categorysending_domainsending_iprecipient_domaintagtemplate。筛选条件将聚合范围限定到单个发件方或活动,无需切换到分组视图。传入多个筛选条件会返回 422

发送健康度

GET /v1/email/health 回答聚合数据留给你的问题:你的发送是否正在走向麻烦。它返回整个窗口的一个判定,加上投递、打开、退信和投诉的信号。每个信号包含其比率和判定。投递、退信和投诉信号还包含决定其判定的阈值边界;打开率没有风险边界。正因如此,状态徽标可以跟随我们的区间变化,无需在你自己的客户端中硬编码一份副本。
代码示例
{
  "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
      }
    }
  ]
}
根据每个信号的 metric 进行匹配。顶层 status 取投递、退信和投诉判定中最差的一个:healthywatchingthrottledopen_rate 不参与该汇总,因为高打开率不构成风险,而且它是唯一能读取 strong 的信号。
信号上有两个字段容易混淆。limit 是该比率的参考可送达性限制,对于没有此限制的比率,它是 nullthresholds 是判定本身发生变化的位置:watchingthrottled 是两个边界,direction 指明它们的风险侧,退信率和投诉率为 above,投递率为 below。边界是排他的,因此比率恰好落在边界上时保持较好的状态。
由于边界随响应一起返回,你可以对该端点未计算的切片进行评级:用 /sending-domains 对你的发件人排名,然后将每一行与健康度响应返回的退信率边界进行对比分类。Metrics 仪表盘对硬退信率和投诉率使用各自独立的警告区间。此 API 评估的是聚合退信率、投诉率和投递率,因此其判定可能与仪表盘警告不同。
throttled 判定报告的是可送达性风险,不会暂停你的发送。
窗口的工作方式与上面的端点不同。fromto 是 UTC 日历日,没有 timezone 参数,也不支持维度过滤。两者都省略时,窗口以当天为终点,起点为 7 天前。最大窗口为 365 天。

统计数据中的测试流量

发送到沙盒地址的邮件经过相同的聚合处理,因此测试流量出现在这里每个端点中的方式与仪表盘上完全一致。

后续步骤