MAIL is an open protocol — and a Python implementation — for email-like communication between humans and AI agents. Every participant (a human user, an AI agent, or a delivery daemon) is an addressable user-agent with its own inbox, and they exchange messages much like people exchange email: compose a draft, send it to one or more addresses, and let a daemon deliver it.
MAIL deliberately covers the communication layer and little else — not an agent runtime, not tool execution. If you already have agents, MAIL gives them a shared, standard way to talk. See What is MAIL?.
- Email-like model — addresses, inboxes, outboxes, drafts, trash, and mailing lists, all defined by an open specification.
- HTTP-native — a FastAPI server with an authoritative OpenAPI contract; any client that speaks the contract works.
- Separation of concerns — the server owns state, daemons deliver messages, clients are just authenticated user-agents.
- Pluggable storage — an in-memory backend for development and a transactional SQLite backend for durability.
- Batteries included — a CLI client (
mail), an admin CLI (mail-admin), a delivery daemon, and webhook delivery for push notifications.
MAIL ships as five lockstep packages on PyPI under mail-swarms-*. Install the
components you need:
pip install mail-swarms-server # the FastAPI server + backend-init
pip install mail-swarms-client # the `mail` and `mail-admin` CLIs
pip install mail-swarms-daemon # the delivery daemonTo work from a source checkout, use uv:
git clone https://github.com/charonlabs/mail.git
cd mail
uv syncRequires Python 3.12+.
Bring up a local deployment and send your first message. (Prefix commands with
uv run when working from a source checkout.)
# 1. Initialize a local memory backend (creates a swarm + starter user-agents)
uv run backend-init --type memory --host localhost
# 2. Configure and start the server
export MAIL_HOST=localhost
export MAIL_JWT_SECRET_KEY=$(openssl rand -hex 32)
export MAIL_JWT_ALGORITHM=HS256
export MAIL_JWT_EXPIRE_MINUTES=30
export MAIL_REFRESH_TOKEN_EXPIRE_DAYS=30
uv run mail-server --backend memory # http://127.0.0.1:8865
# 3. In another terminal, start the delivery daemon (with daemon credentials)
uv run mail-daemon
# 4. In a third terminal, log in and send a message
export MAIL_SERVER=http://127.0.0.1:8865
uv run mail login
uv run mail compose "Hello" "My first MAIL message"
uv run mail send <draft_id> supervisor@default@localhostThe full walkthrough — including where the generated credentials live — is in Run MAIL Locally.
| Package | Directory | Provides |
|---|---|---|
mail-swarms-protocol |
src/mail/protocol |
Shared protocol types, constants, and validators |
mail-swarms-server |
src/mail/server |
FastAPI server, storage backends, backend-init |
mail-swarms-client |
src/mail/client |
mail and mail-admin CLIs |
mail-swarms-daemon |
src/mail/daemon |
The delivery daemon (mail-daemon) |
Full docs live in docs/, organized by the
Divio system:
- Tutorials — Run MAIL Locally · Send Your First Message · Build a Minimal HTTP Client · Build a Webhook Receiver
- How-to guides — running the server, daemon, authentication, sending messages, swarms, mailing lists, webhooks, and more.
- Reference — HTTP API · Data Models · Configuration · Storage Backends · CLIs
- Explanations — Architecture · Addressing · Delivery · Security
The protocol itself is specified in spec/SPEC.md, with the
authoritative HTTP contract in spec/openapi.yaml.
mail/
├── docs/ # documentation (tutorials / howtos / references / explanations)
├── spec/ # SPEC.md + generated openapi.yaml
├── src/mail/
│ ├── protocol/ # mail-swarms-protocol
│ ├── server/ # mail-swarms-server
│ ├── client/ # mail-swarms-client
│ ├── daemon/ # mail-swarms-daemon
│ └── legacy/ # archived MAIL v1 runtime (reference only)
├── tests/ # active v2 test suite (contract / e2e / integration / unit)
├── scripts/ # artifact generation + maintenance
└── pyproject.toml # uv workspace + meta-package
See Repository Layout for the full map.
uv sync # install the workspace
uv run pytest # run the active v2 test suite
uv run mail --help # explore the client CLIMore: Run the Test Suite · Regenerate API Artifacts.
The MAIL v1 runtime is archived under src/mail/legacy/ for reference and is not
part of the v2 packages — see MAIL v1 Legacy Runtime.
Contributions are welcome. Please read CONTRIBUTING.md; commits must be signed off under the Developer Certificate of Origin.
Reference implementation code is licensed under the Apache License 2.0. The protocol specification and patent grant are covered by SPEC-LICENSE and SPEC-PATENT-LICENSE. "MAIL" and related marks are subject to the trademark policy.