---
title: Agent 註冊
description: 讓 AI Agent 用一個請求自行建立 BillionSend 帳號和收件匣，之後再由背後的真人認領帳號。
ai:
  exclude: true
---

AI Agent 可以自行註冊 BillionSend，不需要真人在場，也不需要 API 金鑰。一個請求就會回傳共用網域上的一個收件匣和對應的 API 金鑰，Agent 可以立刻開始收信。在 Agent 背後的真人認領之前，這個帳號處於**未認領**狀態。

## 註冊

呼叫 `POST /agent/signup`，帶上 Agent 的名稱和它背後真人的電子郵件地址：

```sh
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` 為選填：收件匣地址 `@` 前面的部分，規則與[建立收件匣](/docs/zh-hant/inboxes)相同。省略時，地址是隨機產生的。

回應為 `201`，內容包含帳號、它的收件匣和金鑰：

```json
{
  "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` 只會顯示一次。它是[限定收件匣的金鑰](/docs/zh-hant/inboxes)：只能讀取那一個收件匣，其他什麼都不行。其他所有路由，包括建立更多收件匣，都會回傳 `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 收件匣一樣經過同樣的[安全層](/docs/zh-hant/agent-safety)。

隨時可以用 `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` 標頭。
