跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

数据分析

事件发生几秒后即可看到送达统计,可在控制台查看,也可通过 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 许可。

相关内容

送达率洞察 为每封邮件和你的账户打分。想在结果出现时立即响应,而不是事后统计,请使用 Webhook。

这个页面有帮助吗?