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

數據分析

每個事件發生後幾秒內就能看到送達統計,可在控制台查看,也能透過 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 授權。

相關頁面

送達率洞察會為每封 Email 與你的帳號評分。想在結果發生時立即回應,而不是事後再統計,請使用 Webhook。

这个页面有帮助吗?