Skip to main content
POST
Create a Gmail draft or threaded reply with optional workspace attachments

Authorizations

x-api-key
string
header
required

Organization API key passed as the x-api-key header. The raw key is the header value; do not prefix it with Bearer.

Body

application/json
to
string
required

Recipient email address.

Required string length: 3 - 320
subject
string
required

Draft subject line. For replies or forwards, include threadId; subjects starting with Re: or Fwd: are rejected without threadId so the draft stays on the existing conversation.

Required string length: 1 - 500
body
string
required

Draft body: plain prose or a safe Markdown subset (headings, bold, italic or italic, code, text [blocked], bare URLs, lists (-, *, 1.) with simple indented nesting, > block quotes, pipe tables, and fenced code). Links must use http, https, or mailto. Raw HTML is displayed as text, never executed. Separate paragraphs with blank lines; single line breaks, indentation, and repeated spaces are preserved. Do not hard-wrap prose. Put the closing (e.g. Thanks,) and sender name on separate lines with a real newline, never joined on one line. For threaded drafts, the server appends the quoted conversation automatically; do not include quoted history.

Required string length: 1 - 50000
cc
string

Optional comma-separated Cc email addresses.

Required string length: 3 - 1000
bcc
string

Optional comma-separated Bcc email addresses.

Required string length: 3 - 1000
timeZone
string

User's IANA time zone (for example America/New_York). Pass the user's zone to format reply attribution like Gmail Web, including daylight saving time. When omitted, attribution keeps the original message Date header's offset, not the server's time zone.

Required string length: 1 - 100
threadId
string

Gmail thread id to reply on. Required for replies and forwards; get it from the gmail-messages capability. When set, the draft is attached to that thread as a reply — keep the thread's subject (e.g. 'Re: …').

Required string length: 1 - 512
attachments
string[]

Optional workspace file paths, 1 to 10 files totaling at most 4 MiB. File bytes stay outside model context. Requires a direct execute_capability call from a supporting OpenWork host; Code Mode and other MCP hosts are unsupported and create no draft. Do not retry without attachments.

Required array length: 1 - 10 elements
Minimum string length: 1

Response

Draft created.

ok
boolean
required
draftId
string
required
messageId
string | null
required
draftUrl
string | null
required

Gmail URL for the ready-to-send draft. Always share draftUrl with the user so they can open the draft in Gmail for review and send.

threadUrl
string | null
required

Gmail URL for the conversation thread returned by Gmail for this draft.

to
string
required
subject
string
required
threadId
string | null
required
quotedHistoryIncluded
boolean
required

True when quoted conversation history was included by the server or already present in the request body.

attachments
object[]