# 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.
#
# Full docs for LLMs: https://docs.openmail.sh/llms-full.txt
# Agent skill (Claude Code, Cursor, Codex): npx skills add openmailsh/skills

# OpenMail

> Email API for AI agents. Give any agent its own email address with one API call.

OpenMail is email infrastructure purpose-built for AI agents. Every agent gets a dedicated inbox on @omail.sh (or your own domain on Pro plan and above), full send and receive capabilities, real-time delivery via webhooks or WebSocket, and attachments parsed into LLM-ready text.

## 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, so a prompt injection in one agent's mail can't reach another agent's inbox
- **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. The token is returned once
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.

## CLI

One-shot setup (no install, no prompts):

```
npx -y @openmail/cli init --api-key om_xxx
```

Or install globally:

```
npm install -g @openmail/cli
openmail init --api-key om_xxx
```

`openmail init` creates your first inbox, saves it as the default, and stores the key in `~/.openmail-cli/state.json`, so later commands need no env var. Without a TTY it never prompts. The CLI covers inboxes, sending, threads, attachments, pods, custom domains, and sender policy. An agent skill for Claude Code, Cursor, and Codex lives at https://github.com/openmailsh/skills (`npx skills add openmailsh/skills`).

## OpenClaw Integration

`@openmail/openclaw` is a native OpenClaw channel plugin (https://github.com/openmailsh/openclaw-plugin):

```
openclaw plugins install clawhub:@openmail/openclaw
openclaw channels add --channel openmail --api-key <key>
openclaw gateway restart
```

Mail from people wakes the agent as a conversation and its reply goes out in-thread. Automated mail is announced as information; spam is dropped. Modes: `channel` (default), `notify`, `tool`. The plugin bundles the CLI as `openclaw openmail -- <command>`. Docs: https://docs.openmail.sh/integrations/openclaw

## Hermes Agent Integration

`openmailsh/hermes-plugin` is a native platform for Nous Research's Hermes Agent (https://github.com/openmailsh/hermes-plugin):

```
hermes plugins install openmailsh/hermes-plugin --enable
hermes openmail setup
hermes gateway run
```

`hermes openmail setup` asks for an API key of any scope, picks or creates the inbox, and writes `~/.hermes/.env`; `hermes openmail doctor` checks it. Mail from people wakes the agent and its answer goes out as the reply in the same thread. Automated, marketing, and bounce mail reach the agent as a notification; spam and malicious mail never reach it. Modes: `channel` (default), `notify` (summary to your home channel, never to the sender), `tool` (no inbound). Native tools send, reply, read threads, and create inboxes and keys. Docs: https://docs.openmail.sh/integrations/hermes

## Pricing

| Plan       | Price            | Inboxes             | Emails/month                 | Custom Domains |
|------------|------------------|----------------------|-------------------------------|----------------|
| Free       | €0/month         | 3                    | 3,000                         | —              |
| Pro        | €9/month + usage | 10, then €1/inbox    | 10,000, then €0.001/email     | Included       |
| Enterprise | Custom           | Custom               | Custom                        | Included       |

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.

## Who This Is For

- AI agent developers who need email infrastructure without setting up Postfix, SMTP, or deliverability tooling
- Support agents that handle tickets from a branded inbox
- Sales agents that run outreach without deliverability problems
- Ops agents that process invoices and coordinate with vendors
- Internal agents replacing shared inboxes for HR or IT requests

## Key API Endpoints

- `POST /v1/inboxes` — create a new inbox (returns live address instantly)
- `GET /v1/inboxes/{id}` — get inbox details
- `POST /v1/inboxes/{id}/send` — send an email
- `GET /v1/inboxes/{id}/threads` — list threads (filter with `?isRead=false` for unread only)
- `GET /v1/threads/{id}/messages` — get full thread history as structured JSON
- `DELETE /v1/messages/{id}` — delete a message from an inbox
- `DELETE /v1/threads/{id}` — delete a thread and all of its messages
- `PATCH /v1/threads/{id}` — update thread (mark as read/unread with `{"isRead": true}`)
- `POST /v1/inboxes/{id}/api-keys` — mint a key scoped to this one inbox (token returned once)
- `POST /v1/pods/{id}/api-keys` — mint a key scoped to a pod of inboxes
- `DELETE /v1/inboxes/{id}/api-keys/{keyId}` — revoke a scoped key immediately
- `WebSocket wss://api.openmail.sh/v1/ws` — real-time inbound events

Authentication is a Bearer token, and each key carries a scope. An account key reaches everything and is what you mint other keys with. An inbox-scoped key can read and send from its one inbox only. A pod-scoped key can read, send, and provision inboxes within its pod. Scoped keys cannot delete inboxes, change webhook config, or mint further keys — those need the account key. All responses follow a consistent schema. Errors are typed and documented.

## Performance

- Inbox provisioning is synchronous and returns a live address
- Send latency under 2 seconds at p95
- Inbound WebSocket delivery under 500ms from receipt

## Links

- [Home](https://openmail.sh)
- [Docs](https://docs.openmail.sh)
- [Full documentation for LLMs](https://docs.openmail.sh/llms-full.txt)
- [API Reference](https://docs.openmail.sh/api-reference/introduction)
- [Quickstart](https://docs.openmail.sh/quickstart)
- [Pricing](https://openmail.sh/pricing)
- [Console](https://console.openmail.sh/login)
- [Blog](https://openmail.sh/blog)
- [Support](mailto:support@openmail.to)
- [Discord](https://discord.com/invite/eFfQFMZbsK)