Gmail Trigger
Type ID: gmailTrigger · Kind: Trigger · Trigger style: poll · Trace: CHAIN
Polls the Gmail API on an interval and triggers the workflow when new emails matching the configured filters are received.
Credentials
Gmail
Properties
| Property | Key | Type | Required | Default | Possible values | Shown when |
|---|---|---|---|---|---|---|
| Poll Interval | pollIntervalMs | number | Yes | 60000 | Interval in milliseconds to check for new emails (minimum 60 seconds) | Always |
| Event | event | options | Yes | messageReceived | messageReceived (Message Received) | Always |
| Output | output | options | No | simple | simple (Simplified), raw (Raw), fields (Select Included Fields) | Always |
| Fields | fields | checkbox | Yes | [] | id, threadId, labelIds, snippet, historyId, internalDate, payload, sizeEstimate, raw, classificationLabelValues | output = fields |
| Filters | filters | object | No | {} | See sub-table | Always |
| Options | options | object | No | {} | See sub-table | Always |
filters (object)
| Property | Key | Type | Required | Default | Possible values |
|---|---|---|---|---|---|
| Read Status | readStatus | options | No | unread | both (Unread and read messages), unread (Unread messages only), read (Read messages only) |
| Sender | sender | string | No | '' | Email address to match (from:) |
| Subject Contains | subjectContains | string | No | '' | Text the subject must contain (subject:) |
| Has Attachment | hasAttachment | boolean | No | false | Only return messages with attachments |
| Label | label | string | No | INBOX | Gmail label, e.g. INBOX, SENT, IMPORTANT |
options (object)
| Property | Key | Type | Required | Default | Possible values |
|---|---|---|---|---|---|
| Mark as Read | markAsRead | boolean | No | false | Mark emails as read after triggering |
| Max Emails Per Poll | maxEmails | number | No | 10 | Max emails processed per poll (clamped to 1-50) |
Notes
Fires via poll(). Uses a stateless time window: each poll queries emails received between now - pollIntervalMs and now. A Gmail search query is assembled from the filters — is:unread/is:read (from readStatus), label:<label>, from:<sender>, subject:<subjectContains>, has:attachment, and a date bound after:YYYY/MM/DD derived from the window start. Because Gmail's after: filter is date-granular, each fetched message's internalDate is re-checked against the precise fromTime and messages older than the window are skipped.
Message detail format follows output: raw requests format=raw; simple and fields request format=full. simple runs each message through simplifyMessage; fields keeps only the selected keys; raw returns the full API object. If markAsRead is set, the UNREAD label is removed from each emitted message (failures are logged, not fatal).
When no messages fall within the window (before or after the precise time check) the node returns null and the workflow does not trigger. Otherwise it emits one item whose json contains emails (array) and a summary with count, subjects, senders, pollInterval, and polledAt.
The trigger() method (manual/test runs) delegates to poll(). When used as a non-root internal node, execute() instead returns a wait item on the poll channel so the wait orchestrator initiates polling.