@mailiam/mcp-server

MCP (Model Context Protocol) server for Mailiam - enables AI agents to send and receive emails.

What is this?

This MCP server allows AI assistants like Claude to:

• ✉️ Send emails from your verified domains
• 📬 Receive and read emails from agent inboxes
• 💬 Reply to emails with SRS magic for identity preservation
• 📊 Check inbox statistics and manage email status

Perfect for building AI email assistants, automated support bots, or any agent that needs email capabilities.

Quick Start

1. Installation

The MCP server is designed to be run via npx (no installation needed):

npx @mailiam/mcp-server

Or install globally:

npm install -g @mailiam/mcp-server

2. Configuration

The MCP server requires environment variables:

export MAILIAM_API_KEY="mlm_sk_..."           # Your Mailiam Usage API key
export MAILIAM_AGENT_ADDRESS="[email protected]" # Optional: default agent address
export MAILIAM_API_URL="https://api.mailiam.dev" # Optional: custom API URL

3. Claude Desktop Setup

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mailiam": {
      "command": "npx",
      "args": ["-y", "@mailiam/mcp-server"],
      "env": {
        "MAILIAM_API_KEY": "mlm_sk_your_api_key_here",
        "MAILIAM_AGENT_ADDRESS": "[email protected]"
      }
    }
  }
}

4. Claude Code Setup

Add to your project's .claud/mcp.json:

{
  "mcpServers": {
    "mailiam": {
      "command": "npx",
      "args": ["-y", "@mailiam/mcp-server"],
      "env": {
        "MAILIAM_API_KEY": "mlm_sk_your_api_key_here",
        "MAILIAM_AGENT_ADDRESS": "[email protected]"
      }
    }
  }
}

Prerequisites

Before using the MCP server, you need to:

1. Get a Mailiam API Key

# Install Mailiam CLI
npm install -g mailiam

# Create Usage API key
mailiam keys create --name "MCP Server" --type usage

This gives you a key like mlm_sk_... with 1000 requests/hour.

2. Configure an Agent Inbox

Create or update your mailiam.config.yaml:

domains:
  yourdomain.com:
    agents:
      support-bot:
        address: "[email protected]"
        action: api  # Store emails in database instead of forwarding

Then push the config:

mailiam push

Now emails to [email protected] will be stored in the agent inbox and accessible via the MCP server!

Available Tools

Once configured, Claude will have access to these tools:

send_email

Send an email from a verified domain.

Parameters:

• from (required): Sender email address (must be from verified domain)
• to (required): Recipient email address
• subject (required): Email subject
• text (optional): Plain text body
• html (optional): HTML body

Example:

Send an email from [email protected] to [email protected] with subject "Welcome!" and text "Thanks for signing up!"

list_inbox

List emails in an agent inbox.

Parameters:

• address (required): Agent email address
• status (optional): Filter by status (unread, read, archived)
• limit (optional): Max emails to return (default: 50)
• offset (optional): Pagination offset
• since (optional): ISO timestamp for filtering

Example:

List unread emails for [email protected]

get_email

Get full details of a specific email.

Parameters:

• emailId (required): Email ID from list_inbox

Example:

Get email details for email_abc123

mark_email_read

Mark an email as read.

Parameters:

• emailId (required): Email ID

Example:

Mark email email_abc123 as read

reply_to_email

Reply to an email with SRS magic for identity preservation.

Parameters:

• emailId (required): Email ID to reply to
• subject (optional): Reply subject (defaults to "Re: original subject")
• bodyText (optional): Plain text reply
• bodyHtml (optional): HTML reply

Example:

Reply to email email_abc123 with text "Thanks for reaching out! We'll get back to you soon."

get_inbox_stats

Get inbox statistics (unread count, etc.).

Parameters:

• address (required): Agent email address

Example:

Get inbox stats for [email protected]

Usage Examples

Email Support Bot

Claude, check the support inbox for unread emails and reply to any urgent ones.

Claude will:

1. List unread emails for [email protected]
2. Read the content of each email
3. Determine urgency
4. Reply with appropriate responses
5. Mark emails as read

Email Notification System

Claude, send a weekly summary email to [email protected] with our key metrics.

Claude will:

1. Gather relevant metrics
2. Format them in a professional email
3. Send from [email protected]

Multi-Agent Email Router

