# 事件类型

Source: https://docs.simail.ai/zh/event-types/

> 每一种 simail 事件、轮询与 webhook 和 WebSocket 共用的薄载荷，以及哪些事件会唤醒 agent。

## 载荷

载荷是**薄的**，每个通道都一样（[轮询](/zh/events/)、[webhook](/zh/webhooks/)、[WebSocket](/zh/realtime/)）。它们从不包含主题、正文或附件名；需要内容时用你的 key 去取那封信（扣留的信仍然只有元数据）。

```json
{
  "event_id": "evt_…",
  "event_type": "message.received",
  "occurred_at": "2026-10-18T17:02:12Z",
  "organization_id": "org_…",
  "pod_id": "pod_…",
  "inbox_id": "shop-helper@simail.email",
  "thread_id": "thr_…",
  "message_id": "msg_…",
  "data": { "from": "ada@example.com", "labels": ["received", "unread"], "held": false, "classification": "normal", "wake": true }
}
```

| 字段 | 说明 |
|---|---|
| `event_id` | 唯一；用它去重（webhook 把它放在 `webhook-id`） |
| `occurred_at` | ISO 8601，UTC |
| `pod_id`、`inbox_id`、`thread_id`、`message_id` | 事件关于该对象时才出现 |
| `data` | 小的、随类型变化的字段（见下） |

## 类型

| 类型 | 何时 | `data` |
|---|---|---|
| `message.received` | 一封信已存入 | `from`、`labels`、`held`、`classification`、`wake` |
| `message.received.spam` | 被标成垃圾的信已存入 | 同上 |
| `message.received.blocked` | 带 `blocked` 标签的信已存入 | 同上 |
| `message.held` | 一封信被扣留给人审（只有元数据） | `from`、`hold_reasons` |
| `message.released` | 人放行了一封扣留的信 | `from`、`wake` |
| `message.sent` | 外发信已交给邮件网络 | `send_id` |
| `message.delivered` | 收件人的服务器接受了它 | `recipient` |
| `message.bounced` | 退信 | `recipient`、`bounce_type`（`hard` 或 `soft`） |
| `message.complained` | 收件人把它标成垃圾 | `recipient` |
| `message.rejected` | 发信网络拒绝了它 | `recipient` |
| `draft.submitted` | 草稿已提交发送 | `draft_id`、`send_id` |
| `approval.requested` | 一次发送在等审批 | `approval_id`、`send_id`、`flags` |
| `approval.decided` | 审批人批准或拒绝，或已过期 | `approval_id`、`send_id`、`decision` |
| `send.blocked` | 一次发送被拦住 | `send_id`、`reasons` |
| `send.cancelled` | 定时或待发的发送被取消 | `send_id` |
| `send.deferred` | 发送在等待（暂停、锁定或每日上限）并会重试 | `send_id`、`reason` |
| `thread.locked` | 人接管了一个线程 | |
| `thread.unlocked` | 人交还了它 | |
| `label.added` | 加了一个标签 | `label` |
| `label.removed` | 去掉了一个标签 | `label` |
| `inbox.digest` | 没有唤醒 agent 的事件的每日计数 | `counts` |
| `inbox.created` | 建了一个邮箱 | |
| `inbox.deleted` | 删了一个邮箱 | |
| `org.suspended` | 该组织的发送被暂停 | `reason` |
| `org.resumed` | 发送恢复 | |

## 唤醒 agent

每个 `message.received`（以及 `message.released`）事件都有 `data.wake`。邮件属于你参与的线程、来自该邮箱的联系人、或命中收信允许名单时，它为 `true`。陌生人的信唤醒 agent 有预算：每个邮箱每天（`inbound.wake.stranger_daily`，默认 50）以及每个发件人每小时（`inbound.wake.per_sender_hourly`，默认 5）。超过之后，事件仍会存下并由 `GET /v0/events` 返回，但 webhook 和 WebSocket 会跳过，除非订阅设置了 `include_non_wake: true`。每天一条 `inbox.digest` 报告被跳过的数量。扣留的信从不唤醒。

这样，一波邮件不会变成一波模型调用。