GitHub - Mnexa-AI/e2a: Authenticated email gateway for AI agents — SPF/DKIM verified inbound, HMAC-signed delivery, webhook + WebSocket fan-out, CLI + SDKs
Pangram verdict · v3.3
We believe that this document is a mix of AI-generated, and human-written content
AI likelihood · overall
MixedArticle text · 1,519 words · 6 segments analyzed
Authenticated email gateway for AI agents. Receive emails as webhooks or via WebSocket, send emails through an HTTP API, and verify the identity of every sender — humans and other agents alike.
Authenticated transport — SPF/DKIM verified on inbound; HMAC-signed X-E2A-Auth-* headers on every delivery Two delivery modes — webhook (cloud agents) or WebSocket (local agents, no public URL needed) Outbound API — agents send to other agents (SMTP relay) or humans (upstream SMTP, e.g. SES, Resend) Human in the loop — opt-in approval gate that holds outbound mail until a reviewer approves via dashboard, magic-link email, or CLI CLI + SDKs — TypeScript and Python SDKs, plus a e2a CLI for everyday agent ops
e2a-demo-1080p-v2.mp4
Use it You can either use the hosted instance or self-host.
Hosted — sign up at e2a.dev. Includes the shared agents.e2a.dev domain for instant slug-based onboarding (no DNS setup), a dashboard, and managed deliverability. Self-host — see Quickstart and Deployment. Every feature works the same; the shared-domain slug shortcut just needs you to point a mail domain at your relay and set shared_domain in config.yaml.
How it works Human (Gmail/Outlook) │ ▼ SMTP ┌──────────────┐ │ e2a relay │ ← MX record for your agent domain points here │ │ │ 1. Verify │ ← SPF/DKIM check on the inbound message │ 2. Sign │ ← HMAC-signed X-E2A-Auth-* headers │ 3. Deliver │ └──────────────┘ │ ├──▶ Cloud-mode agent: HTTPS webhook POST │ └──▶ Local-mode agent: store + WebSocket notification │ ▼ e2a listen (CLI) or client.listen() (SDK)
Inbound flow: SMTP → SPF/DKIM check → agent lookup → HMAC-sign auth headers → webhook or WebSocket delivery.
Outbound flow: API call → optional HITL hold → SMTP relay (agent-to-agent) or upstream SMTP (agent-to-human). Quickstart Requires Docker. git clone https://github.com/Mnexa-AI/e2a.git cd e2a docker compose up -d Postgres comes up first (migrations run automatically), then the API server, then the dashboard. Three host ports:
:8080 — HTTP API :2525 — SMTP relay :3000 — Dashboard (Caddy + Next.js, proxies /api/* to the API server)
Health check: curl http://localhost:8080/api/health # {"status":"ok"} Open http://localhost:3000 in a browser to view the dashboard. Sign-in requires Google OAuth credentials configured in config.yaml; for an API-only smoke test you can skip the dashboard and use the bootstrap flow below. Create your first user and API key (no OAuth required): docker compose exec e2a e2a -config /etc/e2a/config.yaml -bootstrap-email you@example.com # User: you@example.com (id=...) # API key: e2a_... Save the key — it's only shown once. Register an agent and confirm it works: KEY=e2a_... curl -X POST http://localhost:8080/api/v1/agents \ -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"slug":"my-bot","agent_mode":"local"}'
curl -H "Authorization: Bearer $KEY" http://localhost:8080/api/v1/agents To receive real inbound mail, point a domain's MX record at your relay host:
A: your-domain.com → server IP MX: your-domain.com → your-domain.com (priority 10)
Then register and verify the domain through the API (see Domains). Without DNS, the API still works for testing — but external email won't reach your relay.
Upgrades and migrations. The compose file mounts migrations/ into Postgres' init directory, which only runs on first start (when the data volume is empty).
When you upgrade e2a and pull a new schema migration, you must apply it manually: docker compose exec postgres sh -c \ 'for f in /docker-entrypoint-initdb.d/*.sql; do psql -U e2a -d e2a -f "$f" -v ON_ERROR_STOP=1; done' The migration files are idempotent (CREATE TABLE IF NOT EXISTS, ALTER TABLE … ADD COLUMN IF NOT EXISTS) so re-running them is safe.
Concepts Agent modes Agents operate in one of two modes, set via agent_mode at registration:
Mode Delivery Public URL needed?
cloud (default) HTTPS webhook POST to webhook_url Yes
local WebSocket notification + REST fetch No
Local-mode agents accumulate "unread" messages while disconnected; on reconnect, the server drains them as WebSocket notifications. Both modes can also poll messages via the REST API. Auth headers Every email delivered through e2a (webhook or WebSocket-fetched) carries signed headers:
Header Description
X-E2A-Auth-Verified true if domain-level auth (SPF or DKIM) passed
X-E2A-Auth-Sender Verified sender email or agent domain
X-E2A-Auth-Entity-Type human or agent
X-E2A-Auth-Domain-Check SPF/DKIM result string (e.g. spf=pass; dkim=none)
X-E2A-Auth-Delegation agent={id};human={id} if an active delegation binding exists
X-E2A-Auth-Timestamp RFC3339 timestamp
X-E2A-Auth-Message-Id Internal e2a message ID this delivery is for
X-E2A-Auth-Body-Hash Hex SHA-256 of the raw message bytes
X-E2A-Auth-Signature HMAC-SHA256 over a canonical string of the above
The signature covers: verified \n sender \n entity_type \n domain_check \n delegation \n timestamp \n message_id \n body_hash
The MAC binds to both message_id and a SHA-256 of the raw message body.
Substituting either invalidates the signature, so an attacker who captures one delivery cannot replay the auth claim on a different message or under a modified body. Verifying the signature The X-E2A-Auth-Verified field is the server's claim — anyone who can reach your webhook URL can set it. To make a security decision, verify the signature with one of your account's signing secrets (manage them in the dashboard's Settings → Webhook signing secrets, or via /api/v1/users/me/signing-secrets). The SDKs gate field access behind verification by default — accessing email.sender, email.subject, etc. on an unverified webhook payload raises UnverifiedEmailError, so you can't accidentally trust attacker-controllable fields. The one-call shortcut: from e2a.v1 import E2AClient client = E2AClient() # reads E2A_API_KEY email = client.parse_webhook(request_body) # reads E2A_WEBHOOK_SECRET; raises on bad signature # safe to use email.sender, email.subject, … import { E2AClient } from "@e2a/sdk"; const email = await client.parseWebhook(req.body); // throws on bad signature Both forms read the secret from E2A_WEBHOOK_SECRET by default; pass it explicitly as a second argument if you keep it elsewhere. Under the hood the verify step checks, in order: body_hash matches the raw message bytes, HMAC matches the canonical auth string, and timestamp is within a 5-minute replay window. Emails returned by client.get_message(...) are pre-verified — the bearer token already authenticated the channel — so field access works directly without a verify step. (Listing endpoints like get_messages / listMessages return lightweight summaries, not InboundEmail, so the gate doesn't apply.) Conversation threading Both send and reply accept an opaque conversation_id. e2a propagates it to the recipient on delivery via payload.conversation_id, surfaced in this priority order:
X-E2A-Conversation-Id header — authoritative for e2a-to-e2a traffic. Only honored when the SMTP envelope MAIL FROM originates from this relay, so external senders cannot forge it. In-Reply-To / References lookup — standard RFC 5322 threading, scoped to the recipient agent's own messages. Covers humans replying from Gmail/Outlook.
First contact from a human arrives with conversation_id: null — the agent should assign a new id before replying. Human in the loop (HITL) When an agent has HITL enabled, outbound send and reply calls do not dispatch immediately. The message is stored with status pending_approval and the API returns HTTP 202 Accepted. A reviewer must approve it before delivery; otherwise, after a configurable TTL, the message expires into expired_approved (auto-sent) or expired_rejected (discarded), depending on the agent's hitl_expiration_action. Reviewers can approve or reject via:
Dashboard / API — POST /api/v1/messages/{id}/approve or /reject Magic-link email — sent automatically when HITL fires; one-click GET /api/v1/approve?token=… and /reject?token=… URLs (requires E2A_PUBLIC_URL and outbound SMTP configured) CLI — e2a pending lists held messages
Enable HITL on an agent via PUT /api/v1/agents/{email} with hitl_enabled: true and an optional hitl_expiration_action and TTL. API All endpoints are under /api/v1 unless noted. Auth is Authorization: Bearer <api_key> except for /api/health, /api/v1/info, /api/feedback, and the HITL magic-link routes. Path parameters containing @ (agent emails) must be URL-encoded. The surface covers domain registration + verification, agent CRUD, inbound/outbound messages, HITL approve/reject (API key or signed magic-link token), GDPR-style export and deletion, and a WebSocket channel for local-mode agents. See docs/api.md for the full endpoint reference, or web/public/openapi.yaml for the machine-readable spec. CLI npm install -g @e2a/cli e2a login
Command Description
e2a agents register <slug> Register <slug>@<shared-domain>. The deployment's shared domain is auto-discovered after e2a login and cached in ~/.e2a/config.json.
e2a agents list List your agents
e2a agents update <email> Update an agent (webhook URL, mode, HITL)
e2a agents delete <email> Delete an agent
e2a listen Listen for emails over WebSocket (real-time)
e2a listen --json Output one full message JSON per line
e2a listen --forward <url> Forward each message as HTTP POST to a local URL
e2a inbox List recent messages
e2a read <id> Read a message
e2a reply <id> --body … Reply to a message
e2a send --to … --subject … --body … Send an email
e2a pending List HITL messages awaiting approval
e2a config View or update CLI config
The listen --forward mode also supports OpenAI Responses API forwarding via --forward-token, which formats each inbound email as a Responses payload and auto-replies with the model's output: e2a listen --forward http://localhost:18789/v1/responses --forward-token <token> See cli/README.md for full reference. SDKs Python pip install e2a # webhook mode pip install 'e2a[ws]' # adds WebSocket support from e2a.v1 import E2AClient
client = E2AClient() # reads E2A_API_KEY email = client.parse_webhook(request_body) # parse + HMAC-verify (reads E2A_WEBHOOK_SECRET) print(email.sender, email.subject) email.reply("Got it!", conversation_id="conv_123") WebSocket (local agents): from e2a.v1 import AsyncE2AClient
async with AsyncE2AClient(api_key="e2a_…") as client: async for notif in client.listen("bot@your-domain.com"): # notif is lightweight metadata — fetch the body when you want it email = await client.get_message(notif.message_id) await email.reply("Got it!") See sdks/python/README.md. TypeScript npm install @e2a/sdk See sdks/typescript/README.md.