<!-- BusyBot node reference — https://busybot.net/tools/gmail-trigger/ -->

> Node: Gmail Trigger (`gmail_trigger`) · Polling trigger · v1
> Category: Communication · Credentials: Gmail OAuth2 (`gmailOAuth2`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/gmail-oauth2/) 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:

```json
{
  "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:

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

Watch one sender for invoices:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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.