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 標頭。