Anil-matcha/open-agent-email

Open Agent Email – Email inboxes for AI agents (self‑hosted)

What it is

• A self‑hosted service that gives each AI agent its own real email address and mailbox. It handles incoming SMTP, stores messages, and lets agents read, reply, forward, schedule, or request human approval before sending risky mail.
• Exposes the functionality via a REST API, Python & TypeScript SDKs, a CLI, WebSocket live‑stream, webhooks, and MCP (the protocol used by Claude Code, Cursor, etc.).

Why it matters for AI agents

• Agents that interact with people often need email (support, sign‑ups, invoices). Using a generic sending service gives the agent no identity, no thread history, and no safety guardrails.
• Open Agent Email provides per‑agent inboxes, conversation threading, SPF/DKIM/DMARC validation, prompt‑injection screening, and an optional human‑approval gate.

How it works

People / other agents  →  MX record → Open Agent Email (SMTP listener) → store in DB
                                                   ↑
                                                   │
                                   Agent ↔ REST / SDK / MCP / Webhooks / CLI

• Incoming mail is accepted only for inboxes that exist, validated (SPF/DKIM/DMARC), scanned for AI‑specific tricks, and saved.
• Outgoing mail is sent through any SMTP relay you configure (SES, SendGrid, Resend, etc.). If the approval gate is enabled, the message is held until a human clicks an approve/reject link.

Key features

Category	Highlights
Inboxes & threads	Unlimited inboxes, proper reply threading, labels, search, trash/restore, scheduled send (up to 90 days), attachments ≤10 MB, signed download links
Safety	Prompt‑injection detection, optional virus scan, approval gate with expiry, per‑inbox API keys (read‑only, send, review), recipient blocking, one‑click unsubscribe
Auth & validation	SPF/DKIM/DMARC checks stored per message; strict‑DMARC failures are rejected
Sending	Any SMTP relay, retry with back‑off, idempotent keys, full send history
Delivery tracking	Built‑in SES event handling (delivered, bounced, complaints) and automatic suppression
Domain support	Add custom domains, get DNS records, DKIM‑sign outgoing mail per domain
Webhooks & events	Signed webhooks, retry logic, replay, searchable event log, per‑inbox or global endpoints
Contacts & templates	Address book, CSV import, consent notes, follow‑up reminders, reusable templates with preview
Developer tools	OpenAPI spec, Python & TypeScript SDKs (no runtime deps), oae CLI, 96 MCP tools, cursor‑style pagination, structured error codes
Ops	SQLite (default) or PostgreSQL, Alembic migrations, metrics endpoint, backup/restore scripts, Docker Compose, example nginx deploy

Typical use cases

• Support inbox for a chatbot: support@brand.com can read tickets, draft replies, and hold any risky response for a human.
• Sign‑up verification: an agent creates a user, then reads the confirmation code from its own mailbox.
• Outbound outreach with safety net: draft campaigns, schedule sends, and require approval before any email leaves.
• Agent‑to‑agent communication: each agent has a real address, enabling email‑based workflows across services.
• Event‑driven workflows: incoming mail triggers n8n/Zapier/webhooks, which can launch further automation.
• Personal concierge: a local agent watches an inbox via the live stream, drafts replies, and you approve via a simple link.

Getting started

1. Clone the repo and run the dev script (requires Python 3.11). The server starts on http://127.0.0.1:8000 and prints an admin key.
2. (Optional) Run the Next.js dashboard: cd client && npm install && npm run dev (http://localhost:3000).
3. Create an inbox via the API/CLI, configure an SMTP relay, and point your domain’s MX record at the server (port 25).
4. Use the Python or TypeScript SDK, the MCP command, or simple curl calls to list, read, and send mail.

Tech stack

• Server: Python 3.11, FastAPI, async SQLAlchemy, Alembic, aiosmtpd for SMTP listening.
• Database: SQLite (default) or PostgreSQL.
• Dashboard: Next.js 16, React, Tailwind CSS.
• SDKs: Python & TypeScript, zero runtime dependencies.
• Packaging: Docker Compose + example production deploy (nginx, backup scripts).

Status & community

• Active development, currently single‑user (one admin key, no multi‑tenant accounts yet).
• Tested locally and on a PostgreSQL 16 setup with Amazon SES integration.
• Join the Discord or open issues/PRs on GitHub.

License: Apache 2.0.