MailFathom 0.8.0

The eighth release, and the one in which MailFathom stops being one person's mailbox described in a configuration file.
The people a deployment serves, their mail accounts, the credentials they sign in with, and what each of them may do
are now records in PostgreSQL, written through mfctl and the administrative endpoint while the deployment runs. One
deployment serves several people, shares a mailbox between them, groups them into organizations, and runs as more than
one replica.

It is also the first release that carries MailFathom's own client, and the client is an alpha. It is in the image,
off until you serve it, and published as a desktop application beside the release. It is there to be tried, it is
incomplete, and nothing about it is promised to the next release. The MCP tools remain the supported way to reach your
mail.

This release does not upgrade in place — plan it as a new installation over a backup. The schema artifact applies
to a 0.7.0 database, and applying it discards the stored mail and everything recorded against a mail account;
synchronization fetches the mail again. Nothing imports the users, mailboxes, or credentials your configuration
declared: each is recorded again. The Changed entries below say what, and
Getting started is the path a deployment
follows afterwards. Do not leave a 0.7.0 build running against the migrated schema: there is no rolling upgrade
across this release, and the way back is the backup.

The terms change too. Every artifact from this release on is published under AGPL-3.0-only where earlier
releases were Apache-2.0, and from the fathomise organization rather than from a personal account.

The twenty-one MCP tools keep their names and arguments. What moves on that surface is an account identifier, two
result shapes, and three permission names, each named below.

Added

