AgenticEmailService

emailmcp

Self-hosted SendGrid — powered by AI.

Your own email infrastructure. One MCP command provisions a cloud VPS, WireGuard tunnel, DKIM/SPF/DMARC, Let's Encrypt TLS, and authoritative DNS. No third-party email provider needed.

Or use it as a universal email client with 9 providers. Your choice.

Works with

Autonomous Mode  •  Provider Mode  •  Rules Engine  •  Install  •  API Docs

Two Modes

Self-Hosted (Autonomous Mode) — your own SendGrid

You:  "Set up my email server"
AI:   Creating OVH VPS in GRA11... done. IP: 51.38.x.x
      WireGuard config saved. Run: sudo wg-quick up ~/.emailmcp/wg-email.conf

You:  [connects WireGuard]
You:  "Resume setup"
AI:   Tunnel verified. Add these 2 DNS records at your registrar:
        NS   emailrelay.xyz  →  ns1.emailrelay.xyz
        A    ns1.emailrelay.xyz  →  51.38.x.x

You:  [adds DNS records]
You:  "Resume setup"
AI:   DNS propagated. TLS cert obtained. SMTP verified.
      Your email server is live.

You:  "Add company.com as a sending domain"
AI:   DKIM keys generated. Add these 4 records to company.com:
        MX    company.com  →  mail.company-com.emailrelay.xyz
        TXT   company.com  →  v=spf1 include:company-com.emailrelay.xyz -all
        CNAME emailmcp._domainkey.company.com  →  emailmcp._domainkey.company-com.emailrelay.xyz
        TXT   _dmarc.company.com  →  v=DMARC1; p=reject; adkim=s; aspf=s

You:  "Send hello@company.com a welcome email"
AI:   Sent. DKIM ✅ SPF ✅ DMARC ✅

What you get:

• Dedicated clean IP on a $3/mo VPS (OVH, Vultr, Hetzner, DigitalOcean)
• WireGuard tunnel — email flows through your IP, not a shared pool
• DKIM signing with your own 2048-bit RSA keys
• SPF hard fail (-all) — only your IP authorized
• DMARC strict alignment (adkim=s; aspf=s)
• Authoritative DNS on the VPS (CoreDNS) — you are your own nameserver
• Let's Encrypt TLS for SMTP STARTTLS
• PTR / reverse DNS set automatically
• Local mailbox storage — AI reads inbox via MCP, no IMAP needed
• Multi-tenant: add unlimited sending domains, each with its own DKIM keys
• Health monitoring with auto-restart

No SendGrid. No Mailgun. No monthly email bills. Your infrastructure, your keys, your data.

Provider Mode — 9 providers, zero lock-in

Same tool, different backend. Use any email provider:

Switch providers by changing one env var. Read inbox via IMAP with real-time IDLE push notifications.

Rules Engine

Email rules with MCP-triggered actions. Like server-side rules, but your AI controls them:

You:  "Create a rule: when emails from *@vip-client.com arrive, flag as VIP and forward to ceo@company.com"
AI:   Rule created: VIP Client Alert (priority 10)
      Match: from=*@vip-client.com
      Actions: flag(vip), forward(ceo@company.com)

8 action types: forward, auto_reply, webhook, flag, move, mcp_tool, log, reject

Enterprise patterns tested:

• Multi-department routing (sales/support/billing with different auto-replies)
• Cascading escalation (L1 → L2 → L3 with stop flags)
• Compliance (legal hold, GDPR data subject request detection, SOX flagging)
• DLP (flag emails containing sensitive patterns)
• Phishing protection (reject known bad domains)
• Audit trail (webhook every email to your audit system)
• Batch processing (50 concurrent emails, zero errors)

Rules fire on both autonomous inbound SMTP and IMAP IDLE real-time notifications.

IMAP IDLE — Real-Time Push

No polling. Instant notification when new email arrives:

You:  "Watch my work and personal email for new messages"
AI:   Watching work (me@company.com) and personal (me@gmail.com)
      New emails trigger rule evaluation automatically.

[New email arrives]
AI:   New email in work: "Server Down Alert" from monitoring@infra.com
      → Rule "L2 Infrastructure" matched → forwarded to infra-team@company.com

Works with any IMAP provider. Multi-account. Auto-reconnect on disconnect.

Install

Option A: npx (zero setup)

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "emailmcp"],
      "env": {
        "DEFAULT_PROVIDER": "autonomous",
        "EMAIL_DOMAIN": "company.com"
      }
    }
  }
}

Option B: Clone for autonomous mode

git clone https://github.com/nfodor/emailmcp.git
cd emailmcp && npm install
cp .env.example .env
# Set DEFAULT_PROVIDER=autonomous and EMAIL_DOMAIN

Then ask your AI: "Set up my email server"

Provider mode (any of 9 providers)

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "emailmcp"],
      "env": {
        "DEFAULT_PROVIDER": "mailgun",
        "MAILGUN_API_KEY": "key-your-api-key",
        "MAILGUN_DOMAIN": "mg.yourdomain.com",
        "FROM_EMAIL": "noreply@yourdomain.com",
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_EMAIL": "you@gmail.com",
        "IMAP_PASSWORD": "your-app-password"
      }
    }
  }
}

See .env.example for all provider configs (Mailgun, SendGrid, SES, Gmail, Resend, SMTP, MailHog, Autonomous).

MCP Tools

Email

Rules

Real-Time

Autonomous Server

Infrastructure

Architecture

                     ┌─────────────────────────────┐
                     │     Cloud VPS ($3/mo)        │
                     │                               │
Internet ──► port 25 ──► WireGuard ──────────────────┼──► Your Machine
                     │     ▲                         │     │
                     │     │ CoreDNS (port 53)       │     ▼
                     │     │ Let's Encrypt TLS       │   EmailMCP
                     │     │ iptables forwarding     │   ├── SMTP Receiver
                     └─────┼─────────────────────────┘   ├── Mailbox Store
                           │                              ├── Rules Engine
                           │                              ├── DKIM Signer
                      WireGuard                           ├── MCP Server
                      Tunnel                              └── Local API :41924
                           │
                     ┌─────┼───────┐
                     │  Your Machine│
                     │              │
                     │  Claude/     │
                     │  Cursor/     │◄──── MCP Protocol
                     │  Codex       │
                     └──────────────┘

Inbound: Internet → VPS port 25 → WireGuard → your machine → mailbox store → AI reads via MCP

Outbound: AI sends via MCP → DKIM signed → WireGuard → VPS clean IP → recipient MX

DNS: VPS runs CoreDNS as authoritative nameserver for your service domain

Provisioning Flow (Phased Wizard)

No chicken-and-egg. Each phase waits for its prerequisites:

State saved to ~/.emailmcp/provision-state.json. Run provision_resume after each action.

API Docs

When the local API is running (autonomous mode), Swagger UI is at:

http://127.0.0.1:41924/api-docs

Raw OpenAPI spec: http://127.0.0.1:41924/api-docs/swagger.json

Covers both the REST API and all MCP tools.

Development

git clone https://github.com/nfodor/emailmcp.git
cd emailmcp && npm install
npm test                     # 1266 tests, 103 sections
npm run test:watch           # Auto-rerun on changes

Test categories

E2E tests run real SMTP servers, send real emails via nodemailer, fire real rules, and verify the full pipeline. No mocks.

See CONTRIBUTING.md for how to write tests and add features.

Cloud Provider Pricing

All you need is WireGuard on the VPS. The cheapest VM handles it.

Troubleshooting