# MailFathom

> 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 read-only tools over the Model Context Protocol. Reading is
> local, and synchronization never marks anything read on the mail server.

This is the whole of the published documentation for one version of MailFathom, one line per page. Every link below
is a page's Markdown source, served beside the rendered page at the same address with a `.md` extension, so fetching
one returns text rather than a template. The site holds one directory per documented version and this file describes
the one it was fetched from.

The pages do not repeat each other. Each states one contract and the line beside its link says which, so the way to
an answer is to fetch the page that owns it rather than to read the set — which together is roughly 1.8 MB. Where the
question is a whole path rather than a page of it, a bundle below carries that path in one fetch.

## Bundles

- [The operator path](llms-operator.txt): Choosing an installation, getting started, configuring a mailbox at your provider, and administering the deployment.
- [The mailbox user path](llms-mailbox-user.txt): Connecting the chat client you already use, and what each tool returns and bounds.

## User guide

The guided path from choosing an installation to a first tool call, for whoever installs, operates, and uses MailFathom.

- [What MailFathom is](users/README.md): What MailFathom is, and the two properties that hold everywhere — reading is local, and synchronization never marks mail read.
- [Choosing an installation](users/installation.md): The deployment shapes a release publishes, what each one assumes and is good for, and which guide carries its commands.
- [Getting started](users/getting-started.md): From an installed instance to a synchronized mailbox and a first successful tool call, secrets and the schema step included.
- [Configuring a mailbox at your provider](users/mailbox-providers.md): 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](users/mcp-clients.md): Where the connection 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](users/usage.md): What list_emails, search_emails, get_email_content, and ask_mail return, what they deliberately bound, and how to read a failure.
- [Administering your deployment](users/administering.md): The mfctl command — what it is for, signing in to a running deployment from your own machine, and what it cannot do yet.
- [Configuration reference](operations/configuration-reference.md): Every user-settable option in one place, with its type, default, constraint, and whether changing it needs a restart.

## Operations

What a running deployment is configured with, served on, secured by, and reports about itself.

### Configuration

- [Configuration reference](operations/configuration-reference.md): Every user-settable option in one place, with its type, default, constraint, and whether changing it needs a restart.
- [Configuration sources](operations/configuration-sources.md): Where settings are read from and in which order, what a deployment may provision outside the content root, and why configuration is read-only.
- [Provider endpoints](operations/provider-endpoints.md): The addresses and API shapes each supported AI provider publishes, and what each entry here rests on.
- [Secret provisioning](operations/secret-provisioning.md): How a secret-bearing setting names material rather than carrying it, the schemes that resolve a reference, and what a leaked configuration file exposes.
- [Secret rotation](operations/secret-rotation.md): Which credentials are rotated without restarting, what MailFathom does when one changes, and how to verify the rotation took.

### Deployment

- [The container image](operations/container-image.md): What the one image definition produces, what runs inside it, how it is tagged and published, and how to verify a pulled image.
- [Docker Compose](operations/deployment-compose.md): Running MailFathom and PostgreSQL on one machine with Compose, and upgrading, backing up, restoring, and removing that installation.
- [Podman Quadlet](operations/deployment-quadlet.md): Running MailFathom and PostgreSQL as rootless systemd units under Podman, taking credentials the way a native service takes them.
- [Kubernetes](operations/deployment-kubernetes.md): Installing the Helm chart, the objects it creates, the Secret it deliberately leaves to whoever operates the cluster, and the values that matter.
- [Applying the database schema](operations/database-schema.md): Applying a migration as an explicit operator action, why startup never applies one, and what an instance does when the schema is behind.
- [Changing the embedding model](operations/embedding-profiles.md): Activating a new embedding profile without invalidating the vectors already stored, and what the change costs while it runs.

### Endpoints

- [The MCP endpoint](operations/mcp-endpoint.md): Enabling the endpoint an agent reaches, what a client has to present, which origins and certificates it accepts, and how much traffic it takes.
- [MCP client OAuth](operations/mcp-client-oauth.md): Connecting a chat client through your own identity provider instead of an API key, provider by provider.
- [The administrative endpoint](operations/admin-endpoint.md): How mfctl reaches a running deployment, and what that deployment has to have enabled before it will answer.
- [Health endpoints](operations/health-endpoints.md): What each of the three probes consults, which port they answer on, and how a deployment turns them off or puts TLS in front of them.

### Mail servers and transport security

