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

Agent 注册

让 AI agent 用一个请求自己创建 BillionSend 账号和收件箱,之后由真人认领这个账号。

AI agent 可以自行注册 BillionSend,不需要真人在场,也不需要 API 密钥。一个请求就会返回共享域名上的一个收件箱,以及对应的 API 密钥,agent 可以马上开始收信。在 agent 背后的人认领之前,账号处于未认领状态。

注册

调用 POST /agent/signup,传入 agent 的名称和它背后那个人的邮箱地址:

curl -X POST "https://api.billionsend.com/agent/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "ana@example.com",
    "name": "Research helper",
    "username": "research-helper"
  }'
  • human_email 是认领链接的接收地址,别无他用。一次性邮箱服务的地址,或 BillionSend 域名上的地址,会返回 422。
  • name 是 agent 的名称:最长 60 个字符的普通名称,不含 @、链接或电话号码。在有人为账号重命名之前,它就是账号的名称。模仿品牌的名称会返回 422。
  • username 是可选的:收件箱地址 @ 前的部分,规则与创建收件箱相同。省略时,地址随机生成。

响应是 201,包含账号、它的收件箱和它的密钥:

{
  "object": "agent_signup",
  "status": "unclaimed",
  "api_key": "bs_...",
  "inbox": { "id": "...", "email_address": "research-helper@team-k3m9x2.example.com", "...": "..." },
  "claim": { "email": "ana@example.com", "expires_at": "2026-11-23T10:00:00.000Z" },
  "limits": { "receive_only": true, "inboxes": 1, "emails_per_day": 0, "received_per_day": 50, "received_per_inbox_per_hour": 20 }
}

api_key 只显示一次。它是一把限定到收件箱的密钥:只能读取这一个收件箱,别的都不行。其他所有路由,包括创建更多收件箱,都会返回 403 restricted_api_key。

未认领期间

未认领的账号只能收信。它没有所有者,也没有人登录,限额比 Free 套餐更严格:

未认领 Free
收件箱 1 3
每天发送的邮件 0 100
每天收到的邮件 50 100
每个收件箱每小时收到的邮件 20 200

所有发送,不论来自收件箱接口、POST /emails、批量接口还是 SMTP,都会返回 403 team_unclaimed。超过任一收信限额后,发件方会在 RCPT 阶段收到 452 4.2.2 并稍后重试,与任何已满的邮箱一样。发给这个收件箱的邮件正常到达,并经过与任何 agent 收件箱相同的安全层。

随时可以用 GET /agent/status 查询账号的状态,它返回 unclaimed 以及账号自动删除的日期,或者 claimed。

认领账号

agent 注册时,BillionSend 会把认领链接发到 human_email。这个人打开链接,登录或创建自己的 BillionSend 账号,然后选择认领账号。

  • 这个人成为账号的所有者,账号转为 Free 套餐,agent 的密钥在他们的团队下继续有效。
  • 链接在账号的截止时间之前一直有效,已经认领过的链接不能再次使用。
  • 认领计入这个人的团队数量上限,与创建团队一样。已达上限的人,先删除一个团队或升级套餐,再重新打开链接。

如果邮件没有收到,agent 可以调用 POST /agent/claim-email 重新发送。之前的链接随即失效。认领邮件一共最多发送 5 封,每封间隔十分钟。

无人认领会怎样

未认领的账号在注册 7 天后自动删除,连同它的收件箱、邮件和密钥,方式与删除团队相同。

限额

注册设有限额,防止它被用来塞满平台或向陌生人发信:

限额 数值
每个客户端地址的注册次数 每小时 3 次
注册总次数 每小时 100 次
每个 human_email 的注册次数 每天 3 次
同一个 human_email 下待认领的账号 3 个

被拒绝的注册返回 429,并带有 retry-after 头。

这个页面有帮助吗?