MCP Tools Reference: gmailmcp.googleapis.com

Tool: list_drafts

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 
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 (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 (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 (Draft)
    }
  ],
  "nextPageToken": string
}
Fields
drafts[]

object (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