## Tool: `list_drafts`

> [!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 draft emails from the authenticated user's Gmail account.

This tool can filter drafts based on a query string and supports pagination. It returns a list of drafts, including their IDs and subjects (unless `view` is set to `DRAFT_VIEW_METADATA_ONLY`). `page_token` can be used to paginate the results. To retrieve subsequent pages of results, use the `page_token` returned in the previous response.

The `view` parameter controls which fields are populated in the response. By default (or with `DRAFT_VIEW_FULL`), it returns full content. Use `DRAFT_VIEW_METADATA_ONLY` to exclude sensitive content like subject and body.

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

## Input Schema

Request message for ListDrafts RPC.

### ListDraftsRequest

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

| Fields ||
|---|---|
| Union field `_page_size`. `_page_size` can be only one of the following: ||
| `pageSize` | `integer` Optional. The maximum number of drafts 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. A token received from a previous list_drafts call to retrieve the next page of results. Leave empty to fetch the first page. This is primarily used for pagination to continue fetching results from where the previous `ListDraft` call left off, especially when the number of drafts matching the query exceeds the page_size limit. |
| Union field `_query`. `_query` can be only one of the following: ||
| `query` | `string` Examples: - `subject:OneMCP Update` - `from:gduser1@workspacesamples.dev` - `to:gduser2@workspacesamples.dev AND newer_than:7d` - `project proposal has:attachment` - `is:unread` A space or a dash (`-`) will separate a number while a dot (`.`) will be a decimal. For example, `01.2047-100` is considered two numbers: `01.2047` and `100`. Note: If we want to ensure all drafts for the query are returned, we can paginate the results by making repeated calls to the tool until the response contains an empty list of drafts. |
| 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_drafts#Input.Schema.DraftView`)`` Optional. Controls the fields populated for drafts in the draft list. By default (or with `DRAFT_VIEW_FULL`), it returns full content, which has draft ID, threadID, to, cc, bcc, date, subject, and body. Use `DRAFT_VIEW_METADATA_ONLY` to exclude subject and body. |

### DraftView

Enum to control the fields populated for drafts in the ListDrafts response.

| Enums ||
|---|---|
| `DRAFT_VIEW_UNSPECIFIED` | Maps to DRAFT_VIEW_FULL for backward compatibility. |
| `DRAFT_VIEW_METADATA_ONLY` | Metadata only: does not include subject, plaintext_body, html_body. |
| `DRAFT_VIEW_FULL` | Metadata + UGC (Default behavior). |

## Output Schema

Response message for ListDrafts RPC.

### ListDraftsResponse

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

| Fields ||
|---|---|
| `drafts[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/create_draft#Output.Schema.Draft`)`` List of drafts. |
| `nextPageToken` | `string` A token that can be used in a subsequent call to retrieve the next page of drafts. If the number of drafts 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 `ListDraftsRequest`. |

### Draft

| JSON representation |
|---|
| ``` { "id": string, "subject": string, "threadId": string, "toRecipients": [ string ], "ccRecipients": [ string ], "bccRecipients": [ string ], "plaintextBody": string, "date": string, "htmlBody": string } ``` |

| Fields ||
|---|---|
| `id` | `string` The unique identifier of the draft resource. |
| `subject` | `string` The subject line of the draft message. |
| `threadId` | `string` The ID of the thread this draft belongs to. |
| `toRecipients[]` | `string` List of 'To' recipient email addresses extracted from headers. |
| `ccRecipients[]` | `string` List of 'Cc' recipient email addresses extracted from headers. |
| `bccRecipients[]` | `string` List of 'Bcc' recipient email addresses extracted from headers. |
| `plaintextBody` | `string` Plain text body content, if available. |
| `date` | `string` Date of the draft in ISO 8601 format (YYYY-MM-DD). |
| `htmlBody` | `string` The HTML body content of the draft, if available. |

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