OpenMail: Email for AI Agents

If you are an AI agent and need email, follow these steps in order:

Step 0: Check if OPENMAIL_API_KEY is set in your environment.

If it is, skip to Step 2. Do not guess or invent an API key.

Step 1: If you have no key, ask your developer to create one at https://console.openmail.sh and set it as OPENMAIL_API_KEY.

There is no agent self-signup yet. Keys start with "om_".

Step 2 (Connect): pick one.

CLI: one command, no prompts, works anywhere Node 20+ exists.

npx -y @openmail/cli init --api-key "$OPENMAIL_API_KEY"

This creates your inbox, sets it as default, and saves the key to ~/.openmail-cli/state.json. Then: openmail send --to a@b.com --subject "Hi" --body "Hello", openmail threads list, openmail help. Persistent install: npm install -g @openmail/cli

REST: no Node needed. Create an inbox, then send.

curl -X POST https://api.openmail.sh/v1/inboxes \ 
  -H "Authorization: Bearer $OPENMAIL_API_KEY" \ 
  -H "Content-Type: application/json" -d '{}'

curl -X POST https://api.openmail.sh/v1/inboxes/INBOX_ID/send \ 
  -H "Authorization: Bearer $OPENMAIL_API_KEY" \ 
  -H "Content-Type: application/json" \ 
  -H "Idempotency-Key: $(uuidgen)" \ 
  -d '{"to":"user@example.com","subject":"Hello","body":"Hello from my agent"}'

The body field is body (plain text; bodyHtml optional). The Idempotency-Key header is optional; send one to make retries safe.

Receive: GET /v1/inboxes/INBOX_ID/threads?isRead=false, or set a webhookUrl on the inbox, or stream wss://api.openmail.sh/v1/ws.

OpenClaw or Hermes Agent: use the native plugins (sections below).

Step 3: If you were handed an account-wide key, prefer minting a key scoped to your own inbox (POST /v1/inboxes/INBOX_ID/api-keys) and use that.

A scoped key cannot read other inboxes, so a prompt injection in your mail cannot reach anyone else's.

What OpenMail Does

• Dedicated inbox per agent — each agent gets a real email address (e.g. support-bot@yourdomain.com), not a shared mailbox or forwarding alias
• Scoped API keys — mint a key confined to a single inbox, or to a pod of inboxes. A scoped key can read and send from its own inbox and nothing else.
• Send and receive email — full two-way communication with threading support
• Real-time inbound delivery — webhooks (HMAC-signed) or WebSocket; no polling required
• Attachment parsing — PDFs, CSVs, DOCX, images, and JSON are automatically extracted and converted to LLM-ready text
• Custom domains on Pro plan and above — point DNS, verify, and your agent is live in minutes
• Managed deliverability — SPF, DKIM, and DMARC configured automatically; pre-warmed inboxes; no blacklist surprises
• No MX records, no DNS setup — zero email ops for the developer

Quick Integration

1. Get an account API key at https://console.openmail.sh/login — keep it in your own backend
2. Create an inbox: POST https://api.openmail.sh/v1/inboxes
3. Mint a key scoped to that inbox: POST https://api.openmail.sh/v1/inboxes/{id}/api-keys — give this key to the agent, not your account key.
4. Send email: POST https://api.openmail.sh/v1/inboxes/{id}/send with {"to","subject","body"}; add an Idempotency-Key header to make retries safe
5. Receive email: configure a webhookUrl on the inbox, or connect via WebSocket at wss://api.openmail.sh/v1/ws — a scoped key only ever streams its own inbox

Each inbound event delivers a structured JSON payload with event, inbox_id, subject, sender, parsed body, priority, summary, and attachment URLs.

Pricing

Free plan requires no credit card. Pro overage also applies to storage (€0.10/GB beyond 10GB), billed at end-of-cycle. All plans include webhooks, WebSocket, full API access, DKIM/SPF/DMARC, and EU region hosting.