邮件统计 API
邮件统计 API 返回 Metrics 仪表盘上显示的聚合数据。你可以用它构建仪表盘、导出数据或监控邮件健康状况。它们需要一个对 emails 作用域有读取权限的 API 密钥。
类型化方法包含在 TypeScript、Python 和 Go SDK 的 email.stats 下，bird CLI 将它们暴露为 bird email stats，智能体可以通过 email_stats_* MCP tools 访问。完整的请求和响应模式见 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。
统计数据中的测试流量
发送到沙盒地址的邮件经过相同的聚合流程，因此测试流量会出现在此处的每个端点中，与仪表盘上的表现完全一致。
后续步骤
- 邮件指标：仪表盘如何展示这些数据，以及何时需要采取行动
- 统计汇总参考文档：所有字段、筛选条件和比率公式
- 事件与 Webhook：当聚合数据不够用时，可使用逐收件人的事件流