New Email
trigger.gmail_new_email
TriggerEmailconnection requiredruns in-engine
Polls Gmail messages.list on an interval; one run per new message.
Start a run for each new email matching a Gmail search (polled).
Connection
- Required
- Yes — the node will not save without one
- Auth type
- OAuth 2.0
- Providers
- Gmail
- Secret shape
- {"client_id", "client_secret", "refresh_token"}
- Resolved by
- config.connection_id, else node.connection_id
Configuration
3 fields, none required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.
| Field | Type | Required | Default | Constraints | Example |
|---|---|---|---|---|---|
query Gmail search, e.g. in:inbox, label:leads, from:boss@x.com has:attachment. A bare word matches the subject AND body (there is no body: operator); combine with OR, e.g. `invoice OR receipt`. | string | No | in:inbox | — | — |
poll_interval_sec How often to check (30-86400 seconds). | number | No | 60 | 30–86400 | — |
mark_as_read Remove the UNREAD label once the run has been started. | boolean | No | false | — | — |
Example configuration
Every value below is the contract’s own example or default — nothing invented.
{
"mark_as_read": false,
"poll_interval_sec": 60,
"query": "in:inbox"
}Output
One shape.
| Field | Type | Example |
|---|---|---|
message_id | string | — |
thread_id | string | — |
from | string | Ada <ada@example.com> |
to | string | — |
subject | string | — |
snippet First ~100 chars, as Gmail shows it. | string | — |
body Plain-text body (HTML stripped when no text part). | string | — |
date The Date header. | string | — |
internal_date Receive time, epoch milliseconds. | number | — |
label_ids | array | — |
cc | string | — |
bcc | string | — |
reply_to The Reply-To header; prefer it over `from` when replying. | string | — |
rfc_message_id The RFC 822 Message-ID header. | string | — |
in_reply_to The In-Reply-To header, when this message is itself a reply. | string | — |
references The References header. | string | — |
history_id | string | — |
size_estimate Gmail's estimated size in bytes. | number | — |
attachments Attachment descriptors; fetch bytes with gmail.get_attachment. | array | — |
{
"attachments": [],
"bcc": "",
"body": "",
"cc": "",
"date": "",
"from": "Ada <ada@example.com>",
"history_id": "",
"in_reply_to": "",
"internal_date": 0,
"label_ids": [],
"message_id": "",
"references": "",
"reply_to": "",
"rfc_message_id": "",
"size_estimate": 0,
"snippet": "",
"subject": "",
"thread_id": "",
"to": ""
}Notes
- Existing mail is never replayed: the first poll after publish only sets the cursor.
- Runs are idempotent per message id — a re-poll cannot start a second run.
Templates that use Gmail
Solutions with Gmail
See New Email run in a workflow.
In a technical demo we add the Gmail connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.