Getting started

MCPMail quickstart

MCPMail gives your AI agent its own email address. Your agent can send and receive email as your company domain, parse attachments, wait for replies, and route actions — all via MCP tools.

This guide gets you from zero to a working agent inbox in under five minutes.

1. Get your API key

Sign up at mcpmail.app and create an API key from your dashboard. The free Dev tier gives you one mailbox and 100 messages per day — no credit card required.

# Your API key looks like this
mcpm_sk_live_a8Kq7fR2xZ...

2. Connect the MCP server

Add MCPMail to your MCP client. Here's the config for Claude Desktop:

{
  "mcpServers": {
    "mcpmail": {
      "url": "https://mcpmail.app/mcp",
      "headers": {
        "Authorization": "Bearer mcpm_sk_live_..."
      }
    }
  }
}

For other MCP clients, use the SSE endpoint directly:

https://mcpmail.app/mcp?key=mcpm_sk_live_...

3. Provision a mailbox

Ask your agent to create a mailbox, or call the tool directly:

mailbox.create({
  address: "ops@your-company.com",
  display_name: "Operations",
  approval_mode: "all"
})

This returns a mailbox ID (mbx_...) and an ingest address. The ingest address is where you'll forward email from your existing provider.

approval_mode: "all" means every outbound message is held for human review before sending. This is the recommended default. See Approval Queue for auto-approve options.

4. Set up email forwarding

In your email provider (Google Workspace, Microsoft 365, etc.), create a forwarding rule that sends mail for ops@your-company.com to the ingest address MCPMail provided.

For Google Workspace:

  1. Go to Admin Console → Gmail → Routing
  2. Add a routing rule for the recipient address
  3. Set "Also deliver to" with the MCPMail ingest address

For Microsoft 365:

  1. Go to Exchange Admin → Mail flow → Rules
  2. Create a rule matching the recipient
  3. Add "Redirect" to the MCPMail ingest address

5. Verify your domain (for sending)

To send email as your domain, you need to add DNS records:

domain.verify({ domain: "your-company.com" })

This returns the DNS records to add:

  • SPF — Add include:mcpmail.app to your existing SPF record
  • DKIM — Three CNAME records for cryptographic signing
  • DMARC — Suggested DMARC policy (if you don't have one)

See Domain Setup for the complete walkthrough.

6. Send your first email

await mail.send({
  mailbox: "mbx_ops",
  to: "vendor@acme.com",
  subject: "Purchase Order #4821",
  body: "Please confirm receipt of the attached PO.",
  attachments: [{
    name: "po-4821.pdf",
    content_type: "application/pdf",
    data: base64_pdf
  }]
})

With approval_mode: "all", this message goes to the approval queue. A human reviews and approves it before it sends.

7. Wait for a reply

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

// reply.subject, reply.body, reply.attachments
// reply.parsed_attachments — structured data from PDFs/CSVs

The agent blocks until the reply arrives or the timeout expires. No polling, no webhooks, no state machine. Just send and wait.

Next steps