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

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),並顯示為已撤銷;再次被邀請回來也不會恢復。見團隊角色。

建立、重新命名與撤銷金鑰都會記錄在稽核日誌裡。

其他金鑰

  • SMTP 憑證是在 SMTP 頁面為 SMTP 伺服器建立的僅限傳送金鑰。
  • Agent 金鑰(bs_agent_…)只用於 MCP 伺服器。它們在 MCP 下建立,權限限定為唯讀、讀取並回覆,或讀取並傳送,每個團隊最多 20 把。你的一般 API 金鑰不能用在 MCP 伺服器上。

这个页面有帮助吗?