# Gmail：收到新郵件

Source: https://openflow.run/zh-tw/docs/nodes/poll/
Language: zh-TW
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)