openagentemail/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.
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
| Capability | What it gives you | Boundary |
| --- | --- | --- |
| **Agent identities** | Addresses on your managed domain(s), with individual identity tokens | Logical identities over a catch-all mailbox, not unlimited physical mailboxes |
| **Email and messaging** | Send/read mail, extract OTP codes and links, wait for a match | SMTP acceptance is not recipient delivery |
| **Task handoffs** | Named recipient, state history, structured results and direct parent-child links | No automatic worker selection or descendant scheduling |
| **Approvals** | Record a specified reviewer's approval or rejection | The decision does not execute the action |
| **Notifications and webhooks** | Human alerts and outbound event delivery to your integration | Webhooks are opt-in; delivery is not proof an agent consumed the task |
| **Human visibility** | Inspect mail, tasks, identities and notifications in the dashboard | Access depends on the session's identity and permissions |
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:
The setup CLI guides deployment and client configuration.
Choose the mail backend that fits your environment:
| Deployment | Use it when | Prerequisites |
| --- | --- | --- |
| Bundled mailserver | You want to operate your own mail stack | Docker Compose, a domain, DNS configuration and reachable inbound SMTP; outbound port 25 or a relay |
| API-only | A provider already hosts your domain | Docker Compose, a catch-all mailbox, IMAP/SMTP credentials and permission to send as the identity addresses |
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