邮件统计 API
邮件统计 API 返回 Metrics 仪表盘上展示的聚合数据，以及据此计算的发送健康度判定。你可以用它构建仪表盘、导出数据或监控邮件健康状况。它们需要一个对 emails 作用域有读权限的 API 密钥。
类型化方法包含在 TypeScript、Python、PHP 和 Go SDK 的 email.stats 与 email.health 下；bird CLI 将其暴露为 bird email stats 和 bird email health；智能体则通过 email_stats_* 和 email_health MCP 工具访问它们。完整的请求和响应模式见 API 参考文档。
聚合与时间序列
三个端点覆盖仪表盘的顶部：
- GET /v1/email/stats/summary 返回整个窗口的一行聚合数据。它包含 accepted、delivered、bounced、complained、opened、clicked 及其子类型的生命周期计数，还包含派生的 delivery_rate、bounce_rate、complaint_rate、open_rate 和 click_rate。处理、投递和总延迟的百分位数涵盖 p50、p95 和 p99。传入 compare=previous_period，响应还会包含前一个等长窗口及其变化量。
- GET /v1/email/stats/daily 和 GET /v1/email/stats/hourly 返回相同的计数，每天或每小时一行，空缺时段用零值行填充，确保图表没有断点。
所有比率以 0 到 1 之间的小数 返回，因此 delivery_rate 为 0.9939 表示 99.39%。分母为零的比率返回 null，这样一个没有投递记录的时段会报告 open_rate 而不是显示为 0。比率使用事件时间来归因。发送时间不影响事件归入哪个窗口，因此在窗口期间到达的、属于更早消息的互动数据也会被计入。每个比率的精确公式，包括延迟的带外退信如何将收件人从已投递计数中移除，均按字段记录在汇总参考文档中。
每个响应都会回显其计算所用的窗口，以及 data_as_of：数据截至的时刻。聚合每隔几秒刷新一次，因此响应是近实时而非实时的。在你自己的仪表盘上显示 data_as_of，而不是将数字表示为精确到秒。
选择窗口
from 和 to 接受日历日期（YYYY-MM-DD）或 RFC 3339 时刻，各端点接受的形式不同：
| 端点 | 边界 | 最大窗口 |
|---|---|---|
| /summary | 两端均为日期，或两端均为时刻 | 365 天，或时刻模式下 720 小时 |
| /daily | 日历日期 | 365 天 |
| /hourly | RFC 3339 时刻 | 720 小时（30 天） |
时刻边界精确到小时，这使得滚动 "last 24 hours" 只需一次请求。在 /summary 上，将日期和时刻混用会返回 422。
将 timezone 设置为 IANA 标识符（如 America/New_York），日和小时的边界以及省略 from 和 to 时使用的默认值将按该时区而非 UTC 计算。设置了 timezone 时，from 和 to 不得包含自己的 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 分组。
汇总和时间序列端点还支持每次请求传入一个维度筛选条件。可选 category、sending_domain、sending_ip、recipient_domain、tag 或 template。筛选条件将聚合范围限定到单个发件方或活动，无需切换到分组视图。传入多个筛选条件会返回 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 取投递、退信和投诉判定中最差的一个：healthy、watching 或 throttled。open_rate 不参与该汇总，因为高打开率不构成风险，而且它是唯一能读取 strong 的信号。
信号上有两个字段容易混淆。limit 是该比率的参考可送达性限制，对于没有此限制的比率，它是 null。thresholds 是判定本身发生变化的位置：watching 和 throttled 是两个边界，direction 指明它们的风险侧，退信率和投诉率为 above，投递率为 below。边界是排他的，因此比率恰好落在边界上时保持较好的状态。
由于边界随响应一起返回，你可以对该端点未计算的切片进行评级：用 /sending-domains 对你的发件人排名，然后将每一行与健康度响应返回的退信率边界进行对比分类。Metrics 仪表盘对硬退信率和投诉率使用各自独立的警告区间。此 API 评估的是聚合退信率、投诉率和投递率，因此其判定可能与仪表盘警告不同。
throttled 判定报告的是可送达性风险，不会暂停你的发送。
窗口的工作方式与上面的端点不同。from 和 to 是 UTC 日历日，没有 timezone 参数，也不支持维度过滤。两者都省略时，窗口以当天为终点，起点为 7 天前。最大窗口为 365 天。
统计数据中的测试流量
发送到沙盒地址的邮件经过相同的聚合处理，因此测试流量出现在这里每个端点中的方式与仪表盘上完全一致。
后续步骤
- 邮件指标：仪表盘如何展示这些数据，以及何时采取行动
- 统计汇总参考文档：所有字段、过滤器和比率公式
- 发送健康度参考文档：判定、各比率信号及其边界
- 事件与 Webhook：当聚合数据不够用时的逐收件人事件流