## Tool: `search_threads`

> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which grants early access to certain features.

Lists email threads from the authenticated user's Gmail account.

This tool can filter threads based on a query string and supports pagination. It returns a list of threads, including their IDs and related messages. Each related message contains details like a snippet of the message body, the subject, the sender, the recipients etc. The `view` parameter controls which fields are populated in the related messages. By default (or with `THREAD_VIEW_MINIMAL`), it includes subject and snippet. Use `THREAD_VIEW_METADATA_ONLY` to exclude subject and snippet. Note that the full message bodies are not returned by this tool; use the 'get_thread' tool with a thread ID to fetch the full message body if needed. Threads with excluded criteria may still appear in the results. This occurs because Gmail identifies matching messages first. For example, if you search for -is:starred, Gmail will find an entire thread if it contains at least one unstarred message, even if other emails in that same conversation are starred.

The following sample demonstrate how to use `curl` to invoke the `search_threads` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "search_threads", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for SearchThreads RPC.

### SearchThreadsRequest

| JSON representation |
|---|
| ``` { "pageSize": integer "pageToken": string "query": string "includeTrash": boolean "view": enum (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/list_threads#Input.Schema.ThreadView`) } ``` |

| Fields ||
|---|---|
| Union field `_page_size`. `_page_size` can be only one of the following: ||
| `pageSize` | `integer` Optional. The maximum number of threads to return. If unspecified, defaults to 20. The maximum allowed value is 50. |
| Union field `_page_token`. `_page_token` can be only one of the following: ||
| `pageToken` | `string` Optional. Page token to retrieve a specific page of results in the list. Leave empty to fetch the first page. This is primarily used for pagination to continue fetching results from where the previous `SearchThreads` call left off, especially when the number of threads matching the query exceeds the page_size limit. |
| Union field `_query`. `_query` can be only one of the following: ||
| `query` | `string` Optional. A query string to filter the threads. Natural language queries must be pre-converted into Gmail syntax queries to use this tool. If omitted, all threads (excluding spam and trash by default) are listed. Supported Operators by Category: Sender \& Recipient: - `from:<email>` --- Sent from a specific person. - `to:<email>` --- Sent to a specific person. - `cc:<email>` --- Specific people in Cc. - `bcc:<email>` --- Specific people in Bcc. - `deliveredto:<email>` --- Delivered to a specific address. - `list:<email>` --- From a specific mailing list. Time \& Date: - `after:YYYY/MM/DD` / `newer:YYYY/MM/DD` --- Received after a date. - `before:YYYY/MM/DD` / `older:YYYY/MM/DD` --- Received before a date. - `older_than:<duration>` --- Older than a duration (for example, `1y`, `2d`). - `newer_than:<duration>` --- Newer than a duration. Content: - `subject:<words>` --- Words in the subject line. - `has:<type>` --- Has specific content types (attachment, drive, youtube, document). - `filename:<name>` --- Attachment with a specific name or type. - `"<word/phrase>"` --- Search for an exact word or phrase. (for example, `"holiday"`, `"holiday vacation"`). - `+<word>` --- Match a word exactly. (for example, `+holiday`, `+unicorn`) - `rfc822msgid:<id>` --- Specific message ID header. - `AROUND <distance>` --- Find words near each other (for example, `holiday AROUND 10 vacation`). Labels \& Categories: - `label:<name>` --- Under a specific label. The tool accepts label IDs, not display names. Use the list_labels tool to get the ID. - `category:<name>` --- In a category (primary, social, promotions, updates, forums, reservations, purchases). - `in:<label>` --- Search in specific labels (archive, snoozed, trash, sent, inbox). For example, `in:trash`, `in:inbox`. Archived and sent messages are included by default; use `-in:archive` and `-in:sent` to exclude them. Drafts are explicitly excluded by default by the tool. Use `in:inbox` to restrict search to the inbox only. - `has:userlabels` --- Has any user labels. - `has:nouserlabels` --- Does not have any user labels. - `has:*-star` --- Specific star colors (if enabled, for example, `has:yellow-star`). - `in:draft` --- Search in drafts. -in:draft means exclude drafts from the search results. - `in:sent` --- Search in sent messages. - `in:anywhere` --- Search in all folders (including spam and trash). Status: - `is:<status>` --- Search by status (important, starred, unread, read, muted). Size: - `size:<bytes>` --- Specific size in bytes. - `larger:<size>` / `smaller:<size>` --- Larger or smaller than a size (for example, `10M` for 10 MB). Logic \& Grouping: - `AND` --- Match all criteria (default behavior). - `OR` or `{ }` --- Match one or more criteria (for example, `from:amy OR from:david`, `{from:amy from:david}`). - `-` (minus) --- Exclude criteria (for example, `-movie`). - `( )` --- Group multiple search terms (for example, `subject:(dinner film)`). Examples: - `subject:OneMCP Update` - `from:user@example.com` - `to:user2@example.com AND newer_than:7d` - `project proposal has:attachment` - `is:unread -in:draft` |
| Union field `_include_trash`. `_include_trash` can be only one of the following: ||
| `includeTrash` | `boolean` Optional. Include threads from TRASH in the results. Defaults to false. |
| Union field `_view`. `_view` can be only one of the following: ||
| `view` | ``enum (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/list_threads#Input.Schema.ThreadView`)`` Optional. Controls the fields populated for threads in the thread list. Defaults to THREAD_VIEW_MINIMAL. THREAD_VIEW_MINIMAL returns id, snippet, subject, from, to, cc, date, labelIds. THREAD_VIEW_METADATA_ONLY returns id, from, to, cc, date, labelIds. |

### ThreadView

Enum to control the fields populated for threads in the ListThreads and SearchThreads response.

| Enums ||
|---|---|
| `THREAD_VIEW_UNSPECIFIED` | Maps to THREAD_VIEW_MINIMAL for backward compatibility. |
| `THREAD_VIEW_METADATA_ONLY` | Returns id, from, to, cc, date, labelIds. |
| `THREAD_VIEW_MINIMAL` | Returns id, snippet, subject, from, to, cc, date, labelIds. |

## Output Schema

Response message for SearchThreads RPC.

### SearchThreadsResponse

| JSON representation |
|---|
| ``` { "threads": [ { object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/get_thread#Output.Schema.Thread`) } ], "nextPageToken": string, "resultCountEstimate": string } ``` |

| Fields ||
|---|---|
| `threads[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/get_thread#Output.Schema.Thread`)`` List of thread summaries. |
| `nextPageToken` | `string` A token that can be used in a subsequent call to retrieve the next page of threads. Present only if there are more results. If the number of threads matching the query exceeds the page_size limit, the response will contain a `next_page_token`. To retrieve the next page of results, pass this token in the `page_token` field of the next `SearchThreadsRequest`. |
| `resultCountEstimate` | `string (https://developers.google.com/discovery/v1/type-format format)` The estimated result count for this query. It should be treated as a lower bound, so for example if it is 500, then the count can be reported to the user as "500+". |

### Thread

| JSON representation |
|---|
| ``` { "id": string, "messages": [ { object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/send_message#Output.Schema.Message`) } ] } ``` |

| Fields ||
|---|---|
| `id` | `string` The unique identifier of the thread. |
| `messages[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/send_message#Output.Schema.Message`)`` A list of messages in the thread, ordered chronologically. |

### Message

| JSON representation |
|---|
| ``` { "id": string, "snippet": string, "subject": string, "sender": string, "toRecipients": [ string ], "ccRecipients": [ string ], "date": string, "plaintextBody": string, "attachmentIds": [ string ], "htmlBody": string, "attachments": [ { object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/send_message#Output.Schema.AttachmentMetadata`) } ], "labelIds": [ string ] } ``` |

| Fields ||
|---|---|
| `id` | `string` The unique identifier of the message. |
| `snippet` | `string` Snippet of the message body. |
| `subject` | `string` The message subject extracted from headers: |
| `sender` | `string` Sender email address. |
| `toRecipients[]` | `string` To recipient email addresses. |
| `ccRecipients[]` | `string` CC recipient email addresses. |
| `date` | `string` Date of the message in ISO 8601 format (YYYY-MM-DD). |
| `plaintextBody` | `string` Full body content, only populated if MessageFormat was FULL_CONTENT. |
| `attachmentIds[]` | `string` Output only. The attachment ids, only populated if MessageFormat was FULL_CONTENT. |
| `htmlBody` | `string` The HTML content of the email, only populated if MessageFormat was FULL_CONTENT. |
| `attachments[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/send_message#Output.Schema.AttachmentMetadata`)`` Output only. The attachments, only populated if MessageFormat was FULL_CONTENT. |
| `labelIds[]` | `string` The ids of the labels attached to the message. Includes ids of user labels and standard system labels limited to `INBOX`, `SPAM`, `TRASH`, `UNREAD`, `STARRED`, `IMPORTANT`, `SENT`, `DRAFT`, `CHAT`. |

### AttachmentMetadata

| JSON representation |
|---|
| ``` { "id": string, "mimeType": string, "filename": string } ``` |

| Fields ||
|---|---|
| `id` | `string` Output only. The ID of the attachment. |
| `mimeType` | `string` The MIME type of the attachment. |
| `filename` | `string` The filename of the attachment. |

### Tool Annotations

Destructive Hint: ❌ \| Idempotent Hint: ✅ \| Read Only Hint: ✅ \| Open World Hint: ❌

## Authorization Scopes

Requires one of the following OAuth scopes:

- `https://mail.google.com/`
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/gmail.readonly`