指南

草稿与发送

发送、回复、回复全部、转发和草稿；幂等、发送前检查、审批、定时和发送状态。

docs.simail.ai/zh/sending

agent 从不持有发信凭据。每封外发信都提交给 simail 的放行服务，那是唯一能发信的组件。它检查邮件、套用组织策略、在策略要求时等人批准，并在信离开前立刻再做一次最终检查。

simail 用于预期中的事务邮件。冷外联和群发不允许；见可接受使用政策。

端点

方法与路径	权限
`POST /v0/inboxes/{inbox_id}/messages/send`	`message_send`
`POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply`	`message_send`
`POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all`	`message_send`
`POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward`	`message_send`
`GET`、`POST /v0/inboxes/{inbox_id}/drafts`；`GET`、`PATCH`、`DELETE …/drafts/{draft_id}`	`message_read`、`draft_write`
`POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments`	`draft_write`
`POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send`	`message_send`
`GET /v0/sends/{send_id}`	`message_read`
`DELETE /v0/sends/{send_id}`（取消）	`message_send`
`GET /v0/approvals`、`GET /v0/approvals/{approval_id}`	`approval_read`

请求

POST /v0/inboxes/shop-helper@simail.email/messages/send
Authorization: Bearer $SIMAIL_API_KEY
Idempotency-Key: order-1042-shipped
Content-Type: application/json

{
  "to": ["ada@example.com"],
  "subject": "Your order shipped",
  "text": "Hi Ada, your order #1042 shipped today.",
  "labels": ["orders"]
}

字段	说明
`to`、`cc`、`bcc`	合计最多 50 个收件人；`bcc` 仅在策略允许时
`subject`
`text`、`html`	至少其一；总是带上 `text`
`attachments`	`[{ "filename", "content_type", "content" }]`，`content` 为 base64，或 `{ "draft_attachment_id" }`；最多 32 个
`labels`	已发送副本上的标签
`send_at`	最多提前 30 天的 ISO 8601 时间；大约在该时间的 2 分钟内发出
`reply_to`	忽略：simail 自己设置 Reply-To，以便回复能归线程
`headers`	拒绝，除了 `X-Simail-Client-Ref`
`track_opens`	忽略：simail 不追踪打开或点击

带头里有 CR、LF、NUL 或其他控制字符的字段，以 422 invalid_header 拒绝。

reply 的收件人取自原信的 From（从不取 Reply-To）。reply-all 加上原来的 To 和 Cc，去掉你自己的地址。主题加上 Re: 或 Fwd:，线程头由 simail 设置。你可以传 expected_recipients；如果和 simail 推导的收件人不同，发送会被拦住，以免一次回复悄悄变成群发。转发发给新收件人，所以转发算首次联系。

体积

整封外发信，包括头、正文、附件和编码开销，最多 5 MiB（原始附件大约 3.5 MiB），附件最多 32 个。更大的信返回 413 message_too_large，带 limit_bytes 和 estimated_bytes。带内联附件的发送请求体限 5 MiB，否则 1 MiB。

幂等

完整规则见幂等与重复。简言之：每次发送（send、reply、reply-all、forward、草稿 send）都必须带 Idempotency-Key。键的作用域是你的组织和你的 key。同一把键、同一份正文返回原来的结果；同一把键、不同正文返回 409 idempotency_conflict。超时后用同一把键重试不会发两次。

响应

202 Accepted：

{ "send_id": "out_…", "message_id": "msg_…", "thread_id": "thr_…", "status": "pending_approval", "flags": ["first_contact"] }

`status`	含义
`sent`	已交给邮件网络
`sending`	正在发送
`scheduled`	等待 `send_at`
`pending_approval`	等人（见下）
`blocked`	拒绝；以 `422 send_blocked` 返回，带 `reasons`

之后的状态在 GET /v0/sends/{send_id}：approved、rejected、expired、cancelled、failed，以及 outcome_unknown（可能发出也可能没有；simail 不会自动重发，等投递事件到来再对账）。

信处于 scheduled、pending_approval 或 approved 时，用 DELETE /v0/sends/{send_id} 取消。已经在发或已终态时，取消返回 409 conflict，reason 为 "already_sending" 或 "already_final"。删除已提交的草稿会先取消它。

发送前检查

拦住的原因（reasons）：sender_mismatch、empty_body、placeholder（例如 {{、[NAME]、TODO、lorem ipsum）、too_many_recipients、body_too_large、attachment_too_large、attachment_not_allowed、invalid_address、invalid_header、suppressed（地址硬退信或被投诉）、blocked_recipient、duplicate、loop_auto_reply、loop_thread、loop_peer、card_number、credential、expected_recipients_mismatch、thread_locked、first_contact_blocked、message_too_large、principal_revoked、policy_changed、daily_limit_at_send、platform_hard_cap。

风险旗标（flags，给审批人看）：first_contact、punycode、lookalike_domain、cross_thread_echo（邮件复用了你在其他线程读到的内容）、has_links、has_attachments、bcc、credential_like、large_recipient_set、new_recipient_domain、recipient_unverified。

重复和循环。 去重窗口内内容相同的信（同一发件人、收件人、主题和正文）返回 409 duplicate_send。回复自动回复、退信或其他 simail agent 的信会被拦住，超过往来限额的线程和对端也会，所以两个 agent 不能永远互发。

最终检查。 定时、已批准或延迟的信发出之前，simail 重查当前状态：平台或组织暂停、已吊销的 key、已删除或暂停的邮箱、线程锁、抑制和拦截名单、当前策略和今天的限额。不再通过的信被留下或拦住；不会凭过期的批准发出。

策略和审批

细节：审批与发信策略。策略由人在控制台按组织、pod、邮箱或 key 设置；每一层只能比上一层更严。主要设置：

approval.mode：none、first_contact、risky（任何旗标）、first_contact_and_risky、all。
first_contact：对还不是该邮箱联系人的收件人，allow、approval 或 block。
组织、邮箱、key 和收件人的每日限额，加上每线程每小时限额。
是否允许 bcc、外发附件和链接。

需要批准时，审批人在控制台（如果接上了，也在 Telegram、Slack 或邮件）看到一张卡：完整收件人列表、主题、正文开头、附件和旗标。批准绑定确切内容：内容变了，批准就不再适用。批准默认 24 小时后过期。agent 可以读审批状态（GET /v0/approvals），但永远不能批准。

署名和头

外发信署 simail.ai：一行页脚 — Sent by an AI agent via simail.ai，显示名后加 " via SiMail"。信带 Auto-Submitted 头，让其他系统知道这是自动的。simail 不加追踪像素，也不加远程图片。

投递事件和抑制

投递、退信、投诉和拒绝事件来自发信网络，报告为 message.delivered、message.bounced、message.complained 和 message.rejected。硬退信和投诉会把地址加进抑制名单。如果一个组织 7 天硬退信率达到 2%，或投诉率达到 0.1%（至少 50 封之后），该组织的发送暂停（403 account_suspended，收信继续），直到人在控制台恢复。