• Several users, and mail accounts as records of their own. A user and a mail account are each a record, and an
  account is assigned to the users it serves, so one shared mailbox is one copy of its mail read by several people.
  Users can be grouped into organizations, whose members sign in as SHORTNAME/username. mfctl user, mfctl account, mfctl credential, and mfctl organization administer all of it, and a change is served without a
  restart (#2000,
  #1992,
  #2013).
• Roles at a scope. What a user may do comes from the roles assigned to them — over the deployment, one
  organization, or their own mail — and three are built in: Administrator, Organization administrator, and Mail user. An administrator is a user like any other, and a credential can be confined to the endpoints it may be
  presented on and the networks it may come from (#2328,
  #2333,
  #2341).
• Signing in with a user name and a password, over HTTP Basic, on any endpoint whose Authentication list names
  password (#1328).
• Settings you change while the deployment runs. A deployment's own settings are persisted in PostgreSQL and read
  as one more configuration source, below environment variables and above your files; mfctl config reads and edits
  them, and every replica follows a change. A settings policy held at the deployment or at an organization can force a
  value, or withhold one, for every user and mail account beneath it
  (#1280,
  #1311,
  #2361).
• Configuration in YAML beside JSON, for provisioned files and for a mail account's declaration
  (#2031).
• More than one replica. Work that must not run twice — an account's synchronization, a backfill, a delivery
  pass — is divided between replicas through PostgreSQL alone. The Helm chart renders a rolling update and a
  PodDisruptionBudget, and an optional RESP backplane, Valkey in every deployment asset, carries live updates to a
  client from whichever replica produced them (#1925,
  #1923).
• Stored mail content in an S3-compatible bucket, chosen with ContentStorage:Backend and off by default, with a
  bounded, verified move of what the database already holds (#1219,
  #1266).
• Attachments are searched and cited. search_emails and ask_mail find what was sent as a file — the text of a
  PDF, a document, a spreadsheet, or a presentation, and a description of a picture — and name the file and the page,
  slide, or sheet. Both results gain fields and neither loses one. Reading attachments and describing pictures are
  bounded per period and off until configured (#1714,
  #1735).
• Several chat models. Chat:Models declares them under aliases, each AI capability can name its own, and a
  model can name a fallback (#1934,
  #2047).
• Holding the only copy of a mailbox. An account can be set to have MailFathom hold its mail rather than mirror
  it, emptying the source once each message is durably stored, and custody can be returned to the server afterwards. A
  mailbox exports as a Maildir archive (#2026,
  #2160,
  #2024).
• MailFathom's own client, as an alpha. A web client travels in the image and is served from /app/ once
  ClientEndpoint:Application:Enabled is on; the same client is attached to the release as a .deb, an .rpm, and a
  Windows installer. It reads, searches, composes, and files mail, and carries first versions of an assistant, a
  calendar, tasks, and an address book. It talks to a deployment over the HTTP API under /api/client, which is off
  until ClientEndpoint:Enabled and is expected to change between releases while the client is unfinished
  (#1436,
  #1444).

Changed

• Breaking (configuration schema, database schema): nothing a 0.7.0 configuration declared about mailboxes is
  read, and the mail stored for them is discarded. MailSynchronization:Accounts is gone and a configuration still
  carrying it does not start. Applying the schema artifact removes stored mail, drafts, queued and recurring sends,
  rule and spam-classification history, the audit trails, and the OAuth refresh tokens of every mailbox. Your
  action: back up, apply the schema, remove the section, then record each person with mfctl user add, each mailbox
  with mfctl account add — a declaration now states EmailAddress and no AccountId — assign the role they should
  hold, and let synchronization refill the mail. Re-consent every OAuth mailbox, and state spam classification and
  sensitive-content scanning on each account's own record, where they now live
  (#1861,
  #2000,
  #2011).
• Breaking (configuration schema): credentials are provisioned, not configured. ApiKey, PublicKey, and
  Permissions no longer exist under McpEndpoint:Authentication or AdminEndpoint:Authentication, and a section
  carrying one fails startup naming the command that replaces it. An entry names only the methods the endpoint
  accepts. Your action: create each credential with mfctl credential create and move every client onto what it
  reports (#1339).
• Breaking (deployment contract): the administrative endpoint is signed in to as a user, and it is where a
  deployment is set up. The first start records a user admin holding the Administrator role, and the
  environment-only MAILFATHOM_ADMIN_PASSWORD sets its password once. Compose and Quadlet set it to admin; the Helm
  chart sets nothing and reads a Secret you name. Your action: mfctl login --mode password, change that password
  at once — every start warns until you do — and set your own value before the first start wherever the endpoint is
  reachable from another machine (#2333).
• Breaking (MCP tool contract): three permission names, and what a credential's list means.
  mailfathom.mail.ask is mailfathom.assistant.use, mailfathom.mail.contacts.read and .write are
  mailfathom.contacts.read and .write, and asking about mail needs mailfathom.mail.read beside the first. A
  permission written on a credential now narrows what its user's roles grant rather than granting anything, and a user
  with no role holds nothing. Your action: assign a role to every user, and write the new names wherever a script
  or an authorization server states one (#2374,
  #2332).
• Breaking (MCP tool contract): an account identifier is a generated UUID rather than the name you chose, and it
  resolves only among the accounts assigned to the caller. A client that stored one reads list_accounts again.
  set_mail_flags gains a required applied in its result
  (#2000,
  #2006).
• Breaking (configuration schema): the Chat section is an array. Every key describing an endpoint moves under
  Chat:Models:<n>, and Chat:Model becomes Chat:MainModel:Alias. A start on the old shape is refused naming the
  key. MaxOutputTokens now defaults to 4096 where it defaulted to 1024; write 1024 to keep the previous cost
  (#1934,
  #2185).
• Breaking (configuration schema): deleting defaults to deleting. An account that states neither
  AuthoredDeleteEmailDisposition nor RemotelyDeletedEmailDisposition now erases its local copy when a message is
  deleted through MailFathom and when its server loses one. Write RetainLocalCopy and RetainTombstone to keep what
  0.7.0 did (#2028).
• Breaking (configuration schema): request limits are per user. Every endpoint gains
  MaxConcurrentRequestsPerUser, default 8, which must be below MaxConcurrentRequests; a deployment that set the
  latter to 8 or less fails startup until it sets both. The defaults rise to 48 concurrent requests and a bucket of
  120, and every credential of one user shares one allowance
  (#1985).
• Breaking (deployment contract): where artifacts are pulled from. The image is ghcr.io/fathomise/mailfathom
  and docker.io/fathomise/mailfathom, and the chart is oci://ghcr.io/fathomise/charts/mailfathom; earlier releases
  stay where they were published. The server's name in the MCP Registry is io.github.fathomise/mailfathom
  (#2389,
  #2395).
• Breaking (deployment contract): attachment download links are served beneath /mcp/attachments/. A reverse
  proxy that forwarded only the exact /mcp path forwards the prefix, and a rule for /attachments/ can go
  (#1987).
• Breaking (deployment contract): the license is AGPL-3.0-only. No key, column, or tool moves. Section 13 asks
  something only of somebody who modifies MailFathom and lets other people reach the modified version over a network:
  that they offer those people its source (#1471).
• Telemetry values are spelled one way. The mailbox-mutation folder tag is mailfathom.mail.folder, its outcomes
  are succeeded, failed, and cancelled, and the delivery, draft, and filing outcomes use underscores where they
  used hyphens. Every metric, log record, and span also names the replica that produced it. Rewrite any dashboard or
  alert matching the old spellings (#1046,
  #1994).
• A search with no embedding model matches any of the query's words rather than requiring all of them, ranked by
  how closely they sit together. Quote a phrase to require it
  (#2215).

Removed

• Breaking (deployment contract): the collected contacts a deployment cannot attribute. A contact book is now
  either a user's own or a mail account's. What somebody wrote down is kept; an address MailFathom collected is kept
  only where the mailbox it arrived on is unambiguous, and is collected again from mail that arrives. Export them with
  mfctl contact export on 0.7.0 first if you want them
  (#2022).

Security

• A send and a draft are screened before they leave. Where sensitive-content scanning is on, an outgoing
  message, a draft, and the text of their attachments are scanned, and the act is cancelled when a scanner finds
  something (#1116,
  #1699).
• send_draft is bound by the recipient policy and the send ceilings, which it previously bypassed
  (#1045).
• The libraries that parse mail and sanitize its HTML are on the versions carrying their security fixes
  (#2425,
  #2426).

The full changelog at this tag carries the releases before this one and the surfaces each of them broke.

The published image

Both registries carry the same manifest list under the same digest, so the one to pull from is whichever your environment already reaches.

docker pull ghcr.io/fathomise/mailfathom:0.8.0
docker pull ghcr.io/fathomise/mailfathom@sha256:4e52cb70c7294c2995ed974a822805079955192206cb98b42c7dd825142edd68

docker pull docker.io/fathomise/mailfathom:0.8.0
docker pull docker.io/fathomise/mailfathom@sha256:4e52cb70c7294c2995ed974a822805079955192206cb98b42c7dd825142edd68

The Helm chart

helm install mailfathom oci://ghcr.io/fathomise/charts/mailfathom --version 0.8.0

The chart is published to GHCR alone, because Docker Hub has no repository path to hold it beside the image. Its appVersion is this release, and it deploys the digest above.

The database schema

Apply mailfathom-schema-0.8.0.sql before rolling this version out, and take a backup first. MailFathom applies no schema change while starting and refuses to serve against a schema it does not recognize, so the order is: back up, apply the script, then deploy the image.

Artifact	mailfathom-schema-0.8.0.sql
SHA-256	f3ecffef7b92baf16a876aecb57e5e2e0b339eea3deb1332a54febd9f2b89acb
Migrations	20260801190024_Initial 20260803190706_AddMailboxRefreshTokens 20260803191836_AddSynchronizationCheckpointModSeq 20260806132916_AddEmailChunks 20260807125156_AddEmbeddingProfilesAndEmailEmbeddings 20260807130550_AddMailboxMutations 20260807143735_AddMailboxMutationSourceRemoval 20260807154642_AddMailboxMutationObservations 20260807222509_AddAuthoredDeleteLocalDisposition 20260808113315_AddMailboxMutationAuditEntries 20260808113641_AddEmbeddingProfileLifecycleUniqueIndex 20260808145001_AddStoredEmailAwaitingContentIndex 20260808150849_AddEmbeddingSpendPeriodsAndChunkedTextTruncation 20260808184600_AddMailAnsweringAuditEntries 20260812073051_AddMailRuleEvaluationState 20260812131829_AddMailRuleExecutionHistory 20260812143605_AddEmailSpamClassifications 20260812170539_RenameRuleExecutionDestinationColumn 20260812205202_AddSpamClassificationRuns 20260812215230_AddJobs 20260813083226_AddSensitiveContentDerivationStamp 20260813085031_RestrictJobClaimIndexToClaimableStates 20260813100915_AddStoredEmailStoredAt 20260813102205_AddJobFailureRecord 20260813134459_AddJobDeadLetterIndex 20260813161625_AddMailRuleScheduleTrigger 20260815165050_AddStoredEmailRemoteKeywords 20260815201928_AddStoredEmailSenderAuthentication 20260816151132_AddStoredEmailSenderTrust 20260816172328_ReplaceSenderDomainAlignmentWithAuthorAuthentication 20260816185554_AddStoredEmailDisplayedAuthorDomain 20260816192300_AddMailRederivationPositions 20260816195613_AddContacts 20260816203831_AddOutgoingEmailRecord 20260816214322_AddEmailThreads 20260816232632_AddEmailThreadConcurrencyToken 20260817080518_AddEmailThreadSurvivorForeignKey 20260817190310_AddMailboxMutationFlagAndKeywordParameters 20260817210931_AddStoredEmailMachineAuthorship 20260818094931_AddJobEnqueuedTraceContext 20260818125456_AddOutgoingEmailLease 20260818150010_AddMailRederivationRuns 20260818220053_AddOutgoingRecipientContact 20260818220409_AddStoredEmailSenderAuthenticationSource 20260819154129_AddOutgoingEmailFilings 20260819171623_AddOutgoingEmailPeriodUsageIndex 20260819184706_AddScheduledAndRecurringSends 20260819215942_AddOutgoingEmailPrincipal 20260820082840_AddMailDrafts 20260820202943_AddMailDraftRecipientProvenance 20260823192901_AddUserAccounts 20260824111136_AddContentStorageBackendAndObjectLocator 20260824112627_AddJobTurn 20260824124618_BoundEmbeddingSpendAndStoredContentPerUser 20260824142528_IndexObjectBackedContentAndRequireItsPayloadEmpty 20260824152343_AddContactUser 20260824190011_IndexContentObjectLocators 20260824213453_AddContentMoveRun 20260825123351_RetainDatabaseCopyUntilReleased 20260825140051_AddRootSettings 20260825212451_CarryUserBesideMailAccountReferences 20260826184627_KeyMailAccountByUserAndIdentifier 20260827072558_AddUserLabelAndDocumentMarker 20260827192213_AddUserPasswordCredentials 20260828091727_ResolveUserFacingCredentialsToUserRows 20260828193403_AddStoredSecrets 20260902175313_AddDraftSubjectAndStagedAttachments 20260902180901_AddClientPreferences 20260902224524_AddUserPortrait 20260903223138_AddNotifications 20260906105043_AddAttachmentTextAndAttachmentChunks 20260906184247_AddEmailEnrichment 20260907165757_BoundAndReportAttachmentDerivationSpend 20260908175402_AddNotificationCause 20260908231220_AddEmailThreadStates 20260909155944_WidenFilingJoinIndexesToEveryConfirmedCopy 20260909185210_IndexStandingFilingsByFilingAndAppend 20260910152639_AddWorkLeases 20260910155700_AddSpentClientAssertions 20260910165411_AddDeploymentWideCeilingRows 20260910215154_AddMailboxMutationWithdrawalHold 20260911080610_DropUserDocumentMarker 20260911125554_AddClientSignalTickets 20260911175359_AddWorkLeaseReplica 20260911204203_AddClientSessions 20260913102318_MakeStoredEmailOccurrenceOptional 20260913110610_AddUserEndpointSwitches 20260913111639_MoveUserPortraitsIntoStoredFiles 20260913144350_AddLocalMailFolders 20260913153012_AddOrganizationsScopingPasswordLogins 20260913204921_FileHeldAccountDraftsAndSentCopiesLocally 20260913225224_MoveMailAccountsIntoRecordsOfTheirOwn 20260914073056_HoldSpamAndSensitiveContentOnTheMailAccount 20260914124419_KeyTheMailGraphByTheAccountIdentifier 20260915085932_SplitContactBooksByHolder 20260915155630_AddMailboxExports 20260915191538_AddRequestedCustodyAndSourceDrain 20260916090823_FlagOnlyAuthoredDeletes 20260920124705_AddTasks 20260920134832_AddCalendarEvents 20260920164406_AddCalendarEventReminders 20260920195958_JournalDiscoveryRuns 20260920213742_AddTaskReminders 20260921130420_StoreDiscoveryRunEventPayloadAsWritten 20260921185125_AddAgentConversations 20260922083643_AddMailboxMutationLocalChange 20260922122202_AddMailboxRestoreAppends 20260922140333_RecordAgentConversationTechnicalHistory 20260922154107_IndexAgentConversationsForHistorySearch 20260922181537_ArchiveAnAgentConversation 20261008212533_GroupMailAccountsIntoOrganizations 20261008234837_AddRolesGroupsAndRoleAssignments 20261009005545_HoldMailAccountSettingsInColumns 20261009171250_HoldMailGrantsOnUsers 20261009184940_AdmitUsersOnTheAdministrativeEndpoint 20261010180553_RewriteAdministratorRoleAsAPattern 20261010222745_AddSettingsPolicies 20261011100203_StateEndpointSwitchesHeldOffOnUserRecords 20261011151120_StampEndpointSwitchesOnUserRecords 20261011174705_SplitUserFacingPermissionsByDomain

The script is idempotent, so an installation already carrying some of those migrations takes only what it is missing. Applying the database schema states the privileges it needs, the locks it takes, and what each startup failure means.

The administration command

Download the binary for the machine you administer from, not for the machine the service runs on: mfctl reaches a deployment over HTTP and runs on Linux and Windows alike. Verify it against mfctl-0.8.0.sha256, make it executable, and run mfctl login --endpoint https://host:port. Administering a deployment states what the service has to have enabled before it will answer.

On Linux there is a shorter path, which downloads the binary for the machine it runs on, checks it against the checksum file above, and installs it into ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/fathomise/MailFathom/v0.8.0/scripts/install-mfctl.sh \
  | bash -s -- --version 0.8.0

The script is fetched at the tag of this release, so what it installs is this version rather than whatever is newest. Read it before you run it: it is one file and it is short.

None of the binaries carries a code signature, so Windows warns about an unknown publisher and mfctl-0.8.0.sha256 is what verifies a download — on every platform.

The client

There are two ways to have it, and you choose rather than the deployment. The web head travels inside the image above and is served by the deployment itself, from the same address its client surface answers on — one setting turns it on, and the client endpoint is the page. The desktop head is attached to this release, as a .deb and an .rpm for Linux and an NSIS -setup.exe for Windows, each named after this version. Install one and run MailFathom like any other application; it renders in the WebView your own system supplies and talks to the same client surface over the network.

Verify a download against mailfathom-client-0.8.0.sha256, which is the only thing that verifies it: no artifact here is code-signed either, so Windows warns about an unknown publisher. The desktop client states what each installer does and does not do, and why no AppImage is published.