Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Draft Gmail Message

draft_gmail_message

Creates Gmail draft emails for new messages, replies, and forwards, with optional attachments and Send As aliases, so you can review before sending.

Instructions

Creates a draft email in the user's Gmail account. Supports new, reply, and forward drafts with optional attachments. Supports Gmail's "Send As" feature to draft from configured alias addresses.

To save a forward as a draft for review, pass forward_message_id. The original subject, body (quoted with a "Forwarded message" header), and attachments are carried over. In forward mode, body (if any) is prepended as a note, subject is optional, and threading, reply, and signature options do not apply.

SCHEDULED SEND IS NOT AVAILABLE. Gmail's REST API exposes no send-time parameter; the Schedule send feature is web-UI only, and a message cannot be placed in the Scheduled folder through the API. Do not claim a message was scheduled. To deliver at a chosen time, create a draft with draft_gmail_message. An external scheduler must retain the message data to create and send a new message via send_gmail_message then, or call users.drafts.send with the draft ID returned by draft_gmail_message. Alternatively, let the user schedule the draft in the Gmail UI.

Input Schema

Name	Required	Description	Default
`cc`	No	Optional CC email address.
`to`	No	Optional recipient email address.
`bcc`	No	Optional BCC email address.
`body`	No	Email body. Required unless forwarding, where it becomes an optional note prepended above the quoted original.
`subject`	No	Email subject. Required for a new draft. Optional when replying with thread_id (inherits the parent message's subject, adding 'Re:' only if absent) or when forwarding (then defaults to 'Fwd: <original subject>').
`direction`	No	Base text direction of the body. 'auto' (default) takes it from the first strong character (a right-to-left script gives 'rtl', anything else 'ltr'); 'ltr'/'rtl' force it. On a forward it orients the note.	auto
`from_name`	No	Optional sender display name (e.g., 'Peter Hartree'). If provided, the From header will be formatted as 'Name <email>'.
`reply_all`	No	Whether to derive reply-all recipients from the thread: To = the sender being replied to, Cc = the other participants, excluding the authenticated account and from_email. Requires thread_id. Explicit to/cc win; when cc is omitted the sender being replied to is added to the derived Cc if they are not already in To. Defaults to false.
`thread_id`	No	Optional Gmail thread ID to reply within. When in_reply_to is omitted, replies to the latest non-draft, non-trash message with an RFC Message-ID.
`from_email`	No	Optional 'Send As' alias email address. Must be configured in Gmail settings (Settings > Accounts > Send mail as). If not provided, uses the account's default Send As address, falling back to the authenticated user's email when Gmail returns no usable Send-As entry or settings access is not authorized.
`references`	No	Optional Message-ID ancestry chain. Normally omit when thread_id is provided; the server derives the chain through the selected reply target.
`attachments`	No	Optional list of attachments. Each can have: 'url' (fetch from URL — works with MCP attachment URLs from get_drive_file_download_url / get_gmail_attachment_content), OR 'path' (file path, auto-encodes), OR 'content' (standard base64, not urlsafe) + 'filename'. Optional 'mime_type'. Optional 'content_id' (string) makes the attachment inline-rendered: it lands in a multipart/related part with `Content-ID: <content_id>` and `Content-Disposition: inline`, and the HTML body can reference it via `<img src="cid:<content_id>">` (RFC 2392). Without `content_id` the attachment is a regular multipart/mixed attachment.
`body_format`	No	Email body format. Use 'plain' for plaintext or 'html' for HTML content. With 'html', write real markup; an entity-escaped body ('<div>') is rejected.	plain
`in_reply_to`	No	Optional RFC Message-ID to explicitly reply to a specific message (e.g., '<message123@gmail.com>'). Omit to reply to the latest eligible message in thread_id.
`quote_original`	No	Whether to include the original message as a quoted reply. Only has an effect when thread_id is provided. Defaults to false.
`include_signature`	No	Whether to append the Gmail signature from Settings > Signature when available. Defaults to true.
`user_google_email`	Yes	The user's Google email address. Required for authentication.
`forward_message_id`	No	Set to a Gmail message ID to save a forward of that message as a draft for review. The original subject, body, and (optionally) attachments are carried over; 'body' becomes an optional note prepended to the forward.
`include_forwarded_attachments`	No	When forwarding, whether to include the original message's attachments. Ignored unless forward_message_id is set.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv2.2.0Oct 24, 2026

addedInput schema / properties / body / default
```
Added value: +null
```

changedInput schema / properties / body / description

Previous value: -"Email body (plain text)."New value: +"Email body. Required unless forwarding, where it becomes an optional note prepended above the quoted original."

changedInput schema / properties / body_format / description

Previous value: -"Email body format. Use 'plain' for plaintext or 'html' for HTML content."New value: +"Email body format. Use 'plain' for plaintext or 'html' for HTML content. With 'html', write real markup; an entity-escaped body ('&lt;div&gt;') is rejected."

addedInput schema / properties / direction

Added value: +{
+  "default": "auto",
+  "description": "Base text direction of the body. 'auto' (default) takes it from the first strong character (a right-to-left script gives 'rtl', anything else 'ltr'); 'ltr'/'rtl' force it. On a forward it orients the note.",
+  "enum": [
+    "auto",
+    "ltr",
+    "rtl"
+  ],
+  "type": "string"
+}

addedInput schema / properties / forward_message_id

Added value: +{
+  "default": null,
+  "description": "Set to a Gmail message ID to save a forward of that message as a draft for review. The original subject, body, and (optionally) attachments are carried over; 'body' becomes an optional note prepended to the forward.",
+  "type": "string"
+}

addedInput schema / properties / include_forwarded_attachments

Added value: +{
+  "default": true,
+  "description": "When forwarding, whether to include the original message's attachments. Ignored unless forward_message_id is set.",
+  "type": "boolean"
+}

addedInput schema / properties / reply_all

Added value: +{
+  "default": false,
+  "description": "Whether to derive reply-all recipients from the thread: To = the sender being replied to, Cc = the other participants, excluding the authenticated account and from_email. Requires thread_id. Explicit to/cc win; when cc is omitted the sender being replied to is added to the derived Cc if they are not already in To. Defaults to false.",
+  "type": "boolean"
+}

addedInput schema / properties / subject / default
```
Added value: +null
```

changedInput schema / properties / subject / description

Previous value: -"Email subject."New value: +"Email subject. Required for a new draft. Optional when replying with thread_id (inherits the parent message's subject, adding 'Re:' only if absent) or when forwarding (then defaults to 'Fwd: <original subject>')."

changedInput schema / required

Previous value: -[
-  "user_google_email",
-  "subject",
-  "body"
-]New value: +[
+  "user_google_email"
+]

Changed19 schema fields changedv1.28.0Sep 24, 2026

removedInput schema / properties / attachments / anyOf

Removed value: -[
-  {
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / attachments / items

Added value: +{
+  "additionalProperties": true,
+  "type": "object"
+}

addedInput schema / properties / attachments / type
```
Added value: +"array"
```

removedInput schema / properties / bcc / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / bcc / type
```
Added value: +"string"
```

removedInput schema / properties / cc / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / cc / type
```
Added value: +"string"
```

removedInput schema / properties / from_email / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / from_email / type
```
Added value: +"string"
```

removedInput schema / properties / from_name / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / from_name / type
```
Added value: +"string"
```

removedInput schema / properties / in_reply_to / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / in_reply_to / type
```
Added value: +"string"
```

removedInput schema / properties / references / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / references / type
```
Added value: +"string"
```

removedInput schema / properties / thread_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / thread_id / type
```
Added value: +"string"
```

removedInput schema / properties / to / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / to / type
```
Added value: +"string"
```

Changed4 schema fields changedv1.25.2Aug 30, 2026

changedInput schema / properties / from_email / description

Previous value: -"Optional 'Send As' alias email address. Must be configured in Gmail settings (Settings > Accounts > Send mail as). If not provided, uses the authenticated user's email."New value: +"Optional 'Send As' alias email address. Must be configured in Gmail settings (Settings > Accounts > Send mail as). If not provided, uses the account's default Send As address, falling back to the authenticated user's email when Gmail returns no usable Send-As entry or settings access is not authorized."

changedInput schema / properties / in_reply_to / description

Previous value: -"Optional RFC Message-ID of the message being replied to (e.g., '<message123@gmail.com>')."New value: +"Optional RFC Message-ID to explicitly reply to a specific message (e.g., '<message123@gmail.com>'). Omit to reply to the latest eligible message in thread_id."

changedInput schema / properties / references / description

Previous value: -"Optional chain of Message-IDs for proper threading."New value: +"Optional Message-ID ancestry chain. Normally omit when thread_id is provided; the server derives the chain through the selected reply target."

changedInput schema / properties / thread_id / description

Previous value: -"Optional Gmail thread ID to reply within."New value: +"Optional Gmail thread ID to reply within. When in_reply_to is omitted, replies to the latest non-draft, non-trash message with an RFC Message-ID."

Changed1 schema field changedv1.24.0Aug 13, 2026

changedInput schema / properties / quote_original / description

Previous value: -"Whether to include the original message as a quoted reply. Requires thread_id. Defaults to false."New value: +"Whether to include the original message as a quoted reply. Only has an effect when thread_id is provided. Defaults to false."

Changed21 schema fields changedv1.0.1Jul 31, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / attachments

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional list of attachments. Each can have: 'url' (fetch from URL — works with MCP attachment URLs from get_drive_file_download_url / get_gmail_attachment_content), OR 'path' (file path, auto-encodes), OR 'content' (standard base64, not urlsafe) + 'filename'. Optional 'mime_type'. Optional 'content_id' (string) makes the attachment inline-rendered: it lands in a multipart/related part with `Content-ID: <content_id>` and `Content-Disposition: inline`, and the HTML body can reference it via `<img src=\"cid:<content_id>\">` (RFC 2392). Without `content_id` the attachment is a regular multipart/mixed attachment."
+}

addedInput schema / properties / bcc

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional BCC email address."
+}

removedInput schema / properties / body / title
```
Removed value: -"Body"
```

addedInput schema / properties / body_format

Added value: +{
+  "default": "plain",
+  "description": "Email body format. Use 'plain' for plaintext or 'html' for HTML content.",
+  "enum": [
+    "plain",
+    "html"
+  ],
+  "type": "string"
+}

addedInput schema / properties / cc

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional CC email address."
+}

