指南

收信

来信经过什么、邮件长什么样、扣留、trust_envelope、附件和原始信源。

docs.simail.ai/zh/receiving

入站流水线

发到你地址的信在 SMTP 时被接受或永久拒绝。接受的信在存入之前经过确定性检查，所以不存在「能读到但还没检查」的窗口。收信路径上不跑语言模型。

体积（最多 10 MiB）、收件地址、邮箱状态和你的收信拦截名单。未知、已退役、已暂停或未认领的邮箱，以及被拦截的发件人，会被永久拒绝。
按发件人的速率（每个发件人每个邮箱每小时 50 封；每个组织每小时 2,000 封）。超限的信接受并扣留，不退信。
先存原始信，再解析。
重复的（同一 Message-ID 且内容相同）丢掉。同一 Message-ID 但内容不同的留下，并标 msgid_collision。
归线程（见线程）。
分类：normal、spam、auto_reply（RFC 3834 头、休假回复，以及 simail agent 所发邮件上的循环标记）、bounce（投递和反馈报告）、otp（验证码邮件）和 system。
提示注入启发式（指令措辞、隐藏或零宽文本、CSS 隐藏、伪造系统提示、长编码块）产生 injection_score；达到或超过阈值（默认 0.7；策略可以更严）就扣留。
对受监管或特权材料的筛查会把命中的信扣留给人。
回复提取产生 extracted_text：去掉引用历史后的新内容（包括常见的中文引用标记）。
一次提交全部，然后发布事件。

可选、默认关闭：附件抽文本和基于模型的注入打分在存入之后跑，只能追加扣留，不能放行。

邮件对象

{
  "message_id": "msg_…",
  "thread_id": "thr_…",
  "labels": ["received", "unread"],
  "timestamp": "2026-10-18T17:02:11Z",
  "from": "Ada <ada@example.com>",
  "to": ["shop-helper@simail.email"],
  "cc": [],
  "subject": "Where is my order?",
  "preview": "Hi, I ordered last week and…",
  "text": "Hi, I ordered last week and…",
  "extracted_text": "Hi, I ordered last week and haven't heard back.",
  "attachments": [{ "attachment_id": "att_…", "filename": "receipt.pdf", "size": 48213, "content_type": "application/pdf" }],
  "in_reply_to": null,
  "references": [],
  "size": 61840,
  "created_at": "2026-10-18T17:02:12Z",
  "trust_envelope": {
    "auth": { "spf": null, "dkim": null, "dmarc": null, "computed_by": "none" },
    "sender_known": false,
    "first_contact": true,
    "classification": "normal",
    "hold": false,
    "hold_reasons": [],
    "injection_score": 0.05,
    "flags": [],
    "untrusted": true
  }
}

html 只给带 message_raw_read 的 key（以及人），simail 从不替你渲染它。优先用 extracted_text 和 text。
trust_envelope.auth 只在 simail 自己算过时报告 SPF、DKIM 和 DMARC（computed_by）。它是 "none" 时结果为 null：不要把 From 当成已认证。
sender_known 在发件人是该邮箱的联系人时为真（你先写过的人，或人提升的人）。其他 simail 客户的信和陌生人一样对待。
Reply-To 会存，但从不用来决定回复发给谁。

扣留的信

每种扣留原因以及人能做什么，见扣留与注入扫描。扣留的信（hold: true，标签 held）在每个通道（REST、MCP、webhook、事件、WebSocket）上只有元数据：message_id、thread_id、发件地址、收到时间、大小、标签和 hold_reasons。主题、正文和附件不给。只有人能在控制台放行或拒绝。POST …/messages/{message_id}/agent-armor/release 返回 403 human_required。

hold_reasons 说明原因，例如 rate_limited 或 unparseable，或来自注入、一次性验证码、敏感材料检查的扣留。

列出和读取

方法与路径	权限
`GET /v0/inboxes/{inbox_id}/messages`	`message_read`
`GET /v0/inboxes/{inbox_id}/messages/{message_id}`	`message_read`
`PATCH /v0/inboxes/{inbox_id}/messages/{message_id}`（标签）	`message_update`
`DELETE /v0/inboxes/{inbox_id}/messages/{message_id}`（进废纸篓；30 天后清除）	`message_delete`
`POST /v0/inboxes/{inbox_id}/messages/batch-get`、`batch-update`	`message_read`、`message_update`
`GET /v0/inboxes/{inbox_id}/messages/search?q=`	`message_read`
`GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw`	`message_raw_read`
`GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`	`message_read`

查询参数：labels、before、after、include_spam、include_blocked、include_trash（各自需要对应的 label_*_read 权限）、limit、page_token、ascending。

搜索对主题、发件人和正文做全文匹配，中英文都可以。扣留的信只能按元数据搜索。

附件和原始信源

附件和 raw 的响应不含文件。它们返回隔离内容域上的短时、一次性下载链接：

{ "attachment_id": "att_…", "filename": "receipt.pdf", "size": 48213, "content_type": "application/pdf", "download_url": "https://view.siagentmail.com/…", "expires_at": "2026-10-18T17:07:12Z" }

链接 5 分钟后过期，只能用一次。文件总是作为下载提供（Content-Disposition: attachment），从不渲染。

哪些事件唤醒 agent

每个 message.received 事件带 data.wake。已知线程、联系人或收信允许名单上的信会唤醒 agent。陌生人的信只在每个邮箱的每日预算和每个发件人的每小时预算内唤醒；超过之后，事件仍会记下并能从 GET /v0/events 拿到，但 webhook 和 WebSocket 会跳过，除非订阅 include_non_wake: true。每天一条 inbox.digest 报告计数。扣留的信从不唤醒。