# Gmail：收到新邮件

Source: https://openflow.run/zh-cn/docs/nodes/poll/
Language: zh-CN
Product version: 0.1.0-beta.77

在“触发器”页签选择 Gmail 的具体事件，用新邮件启动后续处理。

在添加面板打开“触发器”页签，从应用列表选择 Gmail，再选择“收到新邮件”。加入画布的是这个具体事件，其账号、配置字段和输出都由所选目录定义决定。

## 选择事件

选择 Gmail 账号，设置发件人、标签、已读状态或 Gmail 搜索条件。本例每五分钟检查一次新邮件。

从应用目录选择 Gmail 的“收到新邮件”事件。本例每五分钟检查新邮件，为接收的事件启动后续处理。

**输入**
选择 Gmail 账号，并配置所选事件的查询字段。

**预期结果**
工作流发布并启用后，符合条件的 Gmail 新邮件可以创建运行。

**运行前准备**
授权 Gmail 账号，检查事件配置和后台服务，再发布并启用工作流。

[下载工作流](https://openflow.run/docs/examples/poll-inbox.openflow.json)

使用 CLI/MCP 编排时，同一个目录事件可以这样创建。这里的 `poll` 表示底层检测方式，不是添加面板中的独立选项：

```json
{
  "op": "node.add", "as": "inbox", "type": "poll", "name": "New inbox messages",
  "config": {
    "key": "gmail.on_message_received",
    "connectionId": "CONNECTION_ID",
    "schedule": [{ "type": "every", "unit": "minute", "value": 5 }]
  }
}
```

## 配置与事件输出

事件配置在运行创建之前就会使用。只能采用当前 schema 支持的静态输入来源，不能读取即将启动的运行中的下游结果。

Beta 77 的事件定义提供以下配置字段：

| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| `labelNamesOrIds` | `[]` | 按标签名称或 ID 筛选，邮件必须包含列出的所有标签。 |
| `readStatus` | `All` | 选择 `Read`、`Unread` 或 `All`。 |
| `search` | `""` | 使用 Gmail 搜索语法筛选邮件，例如按主题查询。 |
| `sender` | `""` | 按发件人地址或名称筛选。 |
| `includeDrafts` | `false` | 是否包含草稿。 |
| `includeSpamAndTrash` | `false` | 是否包含垃圾邮件和已删除邮件。 |
| `maxMessagesPerPoll` | `25` | 每次检查最多读取的邮件数，范围为 1–100。 |

输出端口是 `events`，值为邮件事件数组。数组中的每项包含以下字段，后续节点应绑定这个端口处理邮件：

| 字段 | 类型 | 内容 |
| --- | --- | --- |
| `messageId`、`threadId` | string | 邮件 ID 和会话 ID。 |
| `historyId` | string 或 null | Gmail 历史记录 ID。 |
| `labelIds` | string\[\] | 邮件标签 ID。 |
| `subject`、`sender`、`to` | string | 主题、发件人和收件人。 |
| `messageTimestamp` | string | 邮件时间。 |

## 发布与验证

授权 Gmail 账号、检查配置，再发布并启用工作流。部署端负责定期检查事件和保存投递进度。符合条件的新邮件出现后，系统可以创建运行。

用真实邮件测试，并查看生成的运行记录。草稿模拟不能证明账号权限和后台检测已经就绪。变更账号或范围后，部署端应停止使用旧绑定。事件工作进程的恢复遵循部署契约，不使用普通任务节点的重试设置。

## 资料来源

*   [docs/control/trigger-permissions.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/control/trigger-permissions.md)
*   [docs/control/contracts/control-api.md](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/docs/control/contracts/control-api.md#trigger-configuration-and-outputs)
*   [packages/open-flow/src/workbench/browser/runtime/stores/triggerStore.ts](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/packages/open-flow/src/workbench/browser/runtime/stores/triggerStore.ts)
*   [packages/open-flow/src/trigger/providers/catalog.generated.json](https://github.com/oomol-lab/open-flow/blob/e25a738d170322734572a0b8a1323cb00b9d355a/packages/open-flow/src/trigger/providers/catalog.generated.json)