# 内测与等候名单

Source: https://docs.simail.ai/zh/api/beta/

> GET /v0/beta、POST /v0/agent/sign-up 和 POST /v0/waitlist——agent 不带 key 就能调用的三个接口,以及每一种响应。

这几个接口不需要 API key。它们是 agent 开始使用 simail 的唯一入口;内测期间,它们多半会回答"注册未开放"。背后的规则见[内测门与等候名单](/zh/beta/)。

:::caution[写给 agent]
注册返回 `403 signup_closed` 时:**不要重试**,不要换用户名、邮箱或身份,把 `human_message` 原样转给你的主人。重试改变不了答案。
:::

## 内测状态

`GET /v0/beta`

公开接口。先调它。

```http
GET https://api.simail.ai/v0/beta
```

`200 OK`:

```json
{
  "signup": "waitlist",
  "waitlist": "open",
  "waitlist_url": "https://simail.ai/waitlist",
  "docs_url": "https://docs.simail.ai",
  "human_message": {
    "en": "SiMail is in private beta and sign-ups are closed. Ask your human to join the waitlist.",
    "zh": "SiMail 正在内测,暂未开放注册。请让你的主人加入等候名单。"
  }
}
```

| 字段 | 取值 |
|---|---|
| `signup` | `waitlist`(默认)、`invite_only` 或 `open`。任何模式下,agent 都只能用主人给的定向码注册。 |
| `waitlist` | `open` 或 `closed` |
| `waitlist_url` | 人加入等候名单的地址 |
| `docs_url` | 本文档 |
| `human_message` | `{ en, zh }`,给你主人看的话 |

## agent 注册

`POST /v0/agent/sign-up`

公开接口;每个网段每小时 10 次。

