User manual

Your mail, on your terms.

localmail mirrors every IMAP account you own into a local PostgreSQL database and content-addressable file tree — searchable, scriptable, and yours. This manual walks you from a blank machine to a running archive, step by step.

How the manual is organised

The three "Getting started" pages are sequential — work through them once, in order, on a fresh machine. The "Using localmail" pages are reference material; jump to whichever interface you prefer.

Getting started

Step 1

Set up PostgreSQL

Install Postgres, create the localmail database and role. Works on macOS, Linux, and Docker.

Step 2

Install localmail

Install uv, then install the localmail CLI as a global tool and apply the database schema.

Step 3

Add email accounts

Provider-by-provider recipes: Gmail (OAuth2), Microsoft 365 / Exchange, Fastmail, Proton Mail, iCloud, generic IMAP.

Using localmail

Reference

Run the daemon

Keep your archive up to date in real time. systemd / launchd unit templates, log inspection, restart strategy.

Reference

Use the CLI

One-shot syncs, search, status, failure recovery, attachment text extraction, language detection.

Reference

Admin web UI

Manage accounts, users, the daemon, and imports from a browser — the database-canonical control panel inside serve.

Reference

Import existing mail

Bulk-load old mbox files and Maildir trees into your archive, idempotently.

Reference

AI agents (MCP)

Let an AI assistant search and read the archive over MCP, and sharpen queries with the local-LLM --smart rewriter.

Reference

Run the desktop app

Browse, search, and read mail from a native window. Connect the app to a local localmail serve instance.

What you'll have at the end

A PostgreSQL database called localmail holding every message header, body, and label from every account you connected.
A directory tree of attachments, content-addressable by SHA-256, so identical bytes are stored exactly once across all your accounts.
A background daemon that keeps the archive current using IMAP IDLE on the INBOX and periodic polling on other folders.
A hybrid lexical-plus-vector search index across messages and attachment text — runnable from the CLI, Python, or the desktop app.

Estimated time

~30 minutes for the three setup steps if you already have Postgres and uv installed; ~60 minutes from a completely blank machine. The initial mail sync runs in the background after that and depends on how large your mailboxes are.

Next 1. Set up PostgreSQL