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}"}