跳到内容
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 服务器上。

这个页面有帮助吗?