mail.send

Scope: mail:send

Send an email. Creates a new thread automatically.

Parameters

Name	Type	Required	Description
`to`	`string[]`	Yes	Recipient addresses
`subject`	`string`	Yes	Subject line
`text`	`string`	Yes	Plain text body
`html`	`string`	No	HTML body
`cc`	`string[]`	No	CC recipients
`bcc`	`string[]`	No	BCC recipients
`attachments`	`Attachment[]`	No	File attachments (max 10 per email, 10 MB each, 25 MB total)

Attachment shape

Field	Type	Description
`filename`	`string`	Display name
`contentType`	`string`	MIME type (e.g. `application/pdf`)
`data`	`string`	Base64-encoded file content

Example

Agent: "Email john@acme.com about the proposal"

→ mail.send({
    to: ["john@acme.com"],
    subject: "Proposal for Q4",
    text: "Hi John, attached is our proposal..."
  })

Example with attachment

→ mail.send({
    to: ["john@acme.com"],
    subject: "Q4 proposal",
    text: "Attached is the proposal PDF.",
    attachments: [
      {
        filename: "proposal.pdf",
        contentType: "application/pdf",
        data: "JVBERi0xLjQK..."  // base64
      }
    ]
  })

Returns

Message object with messageId, threadId, subject, labels: ["sent"], and attachments array (each with attachmentId, filename, contentType, size).

To download attachment bytes later, use mail.get_attachment.

REST Equivalent

POST /v0/messages/send