# API 约定

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

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

## 根地址与版本

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

## 认证

```http
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`。下面每个接口都会写明它需要的权限；见[认证](/zh/authentication/)。

标为**只能由人做**的接口，对任何 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` 表示从最旧开始；默认从最新开始 |

并返回：

```json
{ "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`。见[幂等与防重复发送](/zh/idempotency/)。

## 错误

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

## 请求 ID

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

## 频率限制

每把 key 的突发上限是每分钟 600 次请求，另有按组织计算的每日配额。见[频率限制](/zh/rate-limits/)。

## 接口索引

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