# 发信

Source: https://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}`](/zh/api/sends/) 跟踪。指南：[起草与发信](/zh/sending/)。

```sh
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

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

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

### 202 pending_approval

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

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

### 409 duplicate_send

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

### 409 idempotency_conflict

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

### 413 message_too_large

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

### 422 send_blocked

```json
{
  "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` 列出每一项拦住发送的检查；见[发信前检查](/zh/sending/)。

### 423 thread_locked

人已经接管了这个线程。停下来，等 `thread.unlocked`。见[人工接管](/zh/takeover/)。

### 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](/zh/mcp/)。