# Beta & waitlist

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

> GET /v0/beta, POST /v0/agent/sign-up and POST /v0/waitlist — the three endpoints an agent may call without a key, with every response.

These endpoints need no API key. They are the only way an agent can start with simail, and during
the private beta they mostly answer that sign-up is closed. Read [Beta gate & waitlist](/beta/) for
the rules behind them.

:::caution[Agents]
If sign-up returns `403 signup_closed`: **do not retry**, do not try another username, email or
identity, and forward `human_message` to your human verbatim. Retrying cannot change the answer.
:::

## Beta status

`GET /v0/beta`

Public. Call it first.

```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 正在内测,暂未开放注册。请让你的主人加入等候名单。"
  }
}
```

| Field | Values |
|---|---|
| `signup` | `waitlist` (default), `invite_only` or `open`. In every mode an agent can sign up only with a directed code from its human. |
| `waitlist` | `open` or `closed` |
| `waitlist_url` | where a human joins the waitlist |
| `docs_url` | these docs |
| `human_message` | `{ en, zh }` text to show your human |

## Agent sign-up

`POST /v0/agent/sign-up`

Public; 10 requests per hour per network range.

| Body field | Notes |
|---|---|
| `invite_code` | required: a **directed code** (`SI-XXXX-XXXX`) your human generated in the console. Single use, valid 24 hours. |
| `username` | optional; the inbox address to create (see [address rules](/inboxes/#address-rules)) |

```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。"
  }
}
```

| Field | Notes |
|---|---|
| `organization_id` | your human's organization |
| `inbox_id` | the new inbox; it **does not receive mail** until your human claims it |
| `api_key` | a **restricted** key, shown once. Until the claim it can call only `GET /v0/auth/me` and `GET /v0/beta`; everything else returns `403 claim_required`. |
| `claim_code` | your human enters it in the console within 24 hours |
| `claim_required` | always `true` |
| `human_message` | forward it to your human; it contains the claim code, never the key |

Claiming revokes the restricted key; your human gives you the new one. An inbox that is not claimed
within 24 hours is deleted and its address is retired.

### 403 signup_closed

Returned whenever there is no valid directed code, in every sign-up mode:

```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"
  }
}
```

### Other errors

| Status | `code` | When |
|---|---|---|
| 400 | `validation_error` | malformed body or username |
| 409 | `address_unavailable` | the username is taken, reserved or retired |
| 429 | `rate_limited` | too many attempts from your network (`Retry-After`) |
| 503 | `upstream_unavailable` | temporarily unavailable; retry later (`Retry-After`) |

## Join the waitlist (for your human)

`POST /v0/waitlist`

Public; 5 per day per network range. Puts your human on the waitlist without asking for their email
address. The body accepts **only** these fields; anything else, in particular `human_email`, is
rejected with `400 validation_error`.

| Field | Values |
|---|---|
| `use_case` | required: `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` | up to 64 characters |
| `uses_other_agent_mail` | `true` or `false` |
| `note` | up to 280 characters; no client or case information |

```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"
  }
}
```

Forward `human_message` (or at least `claim_url`) to your human. The link works once and expires with
the entry after 24 hours. The response looks the same whether or not the entry was stored, and
submitting twice does not help. Errors: `400 validation_error` (unknown field or bad value),
`429 rate_limited`, `503 upstream_unavailable` (retry later).

## Not offered

`POST /v0/agent/human` and `POST /v0/agent/verify` return `501 not_implemented` (`not_planned`):
humans confirm through the claim link instead.