MailFathom user guide

This is the documentation for people who install, configure, operate, and use MailFathom. It is a guided path rather than a second copy of the reference material: each step links into the operations and feature pages where the full contract lives, so nothing here goes stale on its own. Contributor and agent documentation is separate, under the repository root and docs/ generally.

What MailFathom is

MailFathom is a self-hosted service that synchronizes mail from your IMAP accounts into a local PostgreSQL copy, indexes it for search, and serves it to AI agents as tools over the Model Context Protocol. An agent connected to it can list, read, and search your mail, it can mark, star, and label one message at a time through set_mail_flags, and it can send a message through send_email — or answer one it already holds through reply_to_email and forward_email. It can also write a message into your own Drafts folder and leave it for you, through save_draft, update_draft, and delete_draft, which send nothing at all; send_draft is what sends one. Each of those acts is offered only to a credential granted its own name — mailfathom.mail.flags.write, mailfathom.mail.drafts.write, and mailfathom.mail.send — and none comes with being able to read; the two answering tools and a draft that answers stored mail need the reading name too, because an answer is derived from the message it answers. Drafting and sending are separate names deliberately: a deployment can let an agent prepare mail for you to send and let it send none. get_outgoing_email and cancel_outgoing_email say what became of a message it sent and stop one that has not left yet, and both sit behind the sending name rather than one of their own. It cannot delete or move mail. What it can write besides is MailFathom's own contact book — the people you or your deployment wrote down — which six tools read and maintain, one of them by erasing a record for good.

Two properties hold everywhere and are worth knowing before anything is installed:

Reading is local. A read answers from the local copy and never contacts a mail server, so it is fast, works while the server is down, and changes nothing remotely. Every result states how fresh the local copy is.
Retrieval is read-only. Fetching mail never sets the remote \Seen flag, so mail MailFathom has copied still shows as unread in your mail client until you read it there. Three things write to your mailbox: a mail rule whose action moves, copies, deletes, or marks a message read, the spam actions that file junk and mark it read, and the set_mail_flags tool, beside the three draft tools that put a message into your own Drafts folder. The first two are off until you turn them on; the last two need grants that reading mail does not carry. A fourth path leaves your deployment altogether rather than writing to your mailbox: send_email, reply_to_email, forward_email, and send_draft, behind a grant of its own, and they are the acts here nothing can take back.

The state of the release

0.7.0 is the current release, and the first one in which MailFathom sends mail as well as reading it. The container image is published to both registries, the Helm chart is published, and the schema file you apply and the mfctl binaries are attached to the GitHub release — so an installation starts from a versioned artifact rather than from a checkout. Where a page describes something that arrives later than 0.7.0, it says so and names the release, rather than describing it as though you could already download it.

The path

Choose and perform an installation — which deployment shape fits, what each needs, and where its full guide is.
Getting started — from an installed instance to a synchronized mailbox and a first successful tool call, including secrets, the schema step, health verification, and connecting an MCP client.
Configuring a mailbox at your provider — the address, port, and credential kind each popular mail service publishes, and what each one does differently once synchronization runs.
Connecting the chat client you already use — where the dialog is in each popular client, which address kind it needs, and which of them cannot present an API key at all.
Using the tools — what list_emails, search_emails, get_email_content, set_mail_flags, send_email, the four draft tools, ask_mail, and the six contact tools do, what they deliberately bound, and how to read a failure.
Administering your deployment — the mfctl command: what it is for, signing in to a deployment from your own machine, and what it cannot do yet.
Configuration reference — the map to the four pages that list every user-settable option with its type, default, constraints, and whether changing it needs a restart.

Handing this guide to your own agent

If you are working with an AI assistant beside you, give it the documentation rather than a search over it. The published site carries three artifacts written for exactly that, under whichever version you are running:

llms.txt at the version's root maps every published page with one line saying what it answers, and links each page's Markdown source. An agent loads it in full and then fetches only the page that owns your question.
llms-operator.txt is this guide's operator path — choosing an installation, getting started, configuring a mailbox at your provider, and administering the deployment — in one file, for when the question is the path rather than a page of it.
llms-mailbox-user.txt is the other path in one file: connecting the chat client you already use, and what each tool returns and bounds.

The version-agnostic address https://krzysztof318.github.io/MailFathom/llms.txt is the map of the release the site opens on; the same file sits under each version's own directory. The documentation site records how they are produced and what they deliberately leave out.

Once it is running

Question	Page
Is it healthy, and how do I probe it?	Health endpoints
Which port does it serve `/mcp` on, and is it HTTP or HTTPS?	Where each surface is served
How do I reach a running deployment from my own machine?	Administering your deployment, the administrative endpoint
How do I provision and rotate credentials?	Secret provisioning, secret rotation
How do I protect the MCP endpoint — keys, OAuth, TLS, client certificates, rate limits?	The MCP endpoint
How do I add MailFathom to the chat client I use?	Connecting the chat client you already use
How do I upgrade, back up, restore, or remove it?	Docker Compose, Podman Quadlet, Kubernetes
It refuses to start, saying a migration is pending. What now?	Applying the database schema
Where does configuration come from, and what reloads without a restart?	Configuration sources, configuration reference
What does it record about itself, and where do the records go?	Telemetry, host startup telemetry
What exactly does synchronization store and reconcile?	IMAP synchronization
What address and credential does my mail service want?	Configuring a mailbox at your provider