Email MCP Server
MCP server wrapping IMAP/SMTP with persistent IDLE, DKIM/SPF validation, and policy enforcement.
Build
cd workspace/email-mcp
go mod tidy
go build -o email-mcp .
Config
Copy config.json.example to config.json and fill password:
{
"host": "mail.example.net",
"port": 993,
"smtp_port": 465,
"username": "[email protected]",
"password": "...",
"policy": {
"always_bcc": "[email protected]",
"trusted_senders": ["[email protected]"],
"trusted_authserv_ids": ["mail.example.com"],
"dkim_fail_allowlist": ["newsletters.example.com"],
"dkim_enforced_senders": ["[email protected]"],
"allowed_from_addrs": ["example.com"]
}
}
- Sender trust: Only addresses in
policy.trusted_sendersare treated as actionable. Untrusted senders return content withoutpolicy_actionhints. - Always BCC: Every outbound send automatically BCCs
policy.always_bcc. - Safe-delete:
mail.expire,mail.move, andmail.trashuse UID EXPUNGE (RFC 4315) — only the target message is expunged, never other\Deletedmessages in the folder. - Attachment sandbox:
mail.sendattachment reads are restricted topolicy.attachment_allow_dirs(default:/tmp). Symlinks escaping the allowlist are rejected. - Signature verification: DKIM/SPF/DMARC with client-side DKIM fallback. When
trust_mta_auth: true, trustsAuthentication-Resultsheaders fromtrusted_authserv_idsonly. DKIM is now only enforced for senders listed indkim_enforced_senders(e.g.["[email protected]"]); for all other senders DKIM failures are tolerated, but SPF is still validated — an SPFfailstill blocks delivery. Use full addresses or bare domains (subdomain match:mail.example.commatchesexample.com). - From address allowlist:
allowed_from_addrsrestricts which domains / addressesmail.sendcan use in theFromheader. - Retention: Expire after 48h (configurable per-folder).
mail.expireMOVEs to Trash, never hard-deletes, logs every message. - Forwarded emails:
mail.fetch_attachmentsauto-extracts.emlattachments from forwarded emails. - Header security: All outbound headers are RFC 2047-encoded.
Fromdisplay names are structured vianet/mail.Address— prevents header-injection spoofing. - Idempotency: Duplicate
mail.sendcalls with identical recipients, subject, body, html, from_addr, and attachments are blocked within a 60s window.
Integration
- MCP events:
mail.received,mail.error— pushed over MCP socket / WebSocket / webhook - IMAP IDLE: Persistent connection with automatic reconnect — replaces polling
- REST API: Authenticated HTTP API (
/api/v1/tools/call) for remote access from Sanctum or other HTTP clients - Webhooks: New-mail notifications POSTed to
api.webhook_urlwith 5s timeout, never blocks IDLE - Email client: CLI wrapper at
bob/email-mcp-client—email search,email read,email send,email mailboxes, etc.
Transport Modes
The REST API and WebSocket run alongside any of the other modes. The HTTP render server, REST API, and WebSocket use separate ports.