Drafts and sending | API reference

`create_draft`

Tool

Writes a draft in the mailbox. Never sends. cc and bcc are optional; bcc recipients are hidden from the others. Returns pendingSendId and approvalCode when sending is available, and approvalPath (in-app or page with approvalUrl). If the in-app prompt is declined by a host that cannot show it, the page link comes back instead.

Inputs

Name	Type	Required	Description
`inboxId`	string	Required	Inbox id from list_inboxes.
`to`	string	Required	Recipient address or addresses.
`subject`	string	Required	Subject line.
`cc`	string	Optional	Optional comma-separated addresses to copy, like to.
`bcc`	string	Optional	Optional comma-separated addresses to blind copy, like to. Hidden from the other recipients.
`text`	string	Required	Email body as the human would send it. No meta/product/tooling narration.
`threadId`	string	Optional	Thread to reply in, from get_message.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_draft",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "to": "sam@example.com",
      "subject": "Re: Friday?",
      "text": "Friday at 2 works for me."
    }
  }
}

`send_draft`

Tool

Sends a draft after the person approves it in the app prompt or on the approval page.

Inputs

Name	Type	Required	Description
`pendingSendId`	string	Required	pendingSendId returned by create_draft when sendAvailable is true
`approvalCode`	string	Required	approvalCode returned by create_draft for this pending send
`humanApprovedInChat`	true	Optional	Ignored. Approval happens in the in-app prompt or on the approval page.
`confirmTo`	string	Optional	If provided, must match the pending send To
`confirmSubject`	string	Optional	If provided, must match the pending send subject
`confirmVersion`	string	Optional	Only after a result said the draft changed in the mailbox: the version value that result gave, passed once the person has seen that version and said yes.
`waitSeconds`	number	Optional	When the person approves on the approval page, wait up to this many seconds (default 0) for their click and return sent:true as soon as it lands.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_draft",
    "arguments": {
      "pendingSendId": "ps_7d2c9a",
      "approvalCode": "K7Q2"
    }
  }
}

`get_send_diagnostics`

Tool

Why recent sends did or did not go out, including sends that were never approved.

Inputs

Name	Type	Required	Description
`inboxId`	string	Optional	Inbox id from list_inboxes.
`limit`	number	Optional

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_send_diagnostics",
    "arguments": {}
  }
}

`show_draft`

Tool

Shows a draft as an editable card with a Send button, in apps that support MCP Apps.

Inputs

Name	Type	Required	Description
`inboxId`	string	Required	Inbox id from list_inboxes.
`draftId`	string	Required	The id create_draft returned

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "show_draft",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "draftId": "draft_1758182400000"
    }
  }
}

`set_send_enabled`

Tool

Turns sending on or off. Only when the person asks.

Inputs

Name	Type	Required	Description
`enabled`	boolean	Required	true to allow send_draft once the person approves; false to block sending
`humanConfirmedInChat`	true	Required	Must be literal true. Confirms the human asked to change sendEnabled in this chat

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_send_enabled",
    "arguments": {
      "enabled": true,
      "humanConfirmedInChat": true
    }
  }
}

`update_draft_from_card`

App only

The draft card saving an edit. Needs a single-use code agents never get. Agents use create_draft.

Hidden from the model (visibility: ['app']). The interactive view calls it directly.

Inputs

Name	Type	Required	Description
`nonce`	string	Required	Single-use code the card got from the server. Agents never have one.
`to`	string	Required	Recipient address or addresses.
`cc`	string	Optional
`bcc`	string	Optional
`subject`	string	Required	Subject line.
`body`	string	Required	Plain text body.

`send_draft_from_card`

App only

The draft card sending after the person clicks Send. Agents use send_draft.

Hidden from the model (visibility: ['app']). The interactive view calls it directly.

Inputs

Name	Type	Required	Description
`nonce`	string	Required	Single-use code the card got from the server. Agents never have one.
`to`	string	Required	Recipient address or addresses.
`cc`	string	Optional
`bcc`	string	Optional
`subject`	string	Required	Subject line.
`body`	string	Required	Plain text body.