lucasmaffei/mailgrant

mailgrant

The self-hosted email gateway for AI agents. Each agent gets its own token, its own mailboxes and its own permissions. The mailbox passwords stay with you.

English · Português · Español · Français · 简体中文

Without a gateway, every agent that touches email (Claude, Codex, OpenClaw, your own scripts) holds a copy of every mailbox password. With mailgrant you register each mailbox once, and each agent gets a token that opens only the mailboxes and actions you chose. Agents talk MCP or REST, and every call is checked and logged.

Install: 1. Get it · 2. Configure · 3. Run · 4. Connect an agent Use: Day to day · The web app · Documentation

1. Get it

You need a machine with Docker, and the IMAP/SMTP details of at least one mailbox (an app password is best).

git clone https://github.com/lucasmaffei/mailgrant && cd mailgrant
cp config.example.yaml config.yaml

2. Configure

The config holds two lists: mailboxes (what the gateway can reach) and agents (who may use which mailbox, and for what).

Create a token for your first agent:

docker compose run --rm mailgrant mailgrant token --name support-bot

It prints the token, which you give to the agent, and its hash, which goes in the config. The token is shown only once and isn’t stored anywhere.

Replace the contents of config.yaml with your mailbox and that agent:

mailboxes:
  - name: contact
    imap: {host: mail.example.com, username: [email protected], password: "${CONTACT_PASSWORD}"}
    smtp: {host: mail.example.com, username: [email protected], password: "${CONTACT_PASSWORD}",
           from_address: "Example ", save_copy_to: Sent}

agents:
  - name: support-bot
    token_sha256: "9f86d08…"          # the hash printed above
    mailboxes: [contact]              # names, addresses, or "*" for all
    scopes: [read, mark, send]        # read · mark · delete · send

Put the password in a .env file next to it, so the config holds no secret:

echo 'CONTACT_PASSWORD=the-mailbox-password' > .env

Check the config. It prints who may touch what, or exactly what is wrong:

docker compose run --rm mailgrant mailgrant check

ok: 1 mailbox(es), 1 agent(s)
  support-bot          [mark, read, send]  contact
web app: off (no `web:` section)

Ports, TLS, aliases, the trash folder and every other option: docs/configuration.md.

3. Run

docker compose up -d
curl -s http://127.0.0.1:8000/health      # {"ok":true,"version":"…"}

The port only listens on 127.0.0.1. For agents on other machines, put it behind HTTPS with a reverse proxy (Caddy, Traefik, nginx) or a platform like Coolify (step by step).

4. Connect an agent

The agent needs the address https:///mcp and its token:

# Claude Code
claude mcp add --transport http mailgrant https://mail-mcp.example.com/mcp \
  --header "Authorization: Bearer $MAILGRANT_TOKEN"

# Codex
codex mcp add mailgrant --url https://mail-mcp.example.com/mcp \
  --bearer-token-env-var MAILGRANT_TOKEN

Then ask it “Which mailboxes can you use through mailgrant?”. It should answer with exactly what you granted.

Cursor, Claude Desktop, OpenClaw, plain REST, and a prompt that lets the agent set itself up: docs/connect-agents.md.

Day to day

Edit config.yaml or .env, then apply the change with docker compose up -d --force-recreate (a plain restart doesn’t reread .env). Agents keep their tokens and need no change.

Would you rather click? With the web app and manage: true, you add mailboxes and agents in the app, and changes apply without a restart.

The web app (optional)

A webmail for you, built into the same server. Every mailbox is in one inbox, HTML mail shows safely, and you can reply and attach files. You get push notifications on your phone, a timeline of what each agent read and sent, and passkey sign-in. It comes in English, Português, Español, Français and 简体中文.

It is off by default. To turn it on, add this to config.yaml and apply it the same way:

web:
  origin: https://mail.example.com      # the HTTPS address you open it at
  user: {name: you, mailboxes: ["*"], scopes: [read, mark, delete, send]}

Then run docker compose exec mailgrant mailgrant invite and open the link it prints on your phone to create your passkey.

Installing it on a phone, notifications, managing agents from the app: docs/web-app.md.

Documentation

Contributions are welcome, including new languages for the web app: see CONTRIBUTING.md. Found a vulnerability? Follow SECURITY.md.

Credits and license

mailgrant is a fork of docker-mailbox by Ciprian Mandache (psyb0t), which provides the IMAP/SMTP layer, the unified inbox, reader mode and the MCP transport. mailgrant adds per-agent grants, auditing, safe deletion, threaded sending and the web app.

MIT, see LICENSE. The Docker image bundles third-party components under their own licenses; see THIRD_PARTY.md.