Messages API

Send and manage messages on behalf of the user.

⚠️ Approval Required: messages.send() always requires user approval before execution.

messages.list()

Retrieve recent messages matching optional filters.

Parameters

Parameter	Type	Required	Description
`filter`	object	No	Filter criteria (from, after, limit)
`filter.from`	string	No	Filter by sender email
`filter.after`	string	No	ISO date, messages after this time
`filter.limit`	number	No	Max results (default: 20, max: 100)

Example

const messages = await tools.messages.list({
  from: "boss@company.com",
  after: "2024-01-01T00:00:00Z",
  limit: 10
});

// Returns:
[
  {
    id: "msg_abc123",
    from: "boss@company.com",
    to: ["you@company.com"],
    subject: "Q4 Report",
    body: "Can you send the quarterly report?",
    timestamp: "2024-03-15T14:30:00Z",
    unread: true
  },
  // ...
]

messages.send()

Send a message on behalf of the user. Always requires approval.

Parameters

Parameter	Type	Required	Description
`to`	string[]	Yes	Recipient email addresses
`subject`	string	Yes	Message subject line
`body`	string	Yes	Message body (plain text or HTML)
`cc`	string[]	No	CC recipients
`bcc`	string[]	No	BCC recipients

Example with Approval Flow

export async function handleIntent({ intent, context, tools }) {
  if (intent.action === "send_report") {
    // Step 1: Request approval
    const approval = await tools.approval.request({
      action: "send_message",
      title: "Send Q4 Report",
      description: "Send quarterly report to team@company.com",
      details: {
        to: ["team@company.com"],
        subject: "Q4 2024 Report",
        preview: "Attached is the quarterly report..."
      }
    });

    // Step 2: Wait for user decision
    if (!approval.approved) {
      return {
        type: "error",
        title: "Message not sent",
        description: "You declined to send the message."
      };
    }

    // Step 3: Send message
    try {
      await tools.messages.send({
        to: ["team@company.com"],
        subject: "Q4 2024 Report",
        body: "Attached is the quarterly report for review."
      });

      return {
        type: "result",
        title: "✅ Message sent",
        description: "Report sent to team@company.com"
      };
    } catch (error) {
      return {
        type: "error",
        title: "Failed to send message",
        description: error.message
      };
    }
  }
}

Required Capabilities

{
  "capabilities": [
    "messages.read",  // for messages.list()
    "messages.send"   // for messages.send()
  ]
}

Error Codes

CAPABILITY_DENIED

User has not granted messages.read or messages.send capability to this agent.

APPROVAL_REQUIRED

Must call approval.request() before messages.send().

INVALID_RECIPIENT

One or more email addresses are invalid.