Why 🎀 AgenticMail?

AI agents need to communicate with the real world. Email is the universal communication protocol — every person and business has an email address. AgenticMail bridges the gap between AI agents and email by providing:

• Isolated mailboxes — each agent has its own email address, inbox, and credentials. Agents can't read each other's mail.
• Internet email connectivity — two gateway modes to send/receive real email (Gmail relay or custom domain with DKIM/SPF/DMARC).
• Security guardrails — outbound scanning prevents agents from leaking API keys, passwords, or PII. Blocked emails require human approval.
• Agent collaboration — agents can email each other, assign tasks, and make synchronous RPC calls.
• SMS / Phone number access — integrate Google Voice for SMS receive/send, verification code extraction, and phone number access for AI agents.
• Smart orchestration — call_agent replaces basic sub-agent spawning with auto mode detection, dynamic timeouts, runtime tool discovery, and async execution for long-running tasks.
• Tool integrations — 62 MCP tools for any AI client, 63 OpenClaw tools, and a 44-command interactive shell.
• Self-updating — agenticmail update checks npm, verifies OpenClaw compatibility, and updates both packages automatically.

Features

Email Operations

• Send email with text, HTML, attachments, CC/BCC, reply-to, and custom headers
• Receive email via IMAP with real-time SSE event streaming (IMAP IDLE)
• Reply and forward with proper In-Reply-To and References headers for threading
• Search by sender, subject, body text, date range, read/unread status
• Folders — create, list, move messages between folders
• Batch operations — mark read/unread, delete, move multiple messages at once
• Drafts — save, edit, and send draft emails
• Templates — reusable email templates with variable substitution
• Scheduled sending — queue emails for future delivery
• Signatures — per-agent email signatures
• Tags — label and categorize messages
• Contacts — manage address book per agent

Multi-Agent

• Account management — create, list, delete agents with unique email addresses
• Agent-to-agent email — agents can email each other directly via @localhost
• Task system — assign tasks to agents, claim, submit results, track status
• RPC calls — synchronous agent-to-agent calls with timeout (long-poll + SSE notification)
• Agent directory — discover other agents by name

Gateway (Internet Email)

• Relay mode (beginner) — use your existing Gmail or Outlook as a relay. Emails appear as you+agentname@gmail.com. Setup takes 2 minutes.
• Domain mode (advanced) — custom domain via Cloudflare. Agents send from agent@yourdomain.com with full DKIM signing, SPF, and DMARC records.
  • Automatic DNS configuration (MX, SPF, DKIM TXT, DMARC, tunnel CNAME)
  • Cloudflare Tunnel for secure inbound traffic without exposing ports
  • Cloudflare Email Worker for Email Routing (catch-all → worker → AgenticMail)
  • Optional Gmail SMTP outbound relay for residential IPs without PTR records
  • Domain purchase via Cloudflare Registrar
  • DNS backup before any modifications
  • Automatic @domain email alias for all existing agents

Security

• Outbound guard — scans every outgoing email for sensitive data patterns:
  • API keys and tokens (AWS, OpenAI, Stripe, GitHub, etc.)
  • Passwords and credentials
  • Private keys (SSH, PGP, RSA)
  • PII patterns (SSN, credit card numbers)
  • Internal URLs and configuration data
  • Blocked emails are held for human-only approval (agents cannot self-approve)
• Spam filter — rule-based scoring engine for inbound email:
  • Categories: phishing, scam, malware, commercial spam, social engineering, lottery scam
  • Configurable threshold (default: 40)
  • Skips internal agent-to-agent emails
  • Runs on both relay inbound and SSE event streams
• Human-only approval flow — when an agent's email is blocked:
  • The agent is informed the email was blocked and told to notify their owner
  • The owner receives a notification email with full blocked email content, warnings, and pending ID
  • Only the master key holder can approve or reject (POST /mail/pending/:id/approve)
  • Agents can list and view their own pending emails but cannot approve or reject them
  • System prompt guidelines instruct agents to inform their owner and wait, never attempt to bypass
• DKIM/SPF/DMARC — automatic DNS setup in domain mode for email authentication
• Rate limiting — configurable per-endpoint rate limits

SMS / Phone Number Access

• Google Voice integration — give agents a real phone number via Google Voice
• Direct Voice web reading (primary, instant) — reads SMS directly from voice.google.com via browser
• Email forwarding (fallback) — Google Voice forwards SMS to email, agent auto-detects and records them during relay polling
• Separate Gmail polling — for users whose GV Gmail differs from relay email, runs a dedicated IMAP poll
• Verification codes — automatic extraction of OTP/verification codes from SMS (4-8 digit, alphanumeric, Google G-codes)
• Send SMS — record outbound messages, send via Google Voice web automation
• Smart setup wizard — validates Gmail/GV email matching, warns about mismatches, collects separate credentials when needed

Smart Orchestration (call_agent)

• Auto mode detection — reads task complexity, picks light/standard/full mode automatically
• Dynamic timeouts — 60s for quick tasks, 5+ minutes for deep research, 1 hour for async
• Runtime tool discovery — probes host config for available tools instead of static deny lists
• Async execution — long-running tasks run independently, auto-compact context, email results when done
• Structured RPC — sub-agents return JSON, not raw text

Integrations

• MCP server — 62 tools for any MCP-compatible AI client
• OpenClaw plugin — 63 tools with skill definition and system prompt guidelines
• REST API — 75+ endpoints, OpenAPI-style, Bearer token auth
• SSE events — real-time inbox notifications via Server-Sent Events
• Interactive CLI — 44 shell commands with arrow key navigation, body previews, retry logic
• Self-updating — agenticmail update or /update in shell, with OpenClaw compatibility check

Architecture

                  ┌──────────────────────────────────────────────────┐
                  │                    AgenticMail                    │
                  │                                                  │
 AI Client ─MCP─> │  @agenticmail/mcp    (62 tools, stdio transport) │
                  │       │                                          │
 OpenClaw ─────>  │  @agenticmail/openclaw  (63 tools, plugin)       │
                  │       │                                          │
 HTTP clients──>  │       ▼                                          │
                  │  @agenticmail/api     (Express, 75+ endpoints)   │
                  │    ├── Authentication  (master key + agent keys)  │
                  │    ├── Rate limiting   (per-endpoint)             │
                  │    ├── SSE streaming   (real-time inbox events)   │
                  │    └── Spam filter + Outbound guard               │
                  │       │                                          │
                  │       ▼                                          │
                  │  @agenticmail/core    (SDK layer)                 │
                  │    ├── AccountManager  (CRUD agents in Stalwart)  │
                  │    ├── MailSender      (SMTP, nodemailer)         │
                  │    ├── MailReceiver    (IMAP, imapflow)           │
                  │    ├── InboxWatcher    (IMAP IDLE → events)       │
                  │    ├── GatewayManager  (relay + domain routing)   │
                  │    │   ├── RelayGateway      (Gmail/Outlook)      │
                  │    │   ├── CloudflareClient   (DNS, tunnels, etc) │
                  │    │   ├── TunnelManager      (cloudflared)       │
                  │    │   ├── DNS