Agent Mail Gateway

What Agent Mail Gateway does

The Agent Mail Gateway MCP server gives an AI agent controlled access to a mailbox hosted on an existing mail server. Each configured mailbox has its own API key, and the gateway keeps the IMAP and SMTP credentials out of the agent. It can expose mail as Markdown, convert outgoing Markdown to HTML, and handle calendar invitations alongside ordinary email.

The service is intended for self-hosting, typically as one Docker container. Mail remains on the configured mail server, while the gateway stores its operational state in SQLite. Agents can connect through MCP over Streamable HTTP, use the included stdio bridge, or call the REST API.

How the Agent Mail Gateway MCP server works

An API key maps to exactly one configured mailbox. Receive and send allow lists determine which addresses the agent can see and contact; patterns such as *@domain are supported. Messages from disallowed senders are hidden from the agent and are moved to Trash or retained according to configuration.

Before sending an email or calendar invitation, the gateway can run fixed checks, optional LLM review, and administrator-defined policy checks. Built-in checks cover cases such as empty content, missing attachments referenced by the message, unresolved placeholders, duplicate messages, missing subjects, and invitations in the past. Reviews can block a request or issue a warning, depending on the mailbox settings.

Setup and configuration

Run the service with Docker Compose, then create a config.yaml entry for each mailbox. The entry contains the mailbox address, API key, IMAP and SMTP connection details, login credentials, and receive/send allow lists. Secrets can be supplied through .env; the example uses AGENT_API_KEY and AGENT_MAIL_PASSWORD.

The health endpoint runs at /health, and the REST API provides OpenAPI documentation at /docs. A mailbox can be checked with an authenticated request to /v1/mailbox. A dedicated mailbox per agent is recommended because messages outside the receive allow list may be moved to Trash.

Tools and capabilities

The Agent Mail Gateway MCP server exposes tools to:

• Inspect mailbox identity, current time, limits, allow lists, and review settings.
• List received messages with unread, text, sender, subject, and date filters.
• Read messages as Markdown and inspect attachment and invitation information.
• Download attachments, mark messages read or unread, and move permitted messages to Trash.
• Send new messages, reply or reply-all, and forward messages with attachments.
• Create, update, or cancel calendar invitations; list events and attendee responses.
• Accept, decline, or tentatively accept received invitations.

It also supports signed new-mail webhooks and records sends, rejections, and deletions in an audit log. Calendar invitations are designed to update in Outlook, Gmail, and Apple Calendar.

Limitations and notes

The gateway does not replace the underlying IMAP/SMTP server; each mailbox still requires working mail-server configuration and credentials. Access is limited by the configured allow lists and review behavior. Optional LLM review uses an OpenAI-compatible endpoint, such as a local Ollama service, and policies can be scoped to particular recipients. The material does not specify a hosted deployment option, so operation requires self-hosting.