openagentemail

# openagent.email

**Self-hosted email for AI agents. The open-source alternative to AgentMail.**

**[openagent.email](https://openagent.email)** · website: [openagentemail/website](https://github.com/openagentemail/website)

![Web dashboard: a message with its extracted verification code](docs/images/message-detail.png)

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
[![npm](https://img.shields.io/npm/v/@openagentemail/mcp.svg)](https://www.npmjs.com/package/@openagentemail/mcp)
[![release](https://github.com/openagentemail/openagentemail/actions/workflows/release.yml/badge.svg)](https://github.com/openagentemail/openagentemail/actions/workflows/release.yml)
[![Glama](https://glama.ai/mcp/servers/openagentemail/openagentemail/badges/score.svg)](https://glama.ai/mcp/servers/openagentemail/openagentemail)
[![Smithery](https://smithery.ai/badge/tizerluo/openagentemail)](https://smithery.ai/servers/tizerluo/openagentemail)
[![GitHub stars](https://img.shields.io/github/stars/openagentemail/openagentemail.svg?style=social)](https://github.com/openagentemail/openagentemail)

One `docker compose up` on your own VPS gives every agent you run unlimited real
mailboxes on your own domain — over REST and MCP — with OTP and verification-link
extraction built in. No per-inbox pricing, no third party ever seeing your mail.

## Quickstart

```bash
npx -y @openagentemail/setup
```

A guided wizard: it checks what you already have, helps you pick a VPS and a
domain if you're missing either, and connects your agent clients (Claude Code,
Cursor, Kimi Code…) once the server is up.

The manual path needs a VPS with outbound/inbound port 25 open and a domain
you control:

```bash
git clone https://github.com/openagentemail/openagentemail.git && cd openagentemail
cp .env.example .env   # set DOMAIN, API_KEYS, mailbox password, and NTFY_ADMIN_PASSWORD
docker compose up -d
sudo ./deploy/dns-records.sh   # prints the exact DNS records to create
```

Then verify everything end to end:

```bash
sudo ./deploy/doctor.sh
```

`doctor.sh` checks `.env` permissions; MX, A, SPF, DKIM, and DMARC; PTR;
outbound port 25; DNS blocklists; TLS certificates on 465 and 993; and the
server-side ntfy verification endpoint. It does not log in over IMAP/SMTP or
send a round-trip test. Docker Mailserver can create `docker-data/` as root,
so use `sudo` for these two scripts; an EACCES failure prints the same retry
instruction instead of pretending the DKIM key is missing.

If no SMTP relay is configured and outbound port 25 is blocked, API
`queued:true` only means the local mailserver accepted the message. It does
**not** mean the recipient received it: Postfix can retain the message in its
queue. Treat doctor's outbound-port-25 result as the delivery prerequisite, or
configure a relay before relying on direct delivery.

## Public TLS with Let's Encrypt (opt-in)

The default `docker compose up -d` path remains self-signed: it does not start
or pull Certbot and does not publish TCP 80. To use a publicly trusted mail
certificate, opt in only after `mail.$DOMAIN` has an A (and, if used, AAAA)
record pointing at this host and the firewall permits inbound TCP 80. HTTP-01
cannot create those DNS or firewall prerequisites for you.

In `.env`, set the following (use a reachable contact address outside this
mailserver when possible):

```dotenv
SSL_TYPE=letsencrypt
SSL_DOMAIN=mail.example.com       # exactly mail.$DOMAIN
LETSENCRYPT_EMAIL=admin@example.net  # optional, but recommended
```

First issue the certificate with the explicitly enabled sidecar; do not start
the mailserver in `letsencrypt` mode before this succeeds:

```bash
docker compose --profile letsencrypt-bootstrap up -d certbot-bootstrap
docker compose logs -f certbot-bootstrap
# Wait for “Successfully received certificate”, then confirm:
docker compose --profile letsencrypt-bootstrap run --rm --no-deps \
  --entrypoint ls certbot-bootstrap -l \
  /etc/letsencrypt/live/mail.example.com/fullchain.pem \
  /etc/letsencrypt/live/mail.example.com/privkey.pem
```

This temporary container reads the shared certificate volume, so confirmation
still works after the one-shot bootstrap has stopped.

If first issuance fails, Certbot stops instead of retrying the ACME request in
a tight loop. Correct the DNS/port-80/domain prerequisite, then explicitly run
the same `docker compose --profile letsencrypt-bootstrap up -d certbot-bootstrap`
command again.

The entire `/etc/letsencrypt` tree is a persistent named volume shared with
the mailserver read-only: Certbot's `live/` files are symlinks into `archive/`,
so mounting only `live/` is incorrect. Once the first certificate exists,
start the full opt-in stack and verify the public endpoints. Do not enable
`letsencrypt-bootstrap` and `letsencrypt` together: both publish host TCP 80.

```bash
docker compose --profile letsencrypt up -d
./deploy/doctor.sh
openssl s_client -connect mail.example.com:465 -servername mail.example.com </dev/null \
  2>/dev/null | openssl x509 -noout -issuer -subject -dates
openssl s_client -connect mail.example.com:993 -servername mail.example.com </dev/null \
  2>/dev/null | openssl x509 -noout -issuer -subject -dates
```

After bootstrap, the renewal sidecar runs `renew` every 12 hours and restarts
with Docker. docker-mailserver's change-detection service watches
`SSL_TYPE=letsencrypt` certificate updates and reloads Postfix and Dovecot, so
renewed certificates take effect on 465/993 without a manual container restart.
Keep the `letsencrypt` profile enabled for normal operation. If it is omitted,
the sidecars and TCP 80 are absent and the original self-signed path is unchanged.

Create an identity and hand your agent its scoped token (shown once):

```bash
curl -X POST http://localhost:3100/v1/identities \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"signup-bot","scopes":["read:messages"]}'
# → 201 {"address":"fox-k7d2@example.com","name":"signup-bot","token":"oa_…","scopes":["read:messages"]}
```

The API binds to `127.0.0.1` by default — reach it from other hosts over an
SSH tunnel or a TLS proxy: [docs/security.md](https://openagent.email/docs/guides/security/).

Paths are exact: call `/v1/notify`, not `/v1/notify/` — a trailing slash
returns a plain 404 rather than the API error format.

## Using your own mail server

Already have a mail provider for your domain? Run the API by itself with
[`compose.api-only.yaml`](compose.api-only.yaml), connected to that provider's
catch-all mailbox. The [external mail server guide](https://openagent.email/docs/guides/external-mailserver/)
covers the required catch-all setup, Portainer deployment, SMTP sender limits,
and TLS certificate verification.

The standalone default project name is `openagentemail`. If the full
`compose.yaml` stack also runs on the same host, the API-only stack must not
share that default project: give it an explicitly different `-p` value or
`COMPOSE_PROJECT_NAME` so the two stacks cannot adopt each other's resources.

To run multiple API-only instances on one host, give every instance its own
environment file, unique Compose project, and host `API_PORT`. The API always
listens on port 3100 inside its container; `API_PORT` changes only the host-side
mapping. For example:

```bash
mkdir -p ../oae-api-only-env
cp .env.api-only.example ../oae-api-only-env/alpha.env
cp .env.api-only.example ../oae-api-only-env/beta.env
chmod 600 ../oae-api-only-env/*.env
# Set API_PORT=3100 in alpha.env and API_PORT=3101 in beta.env.
# Generate separate API_KEYS and TASK_SIGNING_SECRET values in each file.

docker compose -p oae-alpha --env-file ../oae-api-only-env/alpha.env -f compose.api-only.yaml up -d
docker compose -p oae-beta  --env-file ../oae-api-only-env/beta.env  -f compose.api-only.yaml up -d
```

You may set a unique `COMPOSE_PROJECT_NAME` for each command instead of using
`-p`. The project names make Compose generate distinct container names and
project-scoped named volumes (for example `oae-alpha_api-data` and
`oae-beta_api-data`). Do not reuse a project name or `API_PORT` between the two
instances. Each instance must have independently generated `API_KEYS` and
`TASK_SIGNING_SECRET` values; configure its IMAP and SMTP credentials for that
instance's intended mailbox/provider boundary as well. Keep these populated
environment files outside the repository, as in the example above.

## Read mail in a browser

Open [`http://localhost:3100/ui`](http://localhost:3100/ui) and paste an admin
or identity API token. The built-in dashboard lists the addresses the token
may access, shows Inbox / All Mail (IMAP) and Sent (API/MCP send audit
for 30 days; direct SMTP is not listed) with cursor paging, extracts
verification codes and links at the top of a message, offers Rendered
(isolated HTML iframe), Plain text, or Source views, and can mark messages
read or unread. Source is fetched on demand from a size-capped `no-store`
endpoint and never injected as HTML. Scheduled and Trash are omitted until
the backend can serve them.
Admin sessions can also create identities (with custom address prefixes),
rotate tokens, and delete identities directly from the overview table.

The browser exchanges the token once for an `HttpOnly` session cookie; manually
pasted tokens never enter the URL or browser storage. You can also bookmark
`https://myinstance:3100/ui?token=<admin-token>` for direct login. The server
automatically issues a single-use exchange code (TTL ≤ 10 min) via a 302 redirect
and sanitizes the URL with `Cache-Control: no-store` and `Referrer-Policy: no-referrer`,
followed by client `history.replaceState` cleanup. Tokens passed in URLs can still linger
in upstream reverse proxy access logs before redirection — see `docs/security.md` for
reverse-proxy scrubbing guidance.
Percent-encode the token if it contains URL-reserved characters like `+`, `&`, or `#`
(e.g. `a+b` → `a%2Bb`), as `+` decodes to a space a