API 参考

发信

发送新邮件、回复、回复全部或转发。调用幂等，会对照你的发信策略检查，规则要求时会等待审批。

docs.simail.ai/zh/api/send-message

POST/v0/inboxes/{inbox_id}/messages/send

权限 message_send。必须带 Idempotency-Key。 邮件提交给放行服务，它执行下面的检查，并返回一个 send_id，你可以在 GET /v0/sends/{send_id} 跟踪。指南：起草与发信。

curl -s https://api.simail.ai/v0/inboxes/shop-helper@simail.email/messages/send \
  -H "Authorization: Bearer $SIMAIL_API_KEY" \
  -H "Idempotency-Key: order-1042-shipped" \
  -H "Content-Type: application/json" \
  -d '{ "to": ["ada@example.com"], "subject": "Your order shipped", "text": "Hi Ada, your order #1042 shipped today.", "labels": ["orders"] }'

发出之前的检查

放行服务按顺序执行这些检查。第一个失败的检查决定响应。

#	检查	失败时返回
1	正文合法，且带有 `Idempotency-Key`	400
2	key 有效、已认领、作用域覆盖这个邮箱，并且有 `message_send`	404 / 403
3	组织可以发信（没有暂停）	403
4	同一个 `Idempotency-Key` 没有配过不同的正文	409
5	邮件头字段里没有 CR、LF、NUL 或控制字符	422
6	邮件没有超过大小上限（含编码 5 MiB，附件最多 32 个）	413
7	线程没有被人上锁，邮箱也没有暂停	423
8	确定性检查和你的发信策略：发件人、收件人、内容、拦截名单、抑制名单、循环	422
9	同一封信尚未在去重时间窗内发出过	409
10	不会超过今天的限额	429
11	全平台没有暂停发信	503
12	审批规则（首次联系、风险标记）决定这封信是否要等人（`pending_approval`）	202

第 2 步对作用域之外的邮箱回答 404 not_found，对未认领或缺少 message_send 的 key 回答 403 missing_permission 或 403 claim_required。即使状态已经是 sent，投递结果也要等之后的 message.delivered 或 message.bounced 事件。

参数

路径

名称	类型	说明
`inbox_id`	string，必填	发信邮箱（它的地址）

请求头

名称	类型	说明
`Authorization`	`Bearer <key>`，必填	一把对该邮箱有 `message_send` 的 key
`Idempotency-Key`	string，必填，最多 255 个字符	你为这次发送定的稳定 ID；重试时重复使用它

正文

名称	类型	说明
`to`	string[]，必填	收件人；`to`、`cc`、`bcc` 合计最多 50 个地址
`cc`	string[]
`bcc`	string[]	仅当你的策略允许 `bcc`
`subject`	string
`text`	string	纯文本正文；发送 `text`、`html` 或两者（始终发送 `text`）
`html`	string	HTML 正文；不会添加远程图片或跟踪
`attachments`	object[]	`{ "filename", "content_type", "content" }`，其中 `content` 为 base64，或 `{ "draft_attachment_id" }`；最多 32 个，原始数据合计大约 3.5 MiB
`labels`	string[]	打在发出副本上的标签
`send_at`	ISO 8601	稍后发送，最多提前 30 天；大约在那个时间的 2 分钟内发出
`expected_recipients`	string[]	如果 simail 推导出的收件人与此不同，发送会被拦住（`expected_recipients_mismatch`）
`headers`	object	会被拒绝，除了 `X-Simail-Client-Ref`
`reply_to`	string	忽略：simail 会设置 Reply-To，让回复正确归入线程
`track_opens`	boolean	忽略：simail 从不跟踪打开或点击

响应

202 sent

{ "send_id": "out_01JZX4C0D1E2F3G4H5J6K7M8N9", "message_id": "msg_01JZX4C0D1E2F3G4H5J6K7M8NA", "thread_id": "thr_01JZX4C0D1E2F3G4H5J6K7M8NB", "status": "sent" }

status 为 sent（已交给邮件网络）、sending，或 scheduled（带 send_at）。

202 pending_approval

{ "send_id": "out_01JZX4C0D1E2F3G4H5J6K7M8NC", "thread_id": "thr_01JZX4C0D1E2F3G4H5J6K7M8ND", "status": "pending_approval", "flags": ["first_contact", "has_links"] }

由人决定。跟踪 GET /v0/sends/{send_id} 或 approval.decided 事件；不要重发。见审批与发信策略。

409 duplicate_send

同一封信已经在去重时间窗内从这个邮箱发出。不要重发。

409 idempotency_conflict

这个 Idempotency-Key 以前配过不同的正文。

413 message_too_large

带有 limit_bytes 和 estimated_bytes。删掉或缩小附件。

422 send_blocked

{
  "type": "https://docs.simail.ai/errors#send_blocked",
  "title": "SendBlockedError",
  "status": 422,
  "code": "send_blocked",
  "message": "The message contains a template placeholder.",
  "fix": "The pre-send check rejected this message; see `reasons`.",
  "retryable": false,
  "reasons": ["placeholder"],
  "request_id": "req_01JZX4C0D1E2F3G4H5J6K7M8NF"
}

reasons 列出每一项拦住发送的检查；见发信前检查。

423 thread_locked

人已经接管了这个线程。停下来，等 thread.unlocked。见人工接管。

429 daily_limit_exceeded

今天的限额用完了。等 Retry-After 之后，用同一个 Idempotency-Key 重试。

503 sending_paused

全平台暂停发信。稍后再用同一个 Idempotency-Key 重试。

POST/v0/inboxes/{inbox_id}/messages/{message_id}/reply

权限 message_send，必须带 Idempotency-Key。正文：text、html、attachments、labels、send_at、expected_recipients。收件人是原信的 From 地址（绝不是它的 Reply-To）；主题会加上 Re:，线程相关的头会替你设好。回复自动回复、退信或另一个 simail agent 会被拦住（loop_auto_reply）。

回复全部

POST/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all

和回复一样，再加上原信的 To 和 Cc，不含你自己的地址。传入 expected_recipients，确保回复不会变成群发。

POST/v0/inboxes/{inbox_id}/messages/{message_id}/forward

权限 message_send，必须带 Idempotency-Key。正文：to、cc、bcc、text（你的附言）、labels。主题会加上 Fwd:；原信附件会一并带上，所以大邮件可能超过 5 MiB 上限（413 message_too_large；改为不带附件转发）。转发给新收件人在审批规则里算首次联系。

在 MCP 里

send_message、reply_to_message、reply_all_message 和 forward_message 接受同样的字段，外加必填的 idempotency_key。见 MCP。