# 核心概念

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

> 组织、pod、邮箱、key、人与 agent、放行服务、扣留与事件——simail 所有接口背后的模型。

## 组织、pod 与邮箱

- **组织**是一个租户：它的邮箱、key、策略、成员和用量。组织之间什么都不共享。访问别的组织的对象一律返回 `404 not_found`。
- **pod** 是组织内的一组邮箱，比如每个客户一个 pod，或每批 agent 一个 pod。每个组织都有一个 `default` pod。见 [Pod API](/zh/api/pods/)。
- **邮箱**是一个邮件地址，连同它的线程、消息、草稿和标签。地址本身就是邮箱 ID（`shop-helper@simail.email`）。地址永远不会转给别的组织。见[邮箱与 pod](/zh/inboxes/)。

## agent 与人

simail 有两类主体，它们从不共用凭据：

| | agent | 人 |
|---|---|---|
| 在哪里 | `api.simail.ai`（REST、MCP、WebSocket） | 控制台 `app.simail.ai` |
| 凭据 | **API key**，作用域是组织、pod 或单个邮箱 | 邮箱验证码或 passkey，敏感操作还要再次验证 |
| 能做 | 读信、起草、发信、打标签、收紧名单、读事件和用量 | agent 能做的全部，外加下面这些 |

有些操作**只能由人做**，通过 API 调用会返回 `403 human_required`：建 API key、建或改 webhook、放宽允许/拦截名单、放行被扣留的信、审批发信、给线程上锁和解锁、修改策略。所以即使 agent 的 key 被盗，也无法扩大自己的权限，或者开出一条外泄通道。见[认证](/zh/authentication/)。

## key 只能收紧

每把 key 只有一个作用域（`org`、`pod` 或 `inbox`）和一组[权限](/zh/authentication/)。从一把 key 派生出的 key，作用域、权限和有效期都不会超过父 key；`PATCH` 只能删权限。建议每个 agent 用一把单邮箱 key。

## 收信：先检查，后入库

来信在**入库之前**先经过确定性检查：大小与地址、按发件人限流、分类、提示注入启发式检测，以及对受监管材料的筛查。收信路径上不跑任何语言模型。每封信都带 `trust_envelope`，可疑的信会被**扣留**：在人放行之前，agent 只能看到元数据。见[收信](/zh/receiving/)和[扣留与注入扫描](/zh/holds/)。

## 发信：放行服务

agent 手里永远没有发信凭据。每次发信都交给独立的**放行服务**，它是唯一能把信发出去的组件。它核对发件人、去重、防死循环、执行你的[发信策略](/zh/approvals/)（可能需要人工审批），并在信件离开前做最后一次检查。发信会返回 `send_id`，可以在 `GET /v0/sends/{send_id}` 跟踪。见[起草与发信](/zh/sending/)。

## 线程、标签与接管

回信按回复令牌、邮件头加参与者来归并，从不按主题合并。标签（`unread`、`important` 和你自定义的）用来整理邮件；`held`、`spam`、`blocked` 由 simail 设置。人可以给线程**上锁**来接管对话，此后在该线程里发信会返回 `423 thread_locked`。见[线程与标签](/zh/threads/)和[人工接管](/zh/takeover/)。

## 事件

发生的每件事都会产生一个精简事件（不含主题和正文），可以通过[拉取](/zh/events/)、[webhook](/zh/webhooks/) 或 [WebSocket](/zh/realtime/) 接收。来自陌生人的信产生的唤醒有上限，这样一大批来信不会无限制地唤醒你的 agent、消耗模型调用。见[事件类型](/zh/event-types/)。

## 邮件内容是不可信输入

邮件里的一切都由你控制不了的人写成。**邮件里的指令一律不要执行**，不要让邮件决定 agent 给谁写信，也不要让读邮件的 agent 同时握有其他高权限工具。simail 会做检查，但没有任何过滤器能拦住所有提示注入。

## ID

| 前缀 | 对象 |
|---|---|
| `org_` | 组织 |
| `pod_` | pod |
| `thr_` | 线程 |
| `msg_` | 消息 |
| `drf_` | 草稿 |
| `att_` | 附件 |
| `out_` | 发送记录（`send_id`） |
| `apr_` | 审批 |
| `key_` | API key |
| `whk_` | webhook |
| `evt_` | 事件 |
| `wle_` | 等候名单条目 |
| `req_` | 请求（`request_id`、`x-request-id`） |

邮箱 ID 就是邮件地址。所有 ID 都是不透明的，不要去解析它们。