MCP tools

Provision a new agent mailbox. Returns a mailbox ID and ingest address for email forwarding.

// Returns
{
  id: "mbx_a8Kq7fR2xZ",
  address: "ops@acme.com",
  ingest_address: "mbx_a8Kq7fR2xZ@ingest.mcpmail.app",
  status: "active"
}

List all mailboxes on your account.

mailbox.list()
// Returns { mailboxes: [{ id, address, display_name, status, approval_mode }] }

Update mailbox settings — display name, approval mode, auto-approve rules.

Delete a mailbox and all stored messages. This action is irreversible.

Start domain verification. Returns DNS records to add for SPF and DKIM.

// Returns
{
  domain: "acme.com",
  status: "pending",
  dns_records: [
    { type: "TXT", name: "@", value: "v=spf1 include:mcpmail.app ~all" },
    { type: "CNAME", name: "mcpm1._domainkey", value: "dkim1.mcpmail.app" },
    { type: "CNAME", name: "mcpm2._domainkey", value: "dkim2.mcpmail.app" },
    { type: "CNAME", name: "mcpm3._domainkey", value: "dkim3.mcpmail.app" }
  ]
}

Check DNS verification status for a domain.

// Returns
{ domain: "acme.com", status: "verified",
  spf: "pass", dkim: "pass", dmarc: "pass" }

Send an email from a mailbox. If approval_mode is all or smart, the message enters the approval queue before sending. Returns a message ID and queue status.

// Returns
{ id: "msg_xK2mN...", status: "queued",
  queue_position: 3 }
// or with approval_mode: "none"
{ id: "msg_xK2mN...", status: "sent" }

List messages in a mailbox with filtering and pagination.

Get a single message with full body and parsed attachments.

// Returns
{
  id: "msg_...",
  from: "vendor@acme.com",
  to: "ops@your-company.com",
  subject: "RE: PO #4821",
  body: "Confirmed. Shipping Friday.",
  html: "...",
  thread_id: "thr_...",
  attachments: [{
    name: "invoice.pdf",
    content_type: "application/pdf",
    size: 48210,
    parsed: { text: "Invoice #9102..." }
  }],
  received_at: "2026-04-17T14:30:00Z"
}

Block until a matching message arrives or timeout expires. This is the key primitive — it turns email into a synchronous step in an agent workflow.

// Blocks until match or timeout
const reply = await mail.wait({
  mailbox: "mbx_ops",
  from: "vendor@acme.com",
  timeout: "48h"
})

if (reply.timed_out) {
  // No reply within 48h — send a follow-up
} else {
  // reply.body, reply.attachments, reply.parsed_attachments
}

Archive a message. Archived messages are retained but excluded from mail.list by default.

Parse attachments from a message into structured data. PDFs are extracted to text, CSVs are parsed to JSON arrays, images are OCR'd.

List messages pending approval.

Approve a queued message for sending. Optionally edit the message before it goes out.

Reject a queued message. It will not be sent.

List conversation threads in a mailbox.

Get all messages in a thread, in chronological order.

Add a contact to a named list. Used for auto-approve rules and recipient management.

Search contacts by email, name, or list.

Register a URL to receive real-time event notifications.