Lenovmail

Self-hosted mail infrastructure for many mailboxes at once — IMAP and Microsoft Graph behind a single database, a browser client, a REST API, and an MCP server that lets AI agents read and send mail under limits you can audit.

Product page: satuapps.com/lenovmail

What it does

Lenovmail keeps a normalized copy of your mailboxes in PostgreSQL. IMAP accounts sync incrementally (UIDVALIDITY, CONDSTORE when the server offers it, IDLE for the inbox); Microsoft 365 accounts sync through Graph delta links. Messages are parsed once, stored with their MIME blob on disk, threaded by References/In-Reply-To, and indexed for full-text search. Everything the GUI can do is also reachable over REST, and a scoped subset is exposed to AI agents over MCP.

It is built for the case where mail is an input to automation: several accounts, one API, and an agent that must not be able to quietly send a thousand emails.

Related MCP server: Mailbuttons MCP Server

Why it is different

Quickstart

git clone https://github.com/satuapps/lenovmail.git
cd lenovmail
cp .env.example .env
python -c "import os,base64;print(base64.b64encode(os.urandom(32)).decode())"   # -> LENOVMAIL_SECRET_KEY

docker compose up -d --build
docker compose exec api uv run lenovmail bootstrap-admin --email admin@example.com

Open http://localhost:8080, sign in with the printed password, and add an account. API documentation is served at http://localhost:8080/api/docs.

No mailbox to test with? Start the bundled fake server and seed it:

docker compose -f docker-compose.test.yml up -d
uv run python scripts/seed_greenmail.py

Full walkthrough: docs/quickstart.md.

Architecture

flowchart LR
    Browser[Browser GUI] -->|session cookie| API
    Agent[AI agent] -->|Bearer token| API

    subgraph Lenovmail
        API[FastAPI: REST + MCP + static GUI]
        Worker[arq worker]
    end

    subgraph Stores
        PG[(PostgreSQL)]
        RD[(Redis)]
    end

    API --> PG
    API <-->|jobs, events| RD
    Worker --> PG
    Worker <--> RD
    Worker -->|IMAP / SMTP| Mailserver[(Mail providers)]
    Worker -->|Microsoft Graph| Graph[(Microsoft 365)]

The API process serves the REST API, the built React client, and the MCP endpoint. The worker process runs sync cycles, body backfill, IMAP IDLE watchers, outbox delivery, and the janitor. Redis carries the job queue and the SSE fan-out; PostgreSQL holds everything else.

Details: docs/architecture.md.

Agents and MCP

{
  "mcpServers": {
    "lenovmail": {
      "type": "http",
      "url": "http://localhost:8080/api/mcp",
      "headers": { "Authorization": "Bearer lnv_..." }
    }
  }
}

Tools: list_accounts, list_folders, search_messages, get_message, get_thread, set_message_flags, move_message, delete_message, send_message, list_outbox, get_attachment.

A token carries scopes (mail.read, mail.write, mail.send, mail.delete, mail.manage), an optional account allowlist, an hourly send budget, and an approval flag. With approval on, send_message stops at pending_approval and waits for a human in the Outbox view. Every call lands in agent_audit.

Sends queued by an agent wait in the Outbox until a human approves them:

Running the agent on another machine takes one allowlist entry and a token: docs/agents.md.

Maintenance built in

Credentials die quietly: an app password gets revoked, a tenant pulls an OAuth grant, an account is closed. The janitor (janitor_sweep, hourly) re-checks every account the sync path marked auth_error:

stateDiagram-v2
    active --> auth_error: provider rejects login
    auth_error --> active: credentials work again
    auth_error --> disabled: grace period expired (default)
    auth_error --> deleted: grace period expired, action=delete

Transient failures never count — a timeout or a 5xx leaves the account exactly where it was. Expired and revoked agent tokens are deleted after their retention window, and agent_audit is trimmed to its own. Run it by hand with uv run lenovmail janitor.

Details: docs/operations.md.

CLI

Documentation

Development

uv sync
docker compose up -d db redis
uv run alembic upgrade head
uv run uvicorn lenovmail.api.app:app --reload --port 8080
uv run arq lenovmail.workers.main.WorkerSettings     # second terminal
npm --prefix web run dev                             # GUI with a proxy to :8080

Checks that CI runs: uv run ruff check src tests, uv run mypy, uv run pytest -q, npm --prefix web run typecheck, npm --prefix web run build. Database-backed tests skip themselves when PostgreSQL is not reachable; the IMAP end-to-end suite needs docker compose -f docker-compose.test.yml up -d.

See CONTRIBUTING.md.

Security

Stored IMAP/SMTP passwords and Microsoft token caches are encrypted with AES-256-GCM using a per-field AAD derived from the account id; rotating LENOVMAIL_SECRET_KEY makes existing credentials undecryptable. Browser sessions live in Redis so they can be revoked; agent tokens are stored as sha256 hashes and displayed once. Incoming HTML is sanitized server-side (nh3) and again in the client (DOMPurify). LENOVMAIL_ALLOWED_HOSTS gates the Host header for the API and the MCP mount alike.

Reporting a vulnerability: SECURITY.md.

License

MIT — see LICENSE.

Built and maintained by satuapps.