Search messages

gmail.searchMessages returns only IDs, keeping broad mailbox searches lightweight. Use Get message or Get messages for bodies, headers, or attachments.

Example

automations/find-unread-invoices.automation.ts

import { automation } from "automate.ax"
import { gmail } from "automate.ax/gmail"

export default automation("Find unread Gmail invoices", () => {
  gmail.searchMessages({
    query: "is:unread subject:invoice has:attachment",
    limit: 25,
  })
})

Inputs

Property	Type	Required	Default	Description
`query`	`string`	No	None	Query using Gmail search-box syntax, such as `from:billing@example.com newer_than:30d`. An omitted or empty query doesn’t filter by query text.
`labelIds`	`string[]`	No	None	Gmail label IDs that every returned message must carry. These are IDs, not display names.
`includeSpamTrash`	`boolean`	No	`false`	Whether messages in Spam and Trash may match.
`limit`	`number`	No	`100`	Maximum total results. Must be an integer from 1 to 10,000.
Second argument: `{ account }`	`string \| IntegrationAccountReference<"google">`	No	Project default	Google Account binding to search.

Inputs accept compatible signals.

Output

Returns Signal<MessageIdentifier[]>:

interface MessageIdentifier {
  messageId: string
  threadId: string
}

messageId identifies the individual email. threadId identifies the Gmail conversation containing it. Multiple results can share a threadId. The action fetches additional Gmail result pages internally until it reaches limit or exhausts the search.

Test complex queries in Gmail’s search box first. labelIds uses provider IDs such as INBOX or IDs returned by List labels; label names belong in query, for example label:Receipts.

Built-in triggers

Built-in actions

Runtime utilities

Integrations

Example

Inputs

Output

​Example

​Inputs

​Output

Example

Inputs

Output