Search messages

searchMessages searches a mailbox using the same query syntax as Gmail’s search box. It returns identifiers only, which keeps broad searches lightweight. Use Get message or Get messages when you need bodies, headers, or attachments.

Example

automations/find-unread-invoices.automation.ts

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

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

Inputs

Property	Type	Required	Default	Description
`query`	`string`	No	—	Query using Gmail search-box syntax, such as `from:billing@example.com newer_than:30d`. An omitted or empty query does not filter by query text.
`labelIds`	`string[]`	No	—	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.
`account`	`string \| IntegrationAccountReference<"google">`	No	Project default	Google account binding to search.

Each input can also be a compatible Signal from an earlier trigger or action.

Output

Returns a 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.

Get started

Concepts

Reference

Example

Inputs

Output

​Example

​Inputs

​Output

Example

Inputs

Output