API 参考

草稿

创建、修改、列出、删除并发送草稿；给草稿上传外发附件；以及在组织范围内列出草稿。

docs.simail.ai/zh/api/drafts

草稿是 agent 在发送前准备的一封信。发送草稿会经过与发信相同的检查。

{
  "draft_id": "drf_01JZX4D0E1F2G3H4J5K6M7N8P9",
  "inbox_id": "shop-helper@simail.email",
  "thread_id": "thr_01JZX4A1B2C3D4E5F6G7H8J9K0",
  "in_reply_to": "msg_01JZX4A9B8C7D6E5F4G3H2J1K0",
  "to": ["ada@example.com"],
  "cc": [],
  "bcc": [],
  "subject": "Re: Where is my order?",
  "text": "Hi Ada, it shipped today.",
  "attachments": [],
  "labels": [],
  "send_at": null,
  "status": "draft",
  "send_id": null,
  "created_at": "2026-10-18T17:04:00Z",
  "updated_at": "2026-10-18T17:04:00Z"
}

status 在发出之前是 draft，之后跟随这次发送：scheduled、pending_approval、sent、blocked、rejected、expired 或 cancelled。send_id 把它连到发送状态。

列出草稿

GET/v0/inboxes/{inbox_id}/drafts

权限 message_read。分页；返回 { count, limit, next_page_token?, drafts }。

创建草稿

POST/v0/inboxes/{inbox_id}/drafts

权限 draft_write。正文是发信字段（to、cc、bcc、subject、text、html、attachments、labels、send_at），加上 in_reply_to（一个 message_id）就会变成回复。回复草稿和直接回复一样，收件人取自原信。支持 Idempotency-Key。

读取、修改或删除草稿

GET/v0/inboxes/{inbox_id}/drafts/{draft_id}

PATCH/v0/inboxes/{inbox_id}/drafts/{draft_id}

DELETE/v0/inboxes/{inbox_id}/drafts/{draft_id}

GET 需要 message_read；PATCH 和 DELETE 需要 draft_write。只有 draft 状态的草稿可以修改。删除已经提交的草稿（已定时或正在等审批）会先取消这次发送；如果已经在发出或已是终态，删除返回 409 conflict，草稿保留。

上传附件

POST/v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments

权限 draft_write。正文 { "filename", "content_type", "content" }，其中 content 是 base64（请求正文最大 5 MiB）。返回 { "attachment_id", "filename", "size", "content_type" }。一份草稿最多 32 个附件，原始附件数据合计大约 3.5 MiB。外发附件必须被你的发信策略允许。

GET/v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}

权限 message_read。返回一次性下载链接，和消息附件一样。

发送草稿

POST/v0/inboxes/{inbox_id}/drafts/{draft_id}/send

权限 message_send。必须带 Idempotency-Key。 响应和错误与发信相同。发布 draft.submitted。

组织范围内的草稿

GET /v0/drafts · GET /v0/drafts/{draft_id} · GET /v0/drafts/{draft_id}/attachments/{attachment_id}

权限 message_read，覆盖你的 key 作用域内的每一个邮箱。pod 变体在 /v0/pods/{pod_id}/drafts 下。

MCP：create_draft、update_draft、get_draft、list_drafts、delete_draft 和 send_draft（必须带 idempotency_key）。