- [Mailbox OAuth](operations/mailbox-oauth.md): Registering an application at a mail provider so a mailbox is synchronized with OAuth rather than a password.
- [The platform TLS policy](operations/platform-tls-policy.md): Why the system OpenSSL decides which mail servers are reachable at all, and what a refusal MailFathom never saw looks like.

### What it reports about itself

- [Telemetry](operations/telemetry.md): What the host emits as logs, metrics, and traces, the one switch that lets any of it leave the process, and why deployments ship with it off.
- [Host startup telemetry](operations/host-startup-telemetry.md): How process lifetime is recorded before and after the logging pipeline exists, and what a failure during startup leaves behind.

### Developing and releasing

- [Local development](operations/local-development.md): The SDK, the database, the package sources and lock files, and the commands a change is built, tested, and verified with.
- [The agent workflow](operations/agent-workflow.md): The scripts and skills a repository change passes through, what each one asserts, and how a review runs on a pull request.
- [Issue tracking and the roadmap board](operations/issue-tracking.md): How work is tracked — the issue body, the one type label, the board's fields and views, and how an arrival from outside is triaged.
- [The release procedure](operations/release-procedure.md): Where the version number lives, how a build acquires it, and the sequence that turns a commit into a published release.
- [The documentation site](operations/documentation-site.md): How this site is generated, which versions it carries, how a link in it is written, and what it publishes for an AI agent to read.

## Features

What the product does, from the mail arriving to the tool call answering, and what each behavior deliberately bounds.

- [The scope of the first release](features/initial-scope.md): What the first release implements, slice by slice, and what is deliberately still pending.
- [IMAP synchronization](features/imap-synchronization.md): How a mailbox is reconciled read-only — what starts a pass, how folder identity survives a rename, and what a remote deletion does locally.
- [Mailbox queries](features/mailbox-queries.md): What a listing filters on, how a page is bounded and continued, and how it reports the freshness of the local copy it answers from.
- [Email search](features/email-search.md): What a search matches, how results are ranked and bounded, and what each hit carries back beside the summary.
- [Email content](features/email-content.md): What the content of a named message returns — normalized headers, body, attachments — and the limits every part of it is bounded by.
- [Message chunks](features/message-chunks.md): Why a message is cut into overlapping passages, how a chunk is identified, and what is stored beside it.
- [Embedding generation](features/embedding-generation.md): What a deployment declares to turn a passage into a vector, what one call may spend, and how a failing call is classified.
- [Automatic embedding](features/automatic-embedding.md): What decides that a passage is embedded, when it happens, and what an operator sees when it falls behind.
- [Embedding backfill](features/embedding-backfill.md): How mail stored before a profile existed is embedded afterwards, and what a backfill reports while it runs.
- [Chat generation](features/chat-generation.md): What a deployment declares to make a chat call, what one call is allowed to spend, and how an operator sees whether the provider is working.
- [Mail answering](features/mail-answering.md): How a question about the mailbox is answered from mail the model looks up while answering, and how much of it leaves the process.
- [Sensitive-content scanning](features/sensitive-content-scanning.md): How a credential that arrived in a mailbox is kept out of a provider's context window, a retrieval snippet, and a log line.
- [Spam classification](features/spam-classification.md): How mail written to deceive a reader is recognized from what the receiving server already decided, and what that changes downstream.
- [Mail rules](features/mail-rules.md): How a rule selects mail and what a match may change, written in the configuration a deployment already carries.
- [MCP tools](features/mcp-tools.md): The conventions every tool follows, the contract of each tool that exists, and what a client reads when a call fails.

## Architecture

The boundaries the code is built on, and the shape of what it stores.

- [Solution structure](architecture/solution-structure.md): The projects, which way their dependencies point, and what belongs inside each boundary.
- [The arrival pipeline](architecture/arrival-pipeline.md): The order a newly arrived message passes through — classification, rules, redaction, chunking, embedding — drawn once, with what each stage waits for and what each classification outcome permits.
- [The stored email schema](architecture/stored-email-schema.md): The columns, constraints, and indexes the mail timeline is read from, and why raw MIME and search text live in tables of their own.
- [Outbound resilience](architecture/outbound-resilience.md): The one model for deciding whether repeating a failed call to a dependency is recovery or damage.

## API reference

- [API reference](api/index.md): Every public type and member, generated from the XML documentation comments in MailFathom's own source.

## Changelog

- [Changelog](CHANGELOG.md): What each release shipped, one section per released version.

---

Copyright © 2026 Krzysztof Kasprowicz
Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
Project repository: https://github.com/Krzysztof318/MailFathom