HermodMail
View on GitHub

Open source · Self-hosted · MCP native

A mailbox where humans and AI agents work together.

HermodMail is a real IMAP/SMTP webmail with a native MCP server. Your agents read, draft and act inside your mailbox through scoped tokens — while you keep control of every folder, every permission and every send.

View on GitHub Explore the features
The actual HermodMail interface — IMAP folders, live search, reading pane and AI actions when a provider is configured.

The actual HermodMail interface — IMAP folders, live search, reading pane and AI actions when a provider is configured.

The problem

Email wasn't built for agents.

Connecting an AI agent to a mailbox usually means sharing your credentials, wiring brittle scripts together and hoping nothing goes wrong. HermodMail starts from a different principle:

One mailbox. One shared engine. Human and agent access with controlled permissions.

Scoped tokens, not shared passwords

Create an API token, pick its scopes, hand it to your agent. Tokens start with hmt_ and only a SHA-256 hash is ever stored — the full value is shown once at creation.

Checked on every call

Scopes are re-read from the database on each tool call. Tighten or revoke a token and it applies to sessions that are already open.

Real drafts, not chat transcripts

Agents save genuine IMAP drafts — flagged \Draft, visible in the Drafts folder — instead of pasting text through a separate chat window.

How it works

The agent did the work. The human kept the decision.

A typical collaboration: you brief your agent, it prepares real drafts in your mailbox, and you review and send when you are ready.

  1. You brief your agent

    "Prepare follow-up drafts for the accounts I met last week." Any MCP client works — the agent connects with its token.

  2. The agent works over MCP

    With mail:write and ai:use, it searches your mailbox, composes and saves real IMAP drafts. Nothing is sent.

  3. The drafts are already there

    Open the Drafts folder in HermodMail. Each draft is a real message you can read, edit and complete — with the recipient picker, attachments and your signature habits.

  4. You decide what leaves

    Review, tweak, send. A token without mail:send cannot send a single message — the sending decision stays with you.

A draft saved by an agent through MCP, waiting in the Drafts folder.
A draft saved by an agent through MCP, waiting in the Drafts folder.

The agent did the work. The human kept the decision.

A real webmail, first

Everything you expect from a mail client — with or without AI.

HermodMail is a complete webmail you can use every day. AI is an optional layer, never a requirement.

IMAP / SMTP

Standard mail protocols — works with existing accounts.

Folders

Create, rename and manage mailboxes with system-folder guardrails.

Full-text search

Fast SQLite full-text search across subject, people and body.

Contacts

Automatically harvested from your mail, with recipient autocomplete.

Drafts

Real IMAP drafts, saved and editable from any client.

Attachments

Attach files when composing, download them when reading.

fr / en / es

A fully translated interface in three languages.

Dark theme

Auto, light or dark — it follows your system preference.

Multi-user

Per-user mailboxes and isolation, managed by an admin.

Markdown export

Export any message to clean Markdown.

Folders, list and reading pane — with AI summary and AI draft reply one click away.

Folders, list and reading pane — with AI summary and AI draft reply one click away.

Native MCP

Built in, not bolted on.

The web interface and MCP agents do not go through different code paths: both speak to the same mail engine, which enforces the same ownership and permission rules for a browser session and a Bearer token alike.

17 tools, exposed over HTTP

Point any MCP-compatible client at /mcp with an Authorization: Bearer header. Here is the full surface, grouped by the scope it requires:

mail:read
  • list_accounts
  • list_folders
  • sync_folder
  • list_messages
  • search_messages
  • get_message
  • export_markdown
mail:write
  • create_draft
  • mark_message
  • move_message
mail:send
  • send_message
mail:delete
  • delete_message
folder:write
  • create_folder
  • rename_folder
folder:delete
  • delete_folder
ai:use
  • summarize_message
  • draft_reply

get_message never returns raw HTML — agents receive sanitized content. delete_folder requires an explicit confirm flag for non-empty folders.

Permissions

Permissions that mean something.

Every token carries a precise set of scopes. The engine checks them on each call — and a few rules hold no matter what.

  • mail:read

    List, sync, read, search messages, export Markdown, download attachments.

  • mail:write

    Save drafts, change flags, move messages between folders.

  • mail:send

    Send messages over SMTP. Grant this one deliberately.

  • mail:delete

    Delete messages, with Trash-aware behaviour.

  • folder:write

    Create and rename folders.

  • folder:delete

    Delete folders — guarded for system folders and non-empty mailboxes.

  • ai:use

    Use the built-in AI features: summarize, classify, draft reply, translate.

The token lifecycle

Shown once, hashed forever

Only a SHA-256 hash of the token is stored. If it leaks, revoke it — nothing to decrypt.

Editable live

Change a token's scopes at any time; the new set applies on the next call, even in open sessions.

Revocable in one click

Revoke instantly from Settings → API tokens. The token stops working immediately.

No account enrollment

API tokens can never add or remove mail accounts. A leaked read-only agent token cannot enroll new mailboxes.

Creating a scoped token in Settings → API tokens (MCP).
Creating a scoped token in Settings → API tokens (MCP).

Honest by design: an agent holding mail:send can send on its own. HermodMail does not force human approval on every message — it gives you the tools to decide exactly who may send.

Bring your own model

No mandatory AI provider. No forced cloud dependency.

The webmail is fully functional with AI turned off — that is the default. When you want built-in assistance, plug in the provider you already trust:

None — the default

Summarize, classify, draft-reply and translate simply stay hidden. A complete webmail, nothing more.

OpenAI-compatible APIs

Any endpoint speaking the chat/completions format, with your API key stored encrypted on your server.

Ollama, locally

Run models on your own machine — nothing leaves your infrastructure.

Agents bring their own LLM

MCP clients use their own model; HermodMail's provider setting is only for its built-in assistant.

Email content is untrusted by definition: text fed to the model is fenced as data and the system prompt forbids treating it as instructions.

For developers

Running your own is the point.

A single Node server with a SQLite database, or a container. No external services required.

git clone https://github.com/cyril-belin/HermodMail.git
cd HermodMail
cp .env.example .env
# Set HERMODMAIL_SECRET (openssl rand -base64 48) in .env
docker compose up -d
# or: podman-compose up -d

HermodMail listens on http://localhost:8667 and stores everything in the hermodmail-data volume.

Before going public

Set a strong HERMODMAIL_SECRET, serve the app behind TLS (the README includes a ready-to-copy Caddy reverse-proxy configuration) and read the security notes before exposing anything to the internet.

Full documentation in the README

Open source, by design

Your mail server should be inspectable.

HermodMail is free software under AGPL-3.0-or-later. Read the engine, audit the crypto, run the test suite — and change what does not suit you.

AGPL-3.0-or-later

The full license text ships with the repository.

Readable architecture

A core engine, thin HTTP and MCP adapters, a Vue 3 front-end. Nothing hidden.

An extensive test suite

Unit and property-based tests cover the engine, auth, crypto and MCP surface.

Read the source Report an issue Read the license

HermodMail is a young project (v0.1.0) under active development — tested with real mailboxes, built to grow in the open.

The same interface, comfortable at night.

The agent did the work. The human kept the decision.

One mailbox, one engine, controlled permissions — and a home for both the people and the machines that work there.

Star HermodMail on GitHub