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 头。