Gmail:Search Emails
Controlled node
Overview
Find Gmail messages with a search query.
Search messages in the connected Gmail account. Use Gmail search expressions to narrow the results.
Inputs
| Input | Type | Description |
|---|---|---|
| run | Event | Triggers this operation. |
| query | Text | Gmail search expression, such as is:unread has:attachment. Leave unset to fetch without a search filter. |
| limit | Number | Maximum messages to return. Use a positive integer up to 500. Defaults to 100. |
| offset | Number | Number of matching messages to skip. Use a non-negative integer. Defaults to 0. |
Properties
| Setting | Type | Description |
|---|---|---|
| connections | Connection | Select an authenticated Gmail connection from this project in the properties panel. |
Outputs
| Output | Type | Description |
|---|---|---|
| messages | Data | Array of message objects. Validation failures can return error text; retrieval failures can return an empty array. |
| done | Event | Fires when the node returns, including when it returns an error result. Check the data output before continuing. |
Message data
Each message contains id, threadId, subject, sentBy, sentTime, to, cc, bcc, snippet, status, isRead, plain and html. Recipient fields are arrays of email addresses. Use id when replying, marking a message as read or fetching attachments; it is not the thread ID.
Pagination and errors
Each run returns up to limit messages after skipping offset. There is no page-token input in the editor. Mailboxes can change between runs, so keep message IDs if you need to avoid processing a message twice.
Check that messages is an array before iterating. An empty array is not proof that the query succeeded; review workflow logs if results are unexpectedly empty.
Example
Select the connection, set limit to 50 and offset to 0, and enter a query. Connect Start to run. After checking the result, pass messages to For Each → object and trigger its run from done. Use Get Value on each element to read fields such as id or subject.
To request the next slice, use offset: 50 with the same limit.