---
title: 数据分析
description: 事件发生几秒后即可看到送达统计，可在控制台查看，也可通过 GET /emails/metrics 读取。
seo:
  title: 邮件数据分析 API
ai:
  exclude: true
---

每一种结果（送达、退信、投诉、打开、点击、退订）在发生几秒后就会被计入统计。控制台的 **数据分析** 页面与 `GET /emails/metrics` 读取的是同一份数据。

控制台的数据分析页展示送达率、打开率、点击率、退信率和投诉率，以及按小时划分的事件图表。可以按时间范围（7、15 或 30 天）、时区、品牌（发信域名）、群发和收件人域名筛选。

统计数据按小时保存 13 个月。群发自身的历史不受 13 个月限制。统计服务没有响应时，接口返回 `503 service_unavailable`，发送不受影响。邮件列表、导出和单封邮件的事件不属于统计，参见 [日志](/docs/zh-hans/concepts/logs)。

## 查询数字

`GET /emails/metrics` 需要完全访问权限的 [API 密钥](/docs/zh-hans/api-reference/basics)。SDK 中对应的方法是 `emails.metrics()`。

```sh
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 的扩展接口，需要完全访问权限的密钥）列出范围内被点击的链接，点击最多的排在前面：

```sh
curl "https://api.billionsend.com/emails/metrics/links?start_date=2026-11-01&end_date=2026-11-14&limit=10" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "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 的扩展接口，需要完全访问权限的密钥），互动最多的排在前面：

```sh
curl "https://api.billionsend.com/emails/metrics/countries?start_date=2026-11-16&end_date=2026-11-30" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "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](https://db-ip.com)，采用 CC BY 4.0 许可。

## 相关内容

[送达率洞察](/docs/zh-hans/concepts/deliverability-insights) 为每封邮件和你的账户打分。想在结果出现时立即响应，而不是事后统计，请使用 [Webhook](/docs/zh-hans/concepts/webhooks)。
