Openagentemail MCP

OpenAgentEmail

Open communication and task handoffs for AI agents. Self-hosted email, task threads, approvals, and webhooks over MCP and REST —for the agents you already use. Bring your own agents. Keep control of the work.

Get started · Try a task handoff · Documentation · Architecture · 简体中文

See it work

Give an agent an address. Send it a task. Read its progress and result in the same thread. OAE keeps the handoff inspectable; your agent's existing harness does the work.

Watch the handoff recording (MP4) — about 47 seconds. The video is linked, not embedded inline. Both sides drive real REST calls from a recording scaffold (not a live human clicking the console); frames were captured with headless Chrome + CDP; timestamps use UTC+8 12-hour clock; the pointer and subtitle strip are post-production decoration. Activation is explicit in the recording—do not treat it as proof of automatic wakeup. Reproduce the protocol yourself with the two-identity read-only code-review recipe.

sequenceDiagram

participant A as Requester agent participant O as OpenAgentEmail participant B as Recipient agent A->>O: Create a task for B B->>O: Read the task when activated B->>O: Report working Note over B: Review in its own environment B->>O: Report completed with a result A->>O: Read the result and history

See the existing email and OTP interface

This repository image demonstrates the email capability, not an Agent orchestration console. Task-board product images appear under Human visibility below.

Why OpenAgentEmail?

Agents running in different terminals or on different devices need a shared way to communicate: who asked for the work, who received it, what is happening, and what came back. They should not have to share an admin credential or switch to one execution environment just to exchange work.

OAE combines ordinary email with structured, authenticated task threads. Use it as an agent mailbox, an inspectable task handoff layer, or both. Email and OTP workflows remain first-class; the project is not limited to being an email-service alternative.

What you can do today

These are real product screenshots from a controlled capture (anonymized). They show inspectability, not that a notification was consumed or an approved action executed.

REST, HTTP MCP and the stdio MCP wrapper expose these operations. Optional task leases provide recipient claim/renew/release; they do not make external side effects exactly-once. See the tool reference.

Quickstart

Already have an instance?

Ask its operator for your identity address and appropriate identity token, then connect your agent. You do not need to deploy another mailserver. Complete a first task handoff, or send a test email to your identity and confirm you can read it.

Deploy a new instance

Start the guided setup:

npx -y @openagentemail/setup

The setup CLI guides deployment and client configuration. Choose the mail backend that fits your environment:

Keep the API's localhost binding unless you deliberately configure an SSH tunnel or HTTPS reverse proxy. Mail certificates and HTTPS for the API are separate concerns. Do not publish a bare HTTP API carrying tokens.

After deployment, verify the path you actually chose:

Bundled mailserver. This stack owns mail.$DOMAIN, the mail DKIM selector, and TLS on ports 465/993. Run the doctor against that layout:

sudo ./deploy/doctor.sh

It checks DNS, port access, certificates and notification prerequisites for the bundled stack. It still does not log in over IMAP/SMTP or send a round-trip email.

API-only (your own mail provider). Skip deploy/doctor.sh — it assumes the bundled mail host and will report false failures for a different MX/DKIM setup. Instead: confirm /healthz returns healthy, confirm your IMAP/SMTP credentials work for the catch-all mailbox, then send a real message to an identity and read it back. Only then try the task recipe. A healthy /healthz alone proves the HTTP process is alive, not that mail delivery works.

Existing api-data volume: one-time non-root migration (#93)

The API runtime image runs as the bun user (uid/gid 1000), not root. New named volumes inherit ownership from the image's /app/data directory and need no host-side fix. Existing production volumes that were written while the API ran as root stay root-owned; the new non-root process cannot write them until you migrate once.

Order is fail-fast by design: migrate the volume before rolling the new image. Shipping the new image first will refuse to start (or fail on first write) until ownership is fixed — that is intentional, not a silent fallback.

1. Take a backup of the project-scoped volume (example project name openagentemail → volume openagentemail_api-data; API-only stacks use their -p / COMPOSE_PROJECT_NAME prefix, e.g. oae-alpha_api-data).
2. Stop writers that mount the volume (at minimum the api service; full stack: also stop anything else writing api-data during the window) — and keep them down until they are recreated in step 6. Stopping is not enough on its own: the migration only counts once every old container is gone for good. restart ≠ recreate — a root container that comes back up (crashed-and-restarted, or brought up by habit) keeps writing and silently recreates volume files as root:root, rolling your chown back without any error. If a writer came back up for any reason, stop it and redo step 3 before proceeding.
3. One-shot chown to the runtime user:

# Replace <project>_api-data with your real volume name (docker volume ls).

docker run --rm -v _api-data:/data alpine \ sh -c 'chown -R 1000:1000 /data'

1. Spot-check ownership before bringing services back:

docker run --rm -v <project>_api-data:/data alpine \

sh -c 'ls -ln /data | head'

Expect uid/gid columns to show 1000 / 1000 for migrated paths.

1. Read back the migration on the volume — must pass:

docker run --rm -v <project>_api-data:/data alpine \

sh -c 'find /data ! -user 1000 | head'

Expect no output: zero files still owned by a non-1000 user.

1. Pull/build the new images, then verify the API image declares the runtime user before starting anything. Build the whole project (docker compose build with no service name) — or at minimum api and ntfy-provision together: they share one Dockerfile, and the --force-recreate below re-runs the one-shot ntfy-provision container too, so it must come from the same non-root image batch. A stale root-based provision image re-running here would write the volume as root and roll your migration back — the same failure this runbook exists to prevent.

docker inspect <new-api-image> --format '{{.Config.User}}'

Expect bun (uid 1000) — never empty/root.

Only then start everything (docker compose up -d --force-recreate or your usual deploy path).

Do not reverse this order. Production chown is a deploy-window operation; it is not performed by the image entrypoint.

Deploy-window recreate gotchas (measured 2026-09-21)

1. `--force-recreate ` follows the dependency chain. Measured on the reference host: recreating api also recreated mailserver along api→mailserver→provision (and ntfy pulls ntfy-provision) — healthy, ~11s, no loss, but unintended. To recreate only the named services, add --no-deps; full-project builds keep the plain form.
2. Measure override attribution — do not assume it. Before editing or removing any override, run docker compose config against three configurations: base alone, base + each override, and compare the resolved output field by field. On the reference host (2026-09-21) this distinguished two siblings: docker-compose.override.yml was a zero-contribution no-op (its patches had long been absorbed into the base file) and was removed with a timestamped backup, while compose.override.yaml is live and must be kept (adds the loopback binding and widens allowed ports). A "Found multiple override files" warning at recreate time is the cue to run this check. Scope note: override auto-merging happens only on default-file invocations — deployments selecting files explicitly (e.g. API-only docker compose -f compose.api-only.yaml ...) auto-merge no override at all and must pass every override explicitly.

ntfy non-root upgrade (#278)

ntfy now runs as UID 1000 and listens on container port 2587. If an existing deploy previously ran ntfy as root, chown its d