> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail: New Email Matching Search

Triggers when a new email matching a Gmail search query is received. Supports Gmail search operators like 'from:sender@example.com subject:invoice'. Polls your real Gmail inbox via OAuth.

Trigger Communications

Triggers when a new email matching a Gmail search query is received. Supports Gmail search operators like 'from:sender@example.com subject:invoice'. Polls your real Gmail inbox via OAuth.

## At a Glance

| Field | Value |
| --- | --- |
| Trigger ID | `gmail-new-email-matching-search` |
| Category | Communications |
| Tags | `email`, `gmail`, `communication`, `notification`, `search`, `filter` |

## Trigger Configuration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | `string` | No | Gmail search query using standard search operators \(e.g. 'from:sender@example.com subject:invoice'\) |
| `labels` | `array` | No | Only trigger for emails with these labels \(optional\) |

## Trigger Result

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `triggeredAt` | `string` | Yes | Timestamp when the event was received \(UTC, RFC3339 format\) |
| `from` | `string` | No | Sender \(From header value\) |
| `to` | `string` | No | Recipients \(To header value\) |
| `subject` | `string` | No | Email subject line |
| `text` | `string` | No | Plain text body of the email |
| `snippet` | `string` | No | Short text preview of the email |
| `threadId` | `string` | No | Gmail thread ID |
| `labelIds` | `array` | No | Gmail label IDs on the message |

## Workflow Root Example

```json
{
  "nodes": {
    "root": {
      "type": "gmail-new-email-matching-search",
      "payload": {
        "q": "example-q",
        "labels": []
      },
      "children": [
        "log_event"
      ]
    },
    "log_event": {
      "type": "log",
      "payload": {
        "message": "Triggered at {{$trigger.triggeredAt}}"
      },
      "children": []
    }
  }
}
```

**Reference trigger output**

Downstream nodes can use `{{$trigger.triggeredAt}}` and any result fields listed above. Event triggers usually expose the raw source payload under a field such as `event`, `body`, `trade`, or `raw`.