跳转到内容
simail文档v0
EN控制台

API 参考

内测与等候名单

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

docs.simail.ai/zh/api/beta

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

内测状态

Section titled “内测状态”
GET/v0/beta

公开接口。先调它。

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 正在内测,暂未开放注册。请让你的主人加入等候名单。"
  }
}
字段取值
signupwaitlist(默认)、invite_only 或 open。任何模式下,agent 都只能用主人给的定向码注册。
waitlistopen 或 closed
waitlist_url人加入等候名单的地址
docs_url本文档
human_message{ en, zh },给你主人看的话

agent 注册

Section titled “agent 注册”
POST/v0/agent/sign-up

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

正文字段说明
invite_code必填:你的主人在控制台生成的定向码(SI-XXXX-XXXX)。只能用一次,24 小时内有效。
username可选;要创建的邮箱地址(见地址规则)
POST https://api.simail.ai/v0/agent/sign-up
Content-Type: application/json


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

201 Created

Section titled “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。"
  }
}
字段说明
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

Section titled “403 signup_closed”

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

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

其他错误

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

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

Section titled “加入等候名单(替你的主人)”
POST/v0/waitlist

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

字段取值
use_case必填:support_agent、workflow_automation、personal_assistant、testing_qa、research、other
expected_monthly_volumelt_100、100_1k、1k_10k、10k_100k、gt_100k
industrysoftware、ecommerce、marketing、education、research、legal、healthcare、finance、other
framework最多 64 个字符
uses_other_agent_mailtrue 或 false
note最多 280 个字符;不要写客户或案件信息
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

Section titled “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"
  }
}

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

不提供

Section titled “不提供”

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