Search Messages

gmail.search

ActionEmailconnection required

Calls messages.list (paged) then messages.get for each hit.

Search a mailbox and return the matching messages (newest first).

Ask about Gmail All Gmail nodes Provider API docs ↗

Connection

Required: Yes — the node will not save without one
Auth type: OAuth 2.0
Providers: Gmail
Secret shape: {"client_id", "client_secret", "refresh_token"}
Resolved by: config.connection_id, else node.connection_id

Configuration

2 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

Field	Type	Required	Default	Constraints	Example
query Gmail search syntax, e.g. from:finance@acme.com newer_than:7d has:attachment. A bare word matches the subject AND body (there is no body: operator).	string	Yes	—	—	—
limit Maximum messages to return (default 25, cap 200).	number	No	25	≥ 1	—

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "limit": 25
}

Output

One shape.

results

Field	Type	Example
ok	boolean	—
query The Gmail query that was run.	string	—
count How many messages were returned.	number	—
truncated True when the limit cut the result short.	boolean	—
message_ids Just the ids, in the same order.	array	—
messages Full envelopes, newest first.	array	—
messages[].message_id Gmail's message id (not the RFC Message-ID).	string	—
messages[].thread_id Pass to gmail.reply / gmail.send to stay in the thread.	string	—
messages[].from	string	Ada <ada@example.com>
messages[].to	string	—
messages[].cc	string	—
messages[].bcc	string	—
messages[].reply_to The Reply-To header — where a reply must actually go.	string	—
messages[].subject	string	—
messages[].date The Date header.	string	—
messages[].snippet First ~100 chars, as Gmail shows it.	string	—
messages[].body Plain-text body (HTML stripped when no text part).	string	—
messages[].internal_date Receive time, epoch milliseconds.	number	—
messages[].label_ids	array	—
messages[].rfc_message_id The RFC 822 Message-ID, for In-Reply-To.	string	—
messages[].in_reply_to	string	—
messages[].references	string	—
messages[].history_id	string	—
messages[].size_estimate Gmail's estimated message size in bytes.	number	—
messages[].attachments One entry per attached file.	array	—
messages[].attachments[].filename	string	—
messages[].attachments[].mime_type	string	—
messages[].attachments[].size	number	—
messages[].attachments[].attachment_id Feed to gmail.get_attachment.	string	—
messages[].attachments[].part_id	string	—

{
  "count": 0,
  "message_ids": [],
  "messages": [
    {
      "attachments": [
        {
          "attachment_id": "",
          "filename": "",
          "mime_type": "",
          "part_id": "",
          "size": 0
        }
      ],
      "bcc": "",
      "body": "",
      "cc": "",
      "date": "",
      "from": "Ada <ada@example.com>",
      "history_id": "",
      "in_reply_to": "",
      "internal_date": 0,
      "label_ids": [],
      "message_id": "",
      "references": "",
      "reply_to": "",
      "rfc_message_id": "",
      "size_estimate": 0,
      "snippet": "",
      "subject": "",
      "thread_id": "",
      "to": ""
    }
  ],
  "ok": false,
  "query": "",
  "truncated": false
}

Related Gmail nodes

Templates that use Gmail

Solutions with Gmail

See Search Messages run in a workflow.

In a technical demo we add the Gmail connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demo Talk to sales