---
title: 數據分析
description: 每個事件發生後幾秒內就能看到送達統計，可在控制台查看，也能透過 GET /emails/metrics 取得。
seo:
  title: Email 數據分析 API
ai:
  exclude: true
---

每一種結果（送達、退信、投訴、開信、點擊、退訂）在發生幾秒後就會被計入。控制台的**數據分析**頁面與 `GET /emails/metrics` 讀取的是同一份數字。

在控制台裡，數據分析會顯示送達率、開信率、點擊率、退信率、投訴率，以及依小時統計的事件圖表。可依時間範圍（7、15 或 30 天）、時區、品牌（寄件網域）、群發與收件者網域篩選。

統計資料依小時保存 13 個月。群發本身的歷史不受 13 個月限制。統計服務沒有回應時，端點會回傳 `503 service_unavailable`，寄信不受影響。Email 清單、匯出，以及單封 Email 的事件不屬於統計，請見[日誌](/docs/zh-hant/concepts/logs)。

## 查詢數字

`GET /emails/metrics` 需要具備完整權限的 [API 金鑰](/docs/zh-hant/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` | 已接受等待寄送的收件者。它不屬於任何網域、群發或 Email，因此依其中任一項篩選或拆分時，回應不含這個指標。 |
| `sent`、`delivered`、`delivery_delayed`、`failed`、`suppressed` | 依寄送結果統計的收件者。 |
| `bounced`、`bounced_permanent`、`bounced_transient`、`bounced_undetermined` | 退信，以及退信的三種類別。 |
| `complained`、`unsubscribed` | 垃圾郵件投訴，以及透過退訂連結離開的收件者。 |
| `opened`、`clicked` | 每一次開信與點擊。 |
| `unique_opened`、`unique_clicked` | 至少被開啟或點擊過一次的 Email。 |
| `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 封 Email。

## 依連結統計點擊

`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` 是讀信者 IP 位址登記所在國家的 ISO 3166-1 alpha-2 代碼。無法判定位址所屬國家時為 `unknown`；透過 Gmail、Yahoo 的圖片代理，或 Apple Mail Privacy Protection 的開信也是 `unknown`，因為這些請求來自服務商的位址，而不是讀信者的位址。
- `client` 是 `gmail`、`apple_mail`、`outlook`、`yahoo`、`thunderbird`、`other`（網頁瀏覽器：網頁信箱和不表明身分的用戶端看起來都一樣）或 `unknown`（沒有 User-Agent）之一。點擊不依用戶端統計，因為點擊是由郵件用戶端交出連結後的瀏覽器發出的。
- 統計只保留國家與用戶端，不保留位址或 User-Agent。
- `unique_opened` 與 `unique_clicked` 計算的是首次開信或點擊來自該國家或用戶端的 Email。真人與機器分開計算，做法與 `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-hant/concepts/deliverability-insights)會為每封 Email 與你的帳號評分。想在結果發生時立即回應，而不是事後再統計，請使用 [Webhook](/docs/zh-hant/concepts/webhooks)。
