Gmail: Search Messages

Plugin ID: eca_gmail_search_messages

Available since: 1.0.0

Advanced email search using Gmail's query syntax with support for filtering by sender, date, labels, keywords, and attachments.

Fields

    <ul>
      <li><strong>from:user@example.com</strong> - Messages from specific sender</li>
      <li><strong>to:me</strong> - Messages sent to you</li>
      <li><strong>subject:"urgent"</strong> - Messages with "urgent" in subject</li>
      <li><strong>has:attachment</strong> - Messages with attachments</li>
      <li><strong>after:2024/01/01</strong> - Messages after specific date</li>
      <li><strong>before:2024/12/31</strong> - Messages before specific date</li>
      <li><strong>in:inbox</strong> - Messages in inbox</li>
      <li><strong>is:unread</strong> - Unread messages</li>
      <li><strong>label:important</strong> - Messages with "important" label</li>
      <li><strong>filename:pdf</strong> - Messages with PDF attachments</li>
    </ul>

Authentication Type — config key: auth_type

Choose between API Client (OAuth2) or Service Account authentication.

Type: select · Required: yes · Default: api_client

Allowed values: api_client, service_account

Authentication Source — config key: auth_from

Choose whether to select authentication directly or use a token for dynamic selection.

Type: select · Required: yes · Default: direct

Allowed values: direct, token

API Client — config key: api_client_id

Search and select an API Client for OAuth2 authentication.

Type: textfield · Required: no · Default: empty string

Service Account — config key: service_account_id

Search and select a Service Account for server-to-server authentication.

Type: textfield · Required: no · Default: empty string

Client ID from Token — config key: auth_client_from_token

Token that resolves to a client ID (e.g., [user:field_google_client_id]). The token should contain just the client ID, not the auth type prefix.
This field supports tokens.

Type: textfield · Required: no · Default: empty string

Search Query — config key: search_query

Gmail search query using advanced syntax. Examples: "from:user@example.com", "has:attachment", "after:2024/01/01", "in:inbox label:important". Leave empty to list all messages. Supports token replacement.
This field supports tokens.

Type: textfield · Required: no · Default: empty string

Maximum Results — config key: max_results

Maximum number of messages to return (1-500). Default: 10.

Type: number · Required: no · Default: 10

Page Token — config key: page_token

Token for pagination. Use next_page_token from previous search results to get more messages. Supports token replacement.
This field supports tokens.

Type: textfield · Required: no · Default: empty string

Label IDs — config key: label_ids

Optional comma-separated list of label IDs to filter by (e.g., "INBOX,STARRED"). Supports token replacement.
This field supports tokens.

Type: textfield · Required: no · Default: empty string

Search Results Token Name — config key: search_token_name

Optional token name to store search results. Accessible as [token_name:messages:0:id], [token_name:total_estimated], [token_name:next_page_token], etc.

Type: textfield · Required: no · Default: empty string