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

API 基礎

BillionSend API 的基礎網址、API 金鑰權限、錯誤清單、頻率限制、冪等性金鑰與分頁。

API 參考中的各端點頁面,是由 API 的路由定義自動產生的。OpenAPI 3.1 規格與它是同一個來源,只是整合成一個 JSON 檔案。

此 API 與 Resend API 相容:路徑、請求格式與錯誤格式都相同。你可以用 BillionSend 的 SDK 呼叫,也可以直接透過 HTTP 呼叫。

基礎網址

https://api.billionsend.com

驗證

每個請求都要送出控制台的 API 金鑰頁面中的 API 金鑰:

Authorization: Bearer bs_...

缺少金鑰或格式錯誤時會回應 401 missing_api_key,金鑰不正確時回應 401 invalid_api_key。

金鑰有不同的權限等級:

  • 完整存取可以使用所有端點。
  • 僅限傳送只能寄信。/emails 以外的所有端點都會回應 403 restricted_api_key,GET /emails、GET /emails/{id}、GET /emails/metrics、DELETE /emails/{id} 與所有 /emails/receiving 端點也一樣,因為它們會回傳已儲存的內容。

金鑰也可以限制在單一網域或單一收件匣。限制在某個網域的金鑰,只能在該網域內運作:只能從它寄信、只能讀取它的信件,在 /domains 下只看得到、也只能更動它,凡是屬於整個團隊的項目(Webhook、抑制清單、範本、聯絡人屬性、/usage、/deliverability、驗證、POST /domains),都會回應 403 restricted_api_key;請見 API 金鑰。你用 API 建立的金鑰,權限永遠不會比建立它的金鑰更大。

一個團隊最多可以有 25 把啟用中的金鑰。哪些操作需要由擁有者或管理員建立的金鑰,請見團隊角色。

錯誤

每個錯誤都是這個格式:

{ "statusCode": 422, "name": "validation_error", "message": "..." }
狀態與名稱 意義
400 invalid_parameter 內文不是有效的 JSON。
401 missing_api_key / invalid_api_key 沒有金鑰,或金鑰不正確。
403 restricted_api_key 金鑰的權限或範圍不允許這項操作。
403 forbidden 你的角色或金鑰不允許這項操作。
403 plan_limit_reached 已達到你方案的限制。請見方案與限制。
403 sending_paused 因為你的退信率或投訴率過高,寄送已暫停。
404 not_found 端點或你要求的項目不存在。
409 invalid_idempotent_request 冪等性金鑰搭配了不同的內容使用。
415 內文不是 application/json。
422 validation_error 請求無效。訊息會說明原因。
422 all_recipients_suppressed 所有收件者都已被抑制或退訂。請見抑制清單。
429 rate_limit_exceeded 請求過多。
429 daily_quota_exceeded / monthly_quota_exceeded 你方案的寄送額度已用完。請見方案與限制。
503 service_unavailable 統計儲存服務沒有回應。寄送不受影響。

每個 429 都帶有 retry-after 標頭:要等待的秒數。

每個回應,不論是否為錯誤,都帶有 x-request-id 標頭:請求的 id,與控制台日誌頁面上該請求的 id 相同。向我們詢問某個請求時,請附上它。

收件者的網域永遠收不到信時,例如 x@example.com、x@foo.test 或 x@gmail.con,會被拒絕並回應 422 validation_error。在這類位址新增聯絡人也一樣。要在不寄給任何人的情況下測試,請寄到 success@simulator.amazonses.com。

收信、收件匣與 Agent 安全各有自己的錯誤,由那些頁面列出。

頻率限制

每把 API 金鑰每分鐘最多 600 個請求,一個團隊的所有金鑰合計 3,000 個。超過限制時,你會收到 429 rate_limit_exceeded 與 retry-after 標頭。同一個 IP 位址每分鐘超過 20 次驗證失敗,也會以同樣的方式被拒絕。

冪等性

POST /emails 與 POST /emails/batch 接受長度 1 到 256 個字元的 Idempotency-Key 標頭。收件匣的回覆、轉寄與草稿寄送,以及收到信件的回覆與轉寄也一樣。用相同的金鑰與相同的內容重試,你會得到原本的回應,而不會多寄一封 Email。相同的金鑰搭配不同的內容,會回應 409。

分頁

清單端點接受 limit(1 到 100,預設 20)與游標 after、before,兩者都是上一頁中的項目 id。回應中有 has_more。清單一律由新到舊排序:

  • after 帶入某一頁的最後一個 id,回傳更舊的項目。
  • before 帶入第一個 id,回傳更新的項目。

要取得最新的內容,請把你儲存的最新 id 當作 before 傳入。

少數清單使用其他排序,各自的參考頁面會註明:收件匣對話串(最近有活動的在前)、對話串中的 Email(最舊的在前),以及訂閱主題與標籤(最舊的在前,一次全部回傳)。游標沒有對應到任何項目時,會回應 422 validation_error(在 /inboxes 下則是 404)。

值得留意的規則

  • 附件只接受內嵌的 base64 content。遠端的 path URL 會回應 422。每封 Email 的附件合計最多 10 MiB,整封 Email 必須小於 40 MB。程式與指令碼(.exe、.js、.bat 等,包含 ZIP 內的檔案)一律會被拒絕。新團隊上,有些風險較高的類型,例如壓縮檔、網頁,以及啟用巨集的 Office 檔案,會被接受,但要先等待審查才會寄出。
  • 聯絡人屬於團隊。沒有 audience 這種東西:audience 端點是分群的別名。
  • 退訂屬於寄件網域。請見退訂。
  • 收件者:to、cc 與 bcc 合計最多 50 個位址,每個都必須是單一信箱。每個 to 位址都已被抑制的寄送,會回應 422 all_recipients_suppressed。
  • 標頭採用允許清單:任何 X-* 名稱(X-SES-* 與 X-BillionSend-* 除外)、串接與優先順序標頭,以及成對的 List-Unsubscribe。其他標頭會回應 422。
  • 主旨最長 998 個字元。
  • 額外的端點:GET /usage(方案、限制與用量)、DELETE /emails/{id},以及 GET /emails/metrics(數據分析)。
  • 批次聯絡人:POST /contacts/batch 一次建立、POST /contacts/batch/remove 一次刪除最多 1,000 位聯絡人。在聯絡人清單加上 include=properties,topics,會一併帶入每位聯絡人的屬性與訂閱主題。
  • 批次抑制每個請求最多處理 1,000 個位址。
  • 額外的狀態:群發可以是 canceled。
  • 收信與收件匣目前是測試版,支援長輪詢與新信件的即時事件串流。請見收信與收件匣。
  • 不支援的設定會以 422 拒絕,而不是被悄悄忽略。

簽署下載連結

收到的信件帶有原始郵件與附件的下載連結。它們是不需要 API 金鑰的一般 GET URL,有效期限一小時,過期後會回應 403。請再向 API 要一個新連結。請見收信。

这个页面有帮助吗?