| 正文字段 | 说明 |
|---|---|
| `invite_code` | 必填:你的主人在控制台生成的**定向码**(`SI-XXXX-XXXX`)。只能用一次,24 小时内有效。 |
| `username` | 可选;要创建的邮箱地址(见[地址规则](/zh/inboxes/#地址规则)) |

```http
POST https://api.simail.ai/v0/agent/sign-up
Content-Type: application/json

{ "invite_code": "SI-7KQ2-M9XD", "username": "shop-helper" }
```

### 201 Created

```json
{
  "organization_id": "org_01JZX3S5V7W9X1Y3Z5A7B9C1D3",
  "inbox_id": "shop-helper@simail.email",
  "api_key": "sk_00000000_EXAMPLE-NOT-A-REAL-KEY-00000000000000000000",
  "claim_code": "EXAMPLEclaim01",
  "claim_required": true,
  "human_message": {
    "en": "Your agent created a SiMail inbox (shop-helper@simail.email). It stays unusable until you claim it at https://app.simail.ai with claim code EXAMPLEclaim01 within 24 hours; then give the agent the new key shown to you.",
    "zh": "你的 agent 创建了一个 SiMail 邮箱(shop-helper@simail.email)。请在 24 小时内到 https://app.simail.ai 用认领码 EXAMPLEclaim01 认领,认领前邮箱不可用;认领后把控制台显示的新 key 交给 agent。"
  }
}
```

| 字段 | 说明 |
|---|---|
| `organization_id` | 你主人的组织 |
| `inbox_id` | 新邮箱;在主人认领之前它**收不到信** |
| `api_key` | **受限** key,只显示一次。认领之前只能调用 `GET /v0/auth/me` 和 `GET /v0/beta`;其他接口都返回 `403 claim_required`。 |
| `claim_code` | 主人要在 24 小时内在控制台输入它 |
| `claim_required` | 总是 `true` |
| `human_message` | 转给你的主人;里面有认领码,从不包含 key |

认领会吊销受限 key;你的主人会把新 key 交给你。24 小时内没被认领的邮箱会被删除,地址随之退役。

### 403 signup_closed

只要没有有效的定向码,在任何注册模式下都返回:

```json
{
  "type": "https://docs.simail.ai/errors#signup_closed",
  "title": "SignupClosedError",
  "status": 403,
  "detail": "Sign-ups are closed during the private beta.",
  "instance": "/v0/agent/sign-up",
  "name": "SignupClosedError",
  "code": "signup_closed",
  "message": "Sign-ups are closed during the private beta.",
  "fix": "Do not retry. Forward human_message to your human; join the waitlist at waitlist_url.",
  "docs": "https://docs.simail.ai/errors#signup_closed",
  "retryable": false,
  "request_id": "req_01JZX3Q4M8T6C2W9R5N7K0B1AD",
  "waitlist_url": "https://simail.ai/waitlist",
  "docs_url": "https://docs.simail.ai",
  "human_message": {
    "en": "SiMail (simail.ai) is in private beta and agent sign-up is closed. Your agent should not retry. To get access, join the waitlist: https://simail.ai/waitlist",
    "zh": "SiMail(simail.ai)正在内测,agent 注册暂未开放,你的 agent 不应重试。想要使用请加入等候名单:https://simail.ai/waitlist"
  }
}
```

### 其他错误

| 状态 | `code` | 何时 |
|---|---|---|
| 400 | `validation_error` | 正文或用户名格式不对 |
| 409 | `address_unavailable` | 用户名已被占用、是保留名或已退役 |
| 429 | `rate_limited` | 你的网络尝试次数太多(`Retry-After`) |
| 503 | `upstream_unavailable` | 暂时不可用;稍后重试(`Retry-After`) |

## 加入等候名单(替你的主人)

`POST /v0/waitlist`

公开接口;每个网段每天 5 次。把你的主人加入等候名单,而不需要提供他们的邮箱地址。正文**只**接受下列字段;其他任何字段,尤其是 `human_email`,都会以 `400 validation_error` 拒绝。

| 字段 | 取值 |
|---|---|
| `use_case` | 必填:`support_agent`、`workflow_automation`、`personal_assistant`、`testing_qa`、`research`、`other` |
| `expected_monthly_volume` | `lt_100`、`100_1k`、`1k_10k`、`10k_100k`、`gt_100k` |
| `industry` | `software`、`ecommerce`、`marketing`、`education`、`research`、`legal`、`healthcare`、`finance`、`other` |
| `framework` | 最多 64 个字符 |
| `uses_other_agent_mail` | `true` 或 `false` |
| `note` | 最多 280 个字符;不要写客户或案件信息 |

```http
POST https://api.simail.ai/v0/waitlist
Content-Type: application/json

{
  "use_case": "support_agent",
  "expected_monthly_volume": "100_1k",
  "industry": "software",
  "framework": "hermes",
  "uses_other_agent_mail": false,
  "note": "Answers customer questions for a small online shop."
}
```

### 202 Accepted

```json
{
  "entry_id": "wle_01JZX3R2D9N4E6F8G0H2J4K6M8",
  "claim_url": "https://app.simail.ai/beta/claim#t=EXAMPLE-claim-token-01",
  "expires_at": "2026-10-19T17:00:00.000Z",
  "human_message": {
    "en": "Your agent asked to put you on the SiMail private-beta waitlist. Open this link within 24 hours and sign in with your email to confirm: https://app.simail.ai/beta/claim#t=EXAMPLE-claim-token-01",
    "zh": "你的 agent 申请把你加入 SiMail 内测等候名单。请在 24 小时内打开此链接并用邮箱登录确认:https://app.simail.ai/beta/claim#t=EXAMPLE-claim-token-01"
  }
}
```

把 `human_message`(至少是 `claim_url`)转给你的主人。链接只能用一次,24 小时后随条目一起过期。无论条目是否被保存,响应看起来都一样,重复提交也没有用。错误:`400 validation_error`(未知字段或取值不对)、`429 rate_limited`、`503 upstream_unavailable`(稍后重试)。

## 不提供

`POST /v0/agent/human` 和 `POST /v0/agent/verify` 返回 `501 not_implemented`(`not_planned`):人改为通过认领链接确认。