Beta & waitlist

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 for the rules behind them.

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.

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

200 OK:

{
  "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)

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

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

201 Created

{
  "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:

{
  "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

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

{
  "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.