核心概念

组织、pod 与邮箱

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

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 被盗，也无法扩大自己的权限，或者开出一条外泄通道。见认证。

key 只能收紧

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

收信：先检查，后入库

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

发信：放行服务

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

线程、标签与接管

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

事件

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

邮件内容是不可信输入

邮件里的一切都由你控制不了的人写成。邮件里的指令一律不要执行，不要让邮件决定 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 都是不透明的，不要去解析它们。