# Gmail: New Message Received

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

Choose Gmail’s named event in the Triggers tab and process new mail.

In Add Node, open **Triggers**, choose **Gmail** from the app list, and select **New Message Received**. That event is the item added to the canvas. Its account, fields, and outputs come from the selected catalog definition.

## Select the event

Choose the Gmail account and set sender, label, read-status, or Gmail search filters. This example checks for new mail every five minutes.

Choose Gmail’s New Message Received event from the app catalog. This example checks for new mail every five minutes and starts the next step for accepted events.

**Input**
Choose the Gmail account and configure the selected event’s query fields.

**Expected result**
A matching new Gmail message can create a Run after the Flow is published and enabled.

**Before running**
Authorize the Gmail account, check the event configuration and background service, then publish and enable the Flow.

[Download workflow](https://openflow.run/docs/examples/poll-inbox.openflow.json)

For CLI/MCP authoring, the same catalog event uses the following request. Here `poll` describes its detection mechanism, not a separate option in Add Node:

```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 }]
  }
}
```

## Configuration and event outputs

The event configuration is resolved before a Run exists. Use the static input sources its current schema supports; it cannot read downstream results from the Run it will start.

The Beta 77 event definition provides these configuration fields:

| Field | Default | Purpose |
| --- | --- | --- |
| `labelNamesOrIds` | `[]` | Match messages carrying all listed labels, by name or ID. |
| `readStatus` | `All` | Select `Read`, `Unread`, or `All`. |
| `search` | `""` | Filter using Gmail search syntax, including subject queries. |
| `sender` | `""` | Match a sender address or name. |
| `includeDrafts` | `false` | Include draft messages. |
| `includeSpamAndTrash` | `false` | Include messages in spam and trash. |
| `maxMessagesPerPoll` | `25` | Maximum messages per check, from 1 to 100. |

The output port is `events`, an array of mail events. Bind downstream inputs to this port. Each item contains:

| Field | Type | Content |
| --- | --- | --- |
| `messageId`, `threadId` | string | Message and thread IDs. |
| `historyId` | string or null | Gmail history ID. |
| `labelIds` | string\[\] | Message label IDs. |
| `subject`, `sender`, `to` | string | Subject, sender, and recipient. |
| `messageTimestamp` | string | Message timestamp. |

## Publish and verify

Authorize the Gmail account, review the configuration, then publish and enable the Flow. The deployment performs the event checks and retains delivery progress. A matching new email can then create a Run.

Test with a real message and inspect that Run. Draft simulation does not prove that account access or background polling is ready. After changing the account or scope, the deployment must stop using the obsolete binding. The event worker’s recovery follows the deployment contract rather than ordinary Task retry settings.

## Sources

*   [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)