agents:
  sales:
    address: "[email protected]"
    action: api
  support:
    address: "[email protected]"
    action: api
  billing:
    address: "[email protected]"
    action: api

Claude can monitor multiple inboxes and route/respond appropriately.

How It Works

Architecture

AI Agent (Claude) → MCP Server → Mailiam API → Email Infrastructure
                                        ↓
                                   Agent Inbox DB ← Inbound Emails (S3 → SNS → Queue Worker)

Inbound Email Flow

1. Email arrives at AWS SES
2. Stored in S3 bucket
3. SNS triggers webhook
4. Queue worker processes email
5. ApiEndpointHandler checks if address is an agent inbox
6. Email stored in agent_emails table
7. MCP server can query via /v1/agents/emails API

SRS Reply Magic

When agents reply to emails:

1. MCP server calls /v1/agents/emails/:id/reply
2. API creates an SRS (Sender Rewriting Scheme) mapping
3. Reply sent with From: [email protected] (verified domain)
4. If recipient replies, it routes back to the agent
5. Maintains conversation thread seamlessly

This is the magic that makes agent email work! No more noreply@ addresses.

Configuration Options

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MAILIAM_API_KEY | Yes | Usage API key (mlm_sk_...) | | MAILIAM_AGENT_ADDRESS | No | Default agent address for convenience | | MAILIAM_API_URL | No | Custom API URL (default: api.mailiam.dev) |

Agent Inbox Config

In mailiam.config.yaml:

domains:
  example.com:
    agents:
      agent-id:
        address: "[email protected]"  # Email address
        action: api                   # Must be "api" for MCP access
        webhook: "https://..."        # Optional: webhook for notifications

Actions:

• api: Store in database (accessible via MCP)
• forward: Forward to another address (not accessible via MCP)

Troubleshooting

"API key required" error

Make sure MAILIAM_API_KEY is set in your MCP server config.

"Email not found" when listing inbox

Check that:

1. Agent inbox is configured in mailiam.config.yaml
2. Config is pushed: mailiam push
3. Domain is verified: mailiam domains verify example.com
4. Emails have been sent to that address

"Domain not found" when sending

Verify your domain:

mailiam domains verify example.com

Follow the DNS setup instructions.

MCP server not appearing in Claude

1. Restart Claude Desktop/Code
2. Check config file syntax (valid JSON)
3. Verify npx is in PATH
4. Check Claude's MCP logs

API Rate Limits

| Key Type | Rate Limit | Best For | |----------|-----------|----------| | Usage (mlm_sk_*) | 1000/hour | MCP server, production bots | | Admin (mlm_sk_admin_*) | 10000/hour | High-volume agents |

Security Best Practices

1. Never commit API keys - use environment variables
2. Use Usage keys - not Admin keys (principle of least privilege)
3. Rotate keys regularly - create new keys, revoke old ones
4. Monitor usage - check mailiam usage for anomalies
5. Verify domains - only send from domains you control

Advanced Usage

Custom Prompts

You can create custom prompts to guide Claude's email behavior:

# .claude/prompts/email-support.md

When handling customer support emails:

1. Always be friendly and professional
2. Acknowledge the issue in the first line
3. Provide clear, actionable steps
4. End with "Let me know if you need anything else!"
5. Mark emails as read after replying

Then: Claude, use the email-support prompt to handle the inbox.

Integration with Other Tools

Combine with other MCP servers:

{
  "mcpServers": {
    "mailiam": { ... },
    "database": { ... },
    "crm": { ... }
  }
}

Claude can now:

• Check email inbox
• Look up customer in database
• Update CRM with email interaction
• Send personalized reply

Examples Repository

Check out examples/mcp-server/ for:

• Email support bot
• Newsletter automation
• Sales lead responder
• Billing inquiry handler

Contributing

Contributions welcome! Please see CONTRIBUTING.md.

License

MIT

Support

• Documentation: https://mailiam.io/docs/mcp
• GitHub Issues: https://github.com/mailiam/mailiam/issues
• Email: [email protected]
• Discord: https://discord.gg/mailiam

Related Packages

• @mailiam/node - Node.js SDK for server-side email
• @mailiam/client - Browser client for form submissions
• mailiam CLI - Command-line interface

Built with ❤️ by the Mailiam team

Making email infrastructure simple for AI agents