addedInput schema / properties / from_email

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional 'Send As' alias email address. Must be configured in Gmail settings (Settings > Accounts > Send mail as). If not provided, uses the authenticated user's email."
+}

addedInput schema / properties / from_name

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional sender display name (e.g., 'Peter Hartree'). If provided, the From header will be formatted as 'Name <email>'."
+}

addedInput schema / properties / in_reply_to

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional RFC Message-ID of the message being replied to (e.g., '<message123@gmail.com>')."
+}

addedInput schema / properties / include_signature

Added value: +{
+  "default": true,
+  "description": "Whether to append the Gmail signature from Settings > Signature when available. Defaults to true.",
+  "type": "boolean"
+}

addedInput schema / properties / quote_original

Added value: +{
+  "default": false,
+  "description": "Whether to include the original message as a quoted reply. Requires thread_id. Defaults to false.",
+  "type": "boolean"
+}

addedInput schema / properties / references

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional chain of Message-IDs for proper threading."
+}

removedInput schema / properties / service

Removed value: -{
-  "title": "service",
-  "type": "string"
-}

removedInput schema / properties / subject / title
```
Removed value: -"Subject"
```

addedInput schema / properties / thread_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional Gmail thread ID to reply within."
+}

removedInput schema / properties / to / title
```
Removed value: -"To"
```

