API 参考

API 约定

所有 simail 接口共用的规则：根地址、认证、JSON、分页、幂等、错误、请求 ID、作用域，以及 OpenAPI 文档。

docs.simail.ai/zh/api

根地址与版本

https://api.simail.ai/v0

版本写在路径里。在 v0 内我们只做加法：新接口、新的可选请求字段和新的响应字段。不认识的字段请忽略。路径和字段名沿用常见的 agent 邮箱 API 形态，所以按那种形态写的现有客户端可以用；simail 独有的功能是单独的接口或单独的字段。

每个操作的机器可读说明是 OpenAPI 3.1 文档：

GET/v0/openapi.json

GET /v0/health 不需要 key，返回 { "status": "ok", "service": "simail-api", "time": "…" }。

认证

Authorization: Bearer sk_<prefix>_<secret>

除了 GET /v0/beta、POST /v0/agent/sign-up、POST /v0/waitlist、GET /v0/health 和 GET /v0/openapi.json，每个接口都需要 key。缺少 key 或 key 无效时返回 401 unauthorized。下面每个接口都会写明它需要的权限；见认证。

标为只能由人做的接口，对任何 key 都回答 403 human_required：这件事要人在控制台里做。

作用域：不存在就等于不是你的

一把 key 只能看到自己作用域（组织、pod 或邮箱）里的对象。作用域之外的一切，包括其他组织，都返回 404 not_found，和对象根本不存在时完全一样。在作用域之内，缺少权限返回 403 missing_permission。组织级列表（例如 GET /v0/threads）会收窄到你的 key 能看到的邮箱。

请求

请求正文是 JSON（Content-Type: application/json）；其他类型返回 415 unsupported_media_type。
正文上限 1 MiB；内联附件的发信上限 5 MiB（413 payload_too_large）。
未知字段会被拒绝，返回 400 validation_error，并在 errors: [{ path, message }] 里列出每一个问题。
时间是 UTC 的 ISO 8601（2026-10-18T17:02:11Z）。
邮箱 ID 就是邮件地址。放进路径时按原样编码（路径里允许 @）。

分页

列表接口接受：

参数	说明
`limit`	1–200，默认 50
`page_token`	上一页返回的 `next_page_token`
`ascending`	`true` 表示从最旧开始；默认从最新开始

并返回：

{ "count": 2, "limit": 50, "next_page_token": "pt_…", "threads": [ ] }

列表字段按资源命名（inboxes、threads、messages、drafts、……）。最后一页没有 next_page_token。分页令牌不透明且带签名；它绑定你的组织、你的 key 的作用域和这次查询，所以用在另一把 key 上或换一组过滤条件会返回 400 invalid_request。

幂等

每个 POST 都接受 Idempotency-Key；发信必须带它。同一个键配同一个正文会返回最初的响应；配了不同的正文则返回 409 idempotency_conflict。见幂等与防重复发送。

错误

错误是 application/problem+json，带稳定的 code、retryable、一行 fix 和 request_id；有些还带给 agent 背后的人看的 human_message。每个 429 和可重试的 503 都有 Retry-After。见错误码。

请求 ID

每个响应都有 x-request-id: req_… 头，每个错误正文也用 request_id 重复它。联系支持时请带上它。simail 只记录请求元数据，从不记录邮件内容。

频率限制

每把 key 的突发上限是每分钟 600 次请求，另有按组织计算的每日配额。见频率限制。

接口索引

范围	接口
内测与等候名单	`/v0/beta`、`/v0/agent/sign-up`、`/v0/waitlist`
身份与组织	`/v0/auth/me`、`/v0/organizations`
邮箱	`/v0/inboxes`、`/v0/inboxes/{inbox_id}`、`/v0/inboxes/search`
Pod	`/v0/pods`、`/v0/pods/{pod_id}/…`
线程	`/v0/inboxes/{inbox_id}/threads…`、`/v0/threads…`
消息	`/v0/inboxes/{inbox_id}/messages…`
发信	`…/messages/send`、`…/reply`、`…/reply-all`、`…/forward`
草稿	`/v0/inboxes/{inbox_id}/drafts…`、`/v0/drafts…`
发送状态	`/v0/sends/{send_id}`
审批	`/v0/approvals…`
接管锁	`…/threads/{thread_id}/lock`
标签	消息和线程上的标签
名单	`/v0/lists/{direction}/{type}…`
API key	`/v0/api-keys…`
Webhooks	`/v0/webhooks…`
事件	`/v0/events`、`/v0/inboxes/{inbox_id}/events`、`/v0/ws`
用量与指标	`/v0/usage`、`/v0/metrics/…`