Gmail Search Emails

Controlled node

Overview

Searches Gmail messages using an advanced query syntax and returns the matching messages. This node supports Gmail's standard search operators (such as from:, to:, subject:, has:attachment, etc.) to filter messages precisely.

Message Limit

There is a hard limit of 500 messages that can be fetched in a single search operation. Use the limit and offset inputs to paginate through larger result sets.

Inputs

Input	Type	Description	Default
Run	Event	Triggers the email search operation.	-
Query	Text	The Gmail search query string. Supports Gmail advanced search operators like from:, to:, subject:, has:attachment, in:inbox, is:unread, etc.	-
Limit	Number	The maximum number of messages to return. Cannot exceed 500.	100
Offset	Number	The number of messages to skip (for pagination).	0
Connections	Connection	The Gmail connection to use for the search. Must be configured in the project settings.	-

Outputs

Output	Type	Description
Done	Event	Fires when the search operation has completed successfully.
Messages	Data	An array of message objects matching the search criteria. Each object contains message metadata including id, threadId, snippet, and payload details.

Runtime Behavior and Defaults

When the Run event fires, the node validates that the sum of limit and offset does not exceed 500. If the limit exceeds this maximum, the node returns an error message instead of results.

The node uses the authenticated Gmail connection to execute the search against the user's mailbox. The query string is passed directly to Gmail's search API, supporting all standard Gmail search syntax including boolean operators, date ranges, and label filters.

If no messages match the query, the Messages output will return an empty array, and the Done event will still fire successfully.

Example Usage

To search for unread emails from a specific sender and process the results:

1. Connect a Start node or trigger event to the Run input.
2. Set the Query input to: from:boss@company.com is:unread
3. Set Limit to 50 to retrieve up to 50 matching messages.
4. Connect the Messages output to a node that iterates through the array (such as a For Each node) to process each email individually.
5. Use the Done event to trigger subsequent workflow steps after all messages have been retrieved.

For pagination, connect the output of a Batch Index node or calculate an offset value to skip previously fetched messages in subsequent search operations.