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。遠端的pathURL 會回應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 要一個新連結。請見收信。