> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Search messages

> Find Gmail messages with Gmail search syntax and return their message and thread IDs.

`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](/reference/integrations/gmail/actions/get-message) or [Get messages](/reference/integrations/gmail/actions/get-messages) when you need bodies, headers, or attachments.

## Example

```ts automations/find-unread-invoices.automation.ts theme={null}
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[]>`:

```ts theme={null}
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.

<Note>
  Test complex queries in Gmail's search box first. `labelIds` uses provider IDs
  such as `INBOX` or IDs returned by [List
  labels](/reference/integrations/gmail/actions/list-labels); label names belong
  in `query`, for example `label:Receipts`.
</Note>