API 金鑰
建立完整存取或僅限傳送權限的 API 金鑰,把金鑰限定到某個網域或收件匣,並管理這些金鑰。
API 金鑰是你的程式碼在每次請求中附帶的憑證。在控制台的 API 金鑰下建立,也可以透過 API 本身建立。金鑰只會在建立時顯示一次,請存放到你的機密管理工具裡。
curl https://api.billionsend.com/emails \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"from": "hello@example.com",
"to": "success@simulator.amazonses.com",
"subject": "Hi",
"text": "Hello."
}'
金鑰以 bs_ 開頭。BillionSend 只儲存金鑰的雜湊值,所以遺失的金鑰無法再次顯示:請撤銷它,再建立一把新的。
建立金鑰
在控制台開啟 API 金鑰,選擇建立 API 金鑰。擁有者、管理員與開發者都可以建立,見團隊角色。需要選擇:
- 名稱:1 到 80 個字元,用來區分不同的金鑰。之後可以重新命名。
- 權限:完整存取或僅限傳送。
- 網域:任何網域,或你團隊的某一個已驗證網域。
- 限制在某個收件匣(有收件匣之後才會顯示):金鑰所限定的那一個收件匣。
透過 API 建立:
curl -X POST "https://api.billionsend.com/api-keys" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production",
"permission": "sending_access",
"domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
}'
回傳值是 { "id": "…", "token": "bs_…" }:權杖只會在這裡出現一次。GET /api-keys 會列出有效的金鑰(不含權杖),DELETE /api-keys/{id} 會立即撤銷一把金鑰,使用它的請求會馬上失敗。
權限
| 權限 | 可以做什麼 |
|---|---|
| 完整存取 | 使用所有端點:傳送、聯絡人、分群、訂閱主題、群發、網域、Webhook、範本、收到的郵件與 API 金鑰。限定到某個網域的金鑰只能存取其中一部分。 |
| 僅限傳送 | 只能傳送郵件(POST /emails、POST /emails/batch),其他什麼都不能做。傳送之外的所有操作,以及對已儲存郵件的所有讀取,都會回覆 403 restricted_api_key。 |
在傳送交易郵件的應用程式裡,請使用僅限傳送的金鑰。即使僅限傳送的金鑰外洩,也無法讀取你的聯絡人、修改你的網域或建立其他金鑰。
把金鑰限定到某個網域
限定到某個網域的金鑰只在這一個網域內運作,碰不到任何屬於整個團隊的內容。網域必須先通過驗證,才能把金鑰限定到它;共用的收件匣子網域不能使用。
| 範圍 | 金鑰能做什麼 |
|---|---|
| 傳送、郵件、收到的郵件、收件匣、退訂、群發 | 只限該網域的。請求其他網域會回覆 403 restricted_api_key。 |
GET /emails/metrics |
只能讀取該網域的數據;在 domain_id 裡指定其他網域會回覆 403 restricted_api_key。 |
GET /domains 與 /domains/{id}(讀取、修改、刪除、驗證) |
只能列出並操作它自己的網域。其他任何網域(包括共用子網域)都會回覆 404。 |
/api-keys |
POST 建立的金鑰限定在同一個網域。GET 只列出、DELETE 只撤銷限定到該網域的金鑰;其他金鑰會回覆 404。 |
| 聯絡人、分群、訂閱主題 | 允許。聯絡人是團隊共用的通訊錄,但金鑰不能撤回團隊範圍的退訂。它建立的分群或訂閱主題會綁定到它自己的網域,也不能解除綁定。 |
Webhook(所有方法,包括簽章金鑰)、抑制清單、範本、聯絡人屬性、GET /usage、GET /deliverability、驗證與 POST /domains |
403 restricted_api_key:這些屬於整個團隊。 |
適合只屬於某一個品牌的服務:即使外洩,也只能觸及該品牌的網域,碰不到你的 Webhook、其他金鑰或其他網域。
把金鑰限定到某個收件匣
收件匣金鑰只讓 AI agent 存取一個收件匣,其他都不行。它需要完整存取權限,不能同時限定到網域,只能為這個收件匣讀取、回覆、轉寄與傳送草稿,而且只能以該收件匣的地址寄信。收件匣過期或被刪除後,金鑰隨之失效。
限額
| 限額 | 數值 |
|---|---|
| 每個團隊的有效金鑰數 | 25 把,包括 SMTP 憑證。要建立新的,先撤銷一把(否則回覆 422)。 |
| 每個收件匣的有效金鑰數 | 5 把,不佔團隊的 25 個名額。 |
| 請求數 | 每把金鑰每分鐘 600 次,每個團隊 3,000 次;見 API 基礎。 |
誰能建立哪種金鑰
- 在控制台裡,擁有者、管理員與開發者可以建立金鑰。
- 透過 API 建立的金鑰,權限永遠不會比建立它的金鑰更大:僅限傳送的金鑰只能建立僅限傳送的金鑰;限定到某個網域的金鑰只能為該網域建立金鑰(也只能看到與撤銷這些金鑰);收件匣金鑰不能建立金鑰。
- 金鑰以其建立者目前的團隊角色行事,每次請求都會重新檢查。建立者是在控制台裡建立它的人(或連接了建立它的應用程式的人);透過 API 建立的金鑰,沿用建立它的那把金鑰的建立者。角色不會限制日常工作:無論建立者是什麼角色,完整存取的金鑰都可以傳送郵件,並管理聯絡人、群發、網域、Webhook 與金鑰(限定到某個網域的金鑰是例外,見上文)。高風險操作(清除收件者、移出抑制清單、撤回退訂)需要建立者目前是擁有者或管理員的金鑰;其他金鑰會回覆
403 forbidden。建立者被降級後,他的金鑰從下一次請求起依新角色處理。如果他被移出團隊或自行退出,他建立的所有 API 金鑰、這些金鑰建立的金鑰,以及他的 agent 金鑰都會立即失效(401 invalid_api_key),並顯示為已撤銷;再次被邀請回來也不會恢復。見團隊角色。
建立、重新命名與撤銷金鑰都會記錄在稽核日誌裡。