數據分析
每個事件發生後幾秒內就能看到送達統計,可在控制台查看,也能透過 GET /emails/metrics 取得。
每一種結果(送達、退信、投訴、開信、點擊、退訂)在發生幾秒後就會被計入。控制台的數據分析頁面與 GET /emails/metrics 讀取的是同一份數字。
在控制台裡,數據分析會顯示送達率、開信率、點擊率、退信率、投訴率,以及依小時統計的事件圖表。可依時間範圍(7、15 或 30 天)、時區、品牌(寄件網域)、群發與收件者網域篩選。
統計資料依小時保存 13 個月。群發本身的歷史不受 13 個月限制。統計服務沒有回應時,端點會回傳 503 service_unavailable,寄信不受影響。Email 清單、匯出,以及單封 Email 的事件不屬於統計,請見日誌。
查詢數字
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 |
已接受等待寄送的收件者。它不屬於任何網域、群發或 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 的擴充端點,需要完整權限的金鑰)會列出範圍內被點擊的連結,點擊最多的排在最前面:
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是讀信者 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 提供,採用 CC BY 4.0 授權。