addedInput schema / properties / user_google_email / description

Added value: +"The user's Google email address. Required for authentication."

removedInput schema / properties / user_google_email / title
```
Removed value: -"User Google Email"
```

changedInput schema / required

Previous value: -[
-  "service",
-  "user_google_email",
-  "subject",
-  "body"
-]New value: +[
+  "user_google_email",
+  "subject",
+  "body"
+]

removedInput schema / title

Removed value: -"draft_gmail_messageArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object",
+  "x-fastmcp-wrap-result": true
+}

First observedv1.0.0Jun 10, 2025

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (non-read-only, non-destructive, non-idempotent, open-world), the description discloses forward-mode semantics — body becomes a prepended note, subject is optional, threading/reply/signature options do not apply — and the hard API limitation on scheduled send. It does not mention that repeated calls create duplicate drafts (relevant given idempotentHint=false), which is the one behavioral gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and modes, then mode-specific rules, then the scheduling constraint; no filler sentences. The scheduling paragraph runs long and restates the limitation three ways, which costs a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 19-parameter mutation tool with annotations and an output schema, the description covers the mode-dependent behavior an agent cannot infer from the schema alone. Minor omissions (duplicate-on-retry behavior, relative priority of thread_id vs in_reply_to) remain but the schema carries those details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely new meaning: the interaction rules for forward mode (what body and subject become, which options become inert) that no single parameter description states in those terms.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

First sentence states a specific verb+resource ('Creates a draft email in the user's Gmail account') and the next sentences enumerate the modes (new, reply, forward, alias 'Send As'). An agent can immediately distinguish this from the sibling send_gmail_message, which delivers mail rather than saving a draft.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use forward_message_id to save a forward for review, use draft_gmail_message when scheduling time delivery, then send_gmail_message (or users.drafts.send) at the chosen time, or let the user schedule in the UI. It also names an exclusion ('SCHEDULED SEND IS NOT AVAILABLE') and warns against claiming scheduling succeeded.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server