## Tool: `get_thread`

> [!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.

Retrieves a specific email thread from the authenticated user's Gmail account, including a list of its messages.

The optional `messageFormat` parameter controls the format of the messages returned. By default (or with `FULL_CONTENT`), it returns the full content of messages. Use `MINIMAL` to include only subject and snippet (excluding body). Use `METADATA_ONLY` to include only basic metadata (message ID, thread ID, labels, timestamp, and size estimate).

The following sample demonstrate how to use `curl` to invoke the `get_thread` 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": "get_thread", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for GetThread RPC.

### GetThreadRequest

| JSON representation |
|---|
| ``` { "threadId": string, "messageFormat": enum (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/get_thread#Input.Schema.MessageFormat`) } ``` |

| Fields ||
|---|---|
| `threadId` | `string` Required. The unique identifier of the thread to fetch. |
| `messageFormat` | ``enum (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/get_thread#Input.Schema.MessageFormat`)`` Optional. Specifies the format of the messages returned within the thread. Defaults to FULL_CONTENT. Note: MINIMAL format returns id, snippet, subject, from, to, cc, date, labelIds. METADATA_ONLY format returns id, from, to, cc, date, labelIds. FULL_CONTENT returns id, snippet, subject, from, to, cc, date, labelIds, attachmentIds, plaintextBody, htmlBody, attachments. |

### MessageFormat

Enum to control the level of detail for messages in the thread.

| Enums ||
|---|---|
| `MESSAGE_FORMAT_UNSPECIFIED` | Defaults to FULL_CONTENT. |
| `MINIMAL` | Returns message snippets and key headers (Subject, From, To, Cc, Date). |
| `FULL_CONTENT` | Returns all information in "MINIMAL" plus the full body content of each message. |
| `METADATA_ONLY` | Metadata only: does not include subject, snippet, body, attachment filenames. |

## Output Schema

Thread containing a list of messages.

### 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`
- `https://www.googleapis.com/auth/gmail.metadata`