OpenAgentEmail (OAE) is a self-hosted communication and task handoff layer for AI agents. Its core idea is: assign an email address to an agent, send tasks to it, and then read its progress and results in the same thread. The entire handoff process remains inspectable, while the actual work is still done by the agent's own runtime environment (harness).
Uses
- Collaboration between agents across terminals and devices: Agents on different terminals or devices need a shared way to communicate, making clear who requested the work, who received it, the current status, and what was returned. They should not have to share admin credentials or switch to the same execution environment in order to exchange work.
- As an agent mailbox: Supports regular email, OTP extraction and verification link extraction, as well as waiting for new email to arrive.
- As an inspectable task handoff layer: Combines regular email with structured, authenticated task threads.
Main capabilities
- Self-hosted mail service: Can run the bundled mail server under your own domain (such as mail.$DOMAIN), manage DKIM selectors and TLS on ports 465/993.
- Task threads, approvals, and webhooks: Expose operations via MCP (HTTP and local stdio wrapper) and REST. Supports optional task leases (recipient claim/renew/release), but does not guarantee exactly-once external side effects.
- Multi-interface access: REST, HTTP MCP, and stdio MCP wrappers can all perform these operations.
- Web dashboard: Provides a task board product interface (shown under "Human visibility") for viewing handoff status.
- Integrate with existing agents: Adhering to the "bring your own agent" philosophy, OAE does not run models; execution still takes place in the agent's own runtime.
How to use
- If you already have an instance: Ask the operator for the identity address and corresponding identity token, then connect the agent, with no need to deploy a mail server separately. You can first complete one task handoff, or send a test email to your own identity and confirm that it can be read.
- Deploy a new instance: Use the guided installation CLI, and choose the appropriate mail backend for the environment. The API binds to localhost by default unless an SSH tunnel or HTTPS reverse proxy is intentionally configured. Do not expose a bare HTTP API carrying tokens. After deployment, verify: for the bundled mail server setup, run deploy/doctor.sh to check DNS, port access, certificates, and pre-notification.conditions; the API-only option (using your own email provider) skips doctor.sh and instead confirms that /healthz returns healthy, IMAP/SMTP credentials work, and actually sends and reads an email.
- Connecting agents: local stdio MCP clients require Node.js 20+; remote HTTP MCP clients can connect directly to the instance's /mcp endpoint, configuring Bearer/OAuth in the way the client supports.
- Migrating an existing api-data volume: the API runtime image runs as the non-root bun user (uid/gid 1000), and existing root-owned volumes require a one-time chown migration; the order is to migrate the volume first, then roll out the new image.
- ntfy non-root upgrade: ntfy now runs as UID 1000 and listens on container port 2587; if it previously ran as root, chown its data before starting.
Use cases
- Multiple agents dispatching tasks and collecting results across different terminals or devices.
- Needing an inspectable task handoff layer, rather than just an email service replacement.
- Self-hosted deployments that want an autonomous, controllable data path and want to avoid a mandatory SaaS control plane.
- Agent scenarios that need email workflows such as OTP and verification link extraction and waiting for new mail.
Limitations and boundaries
- The core does not require Orca; the webhook-wake example in the repository currently targets Orca and is not a general-purpose replacement adapter.
- Recorded pending webhook deliveries are recoverable, but the monitor does not replay all mail that arrived while the API was stopped. Consumers should reconcile task/mail state on startup or reconnect.
- Read status is shared state: marking an email as read affects other mailbox consumers and is not an agent's private acknowledgment; merely reading does not mark an email as read.
- Task leases are off by default (TASK_LEASES_ENABLED defaults to false). When enabled, each mailbox can only have one API process. Expiry audit sending in production is still hard-disabled, and the related flags will not enable it.
- Software licensing per identity is free of charge, but mailbox capacity, provider policies, disk, memory, and configurable rate limits still apply (sending defaults to 20 per identity per hour). Ordinary mail is retained for 30 days by default; mail marked as a task is outside this cleanup scope.
- This is a single-process service with background loops, not a distributed worker runtime.
- Passwords and tokens must be protected; do not commit tokens in client configuration. Remote models/clients will receive data, so review the data path before exposing credentials or message contents.
- Framework examples and local fixtures do not constitute evidence of a production end-to-end run.
- The project direction is to more simply connect existing work environments and provide clearer recovery/operations guidance, without promising a general-purpose scheduler, shared workspace manager, global federation, or automatic code execution.
- Some specific deployment configurations, detailed pricing (if any), and terms of service are not yet described in the provided materials.
