Gmail Trigger

Trigger workflows on new Gmail emails

Overview

The Gmail Trigger node polls the Gmail API for new emails and starts the workflow when new messages are detected. It supports filtering by labels, sender, read status, and Gmail search queries. Uses timestamp-based deduplication with ID tracking to handle same-second collisions. Can return simplified metadata or full raw email content including headers, body text, HTML, and attachments. Requires Google OAuth2 credentials.

Category: Communication
Tool Name: gmail_trigger
Version: 1

Appearance: Icon: si-gmail | Color: #4285f4

Node Type

Trigger — polling (checks for new data on a schedule)

Input / Output

Direction	Port(s)
Input	None (trigger node)
Output	Output

Credentials

This tool requires Gmail OAuth2 credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Authentication	options	No	oAuth2	Authentication method to use.
				Options: oAuth2 (recommended), serviceAccount
Google Account	credential	No	—	Connect or select your Google account. (shown when Authentication is oAuth2)
Service Account Email	string	Yes	—	The email address of the Google service account. (shown when Authentication is serviceAccount)
Private Key	string	Yes	—	The private key from the service account JSON key file. (shown when Authentication is serviceAccount)
Event	options	No	messageReceived	Which event to listen for.
				Options: messageReceived
Simplify	boolean	No	true	Whether to return a simplified version of the response instead of the raw data. When true, returns metadata only (From, To, Subject, snippet). When false, returns the full email with headers, text, HTML, and attachment info.
Filters	collection	No	{}	Which emails should start the workflow. Every filter you set must match.
— Include Spam and Trash	boolean	No	false	Whether to include messages from SPAM and TRASH in the results.
— Include Drafts	boolean	No	false	Whether to include email drafts in the results.
— Label IDs	string	No	—	Comma-separated label IDs to filter by. Only messages matching all specified labels will be returned.
— Search	string	No	—	Gmail search query to filter messages. Uses the same syntax as the Gmail search box (e.g. “has:attachment”, “from:user@example.com”, “subject:invoice”).
— Read Status	options	No	unread	Filter emails by whether they have been read or not.
				Options: both (Unread and Read Emails), unread (Unread Emails Only), read (Read Emails Only)
— Sender	string	No	—	Sender name or email to filter by.
Options	collection	No	{}	Additional handling for the full-email output. (shown when Simplify is false)
— Attachment Prefix	string	No	attachment_	Prefix for the name of attachment data properties. An index starting with 0 will be appended.
— Download Attachments	boolean	No	false	Whether the email attachments will be included in the output.
Poll Interval	number	No	1	How often to check for new emails.
Poll Interval Unit	options	No	minutes	Unit for the poll interval.
				Options: seconds, minutes, hours

Output Data

Each new message becomes one output item. Every item carries _trigger (always gmail_polling) and _timestamp (when the poll ran). The rest of the shape depends on Simplify.

With Simplify on (the default), the item holds message metadata, resolved label names, and each requested header flattened to a top-level key using the header’s own name:

{
  "id": "18f2c1a9b0d4e5f6",
  "threadId": "18f2c1a9b0d4e5f6",
  "snippet": "Your invoice for August is attached",
  "sizeEstimate": 24518,
  "historyId": "552310",
  "internalDate": "1755248400000",
  "labels": [{ "id": "INBOX", "name": "INBOX" }],
  "From": "Billing <billing@example.com>",
  "To": "accounts@mycompany.com",
  "Cc": "",
  "Bcc": "",
  "Subject": "Invoice 4192",
  "_trigger": "gmail_polling",
  "_timestamp": "2026-08-15T09:01:00.000Z"
}

With Simplify off, the item holds the full message instead: id, threadId, labelIds, snippet, sizeEstimate, historyId, internalDate, headers (every header keyed by its lower-cased name), the convenience fields subject, from, to, cc, date, messageId and replyTo, the decoded text and html bodies, and attachments — one entry per attached file with filename, mimeType, size and attachmentId.

Reference values downstream by expression, e.g. {{ $json.Subject }} in simplified mode or {{ $json.subject }} in full mode.

Usage Examples

• Start a workflow when a new email arrives in Gmail
• Monitor a specific label for incoming support requests
• Trigger processing when emails from a specific sender arrive
• Watch for unread emails matching a search query
• Poll Gmail every 5 minutes for new messages with attachments

Example Configuration

Watch for any new unread mail, simplified output:

{
  "type": "gmail_trigger",
  "parameters": {
    "event": "messageReceived",
    "simple": true,
    "pollInterval": 5,
    "pollIntervalUnit": "minutes"
  }
}

Watch one sender for invoices:

{
  "type": "gmail_trigger",
  "parameters": {
    "event": "messageReceived",
    "simple": true,
    "pollInterval": 15,
    "pollIntervalUnit": "minutes",
    "filters": {
      "includeSpamTrash": false,
      "includeDrafts": false,
      "readStatus": "unread",
      "sender": "billing@supplier.com",
      "q": "subject:invoice"
    }
  }
}

Watch specific labels with a Gmail search query:

{
  "type": "gmail_trigger",
  "parameters": {
    "event": "messageReceived",
    "simple": true,
    "pollInterval": 30,
    "pollIntervalUnit": "seconds",
    "filters": {
      "labelIds": "INBOX,IMPORTANT",
      "q": "subject:invoice OR subject:receipt",
      "readStatus": "unread"
    }
  }
}

Return the full email, including body and attachment details:

{
  "type": "gmail_trigger",
  "parameters": {
    "event": "messageReceived",
    "simple": false,
    "pollInterval": 2,
    "pollIntervalUnit": "minutes",
    "filters": {
      "readStatus": "unread",
      "q": "has:attachment"
    },
    "options": {
      "dataPropertyAttachmentsPrefixName": "attachment_",
      "downloadAttachments": true
    }
  }
}

Trigger Behavior

• Activation: Polling starts when the workflow is activated. There is no poll at the moment of activation — the first check runs one full interval later.
• Schedule: The trigger polls for new data based on the configured polling interval.
• State: Maintains internal state (the date of the newest message seen, plus the IDs at that boundary) so each poll returns only mail that arrived since the last check.
• First Run: The first poll records the current position and returns no items, so activating the workflow never replays your mailbox.
• Testing: Running the node from the editor emits a single sample message so you can build the rest of the workflow; real mail arrives only while the workflow is activated.

Tips

The Gmail Trigger polls your Gmail inbox for new messages at a configurable interval. Filter emails by labels, sender, read status, or Gmail search queries. In simple mode, returns metadata (From, To, Subject, snippet). In full mode, returns the complete email with headers, text, HTML body, and optionally attachments. On first activation, it establishes a baseline and will only trigger on emails received after that point.

Key Relationships

• simple controls options availability: when simple is true, the options parameter is hidden and unavailable.
• Filter combination: all specified filter criteria work together with AND logic (all must match).
• Gmail search syntax: the q field uses the same search syntax available in Gmail’s web interface.
• Label IDs: use comma-separated Gmail label IDs (like “INBOX,IMPORTANT”) rather than label names.

Notes

• Messages carrying the SENT label but not INBOX are skipped, so replies you send yourself do not re-trigger the workflow.