数据分析
事件发生几秒后即可看到送达统计,可在控制台查看,也可通过 GET /emails/metrics 读取。
每一种结果(送达、退信、投诉、打开、点击、退订)在发生几秒后就会被计入统计。控制台的 数据分析 页面与 GET /emails/metrics 读取的是同一份数据。
控制台的数据分析页展示送达率、打开率、点击率、退信率和投诉率,以及按小时划分的事件图表。可以按时间范围(7、15 或 30 天)、时区、品牌(发信域名)、群发和收件人域名筛选。
统计数据按小时保存 13 个月。群发自身的历史不受 13 个月限制。统计服务没有响应时,接口返回 503 service_unavailable,发送不受影响。邮件列表、导出和单封邮件的事件不属于统计,参见 日志。
查询数字
GET /emails/metrics 需要完全访问权限的 API 密钥。SDK 中对应的方法是 emails.metrics()。
curl "https://api.billionsend.com/emails/metrics?start_date=2026-11-01&end_date=2026-11-14&granularity=daily&metrics=sent&metrics=delivered&metrics=open_rate&dimensions=period" \
-H "Authorization: Bearer bs_..."
| 参数 | 作用 |
|---|---|
start_date、end_date |
查询范围。统计按完整的 UTC 小时读取,返回结果会显示实际使用的起点。 |
timezone |
IANA 时区名,例如 Europe/Berlin(不接受 +05:00 这样的 UTC 偏移)。时间段按该时区切分。 |
granularity |
hourly、daily、weekly 或 monthly:dimensions 包含 period 时,每个时间段的大小。一个范围最多可跨 10,000 个时间段。 |
metrics |
每个想要的指标重复传一次(见下文)。 |
dimensions |
每个拆分维度重复传一次:period、domain、email 或 broadcast。email 和 broadcast 不能同时使用。 |
domain_id、email_id、broadcast_id |
筛选条件。每个最多重复 100 次。 |
响应中的 totals 是整个范围的合计;指定了维度时,data 里每个组合对应一行。
指标
| 指标 | 统计内容 |
|---|---|
received |
已接受发送的收件人。它不属于任何域名、群发或邮件,所以按其中任何一项筛选或拆分时,结果不包含它。 |
sent、delivered、delivery_delayed、failed、suppressed |
按发送结果统计的收件人。 |
bounced、bounced_permanent、bounced_transient、bounced_undetermined |
退信,以及退信的三个类别。 |
complained、unsubscribed |
垃圾邮件投诉,以及通过退订链接离开的收件人。 |
opened、clicked |
每一次打开和点击。 |
unique_opened、unique_clicked |
至少被打开或点击过一次的邮件。 |
delivery_rate |
delivered ÷ sent |
bounce_rate |
bounced ÷ sent |
open_rate、click_rate |
unique_opened 或 unique_clicked ÷ delivered |
complaint_rate、unsubscribe_rate |
complained 或 unsubscribed ÷ delivered |
比率以百分数表示,保留一位小数;除数为零时为 0。机器产生的打开和点击(例如隐私代理和安全扫描器)不计为打开或点击。
使用 email 维度且没有传 email_id 时,结果最多列出该范围内创建的 1,000 封邮件。
按链接统计点击
GET /emails/metrics/links(BillionSend 的扩展接口,需要完全访问权限的密钥)列出范围内被点击的链接,点击最多的排在前面:
curl "https://api.billionsend.com/emails/metrics/links?start_date=2026-11-01&end_date=2026-11-14&limit=10" \
-H "Authorization: Bearer bs_..."
{
"object": "list",
"start_date": "2026-11-01T00:00:00.000Z",
"end_date": "2026-11-14T23:59:59.999Z",
"has_more": false,
"data": [
{ "link": "https://shop.example.com/sale", "clicked": 412, "bot_clicked": 37 }
]
}
- 链接按协议、主机和路径计数,查询字符串和片段不计入。因此为每个收件人单独生成的链接只算一行,也不会保存任何收件人的信息。
clicked统计真人点击,bot_clicked统计机器(例如安全扫描器和链接预览)的访问。- 支持
start_date、end_date、domain_id、broadcast_id(用逗号分隔)和limit(1 到 100,默认 20),与GET /emails/metrics一样按完整的 UTC 小时统计。按链接统计的点击从 2026 年 11 月 16 日开始。
按国家和邮件客户端统计打开与点击
GET /emails/metrics/countries 按来源国家列出真人的打开和点击,GET /emails/metrics/clients 按加载图片的邮件客户端列出打开(两者都是 BillionSend 的扩展接口,需要完全访问权限的密钥),互动最多的排在前面:
curl "https://api.billionsend.com/emails/metrics/countries?start_date=2026-11-16&end_date=2026-11-30" \
-H "Authorization: Bearer bs_..."
{
"object": "list",
"start_date": "2026-11-16T00:00:00.000Z",
"end_date": "2026-11-30T23:59:59.999Z",
"has_more": false,
"data": [
{ "country": "BR", "opened": 1840, "unique_opened": 1203, "bot_opened": 95, "clicked": 311, "unique_clicked": 240, "bot_clicked": 22 },
{ "country": "unknown", "opened": 960, "unique_opened": 702, "bot_opened": 410, "clicked": 12, "unique_clicked": 9, "bot_clicked": 3 }
]
}
country是读者所用地址注册国家的 ISO 3166-1 alpha-2 代码。无法确定地址归属时为unknown;通过 Gmail 和 Yahoo 的图片代理或 Apple Mail 邮件隐私保护产生的打开也是unknown,因为这些请求来自服务商的地址,而不是读者的地址。client的取值为gmail、apple_mail、outlook、yahoo、thunderbird、other(网页浏览器:网页邮箱和不声明自身身份的客户端看起来一样)或unknown(没有 user agent)。点击不按客户端统计,因为点击来自邮件客户端把链接交给的浏览器。- 统计中只保存国家和客户端,从不保存地址或 user agent。
unique_opened和unique_clicked统计首次打开或点击来自该国家或客户端的邮件。真人和机器分开计数,与GET /emails/metrics一致。- 两个接口都支持
start_date、end_date、domain_id和broadcast_id(用逗号分隔),按完整的 UTC 小时统计,并返回全部行(国家和客户端的数量有限)。按国家和客户端统计的打开与点击从 2026 年 11 月 16 日开始。 - IP 地理定位数据来自 DB-IP,采用 CC BY 4.0 许可。