IMAP runs in two steps: rules on message headers first (junk folder and INBOX), then the models on the full body of the rest (Pass 3, nomic + Gemma, is currently at rest with [mlx] enabled = false: the rules classify and everything else goes to 5-A revoir). Filing a mail out of 5-A revoir teaches MailTag its sender. The rules were learned from the legacy folders with scripts/taxonomy_setup.py and a local Streamlit review page; see the usage docs. Day-to-day use (folders, archiving, teaching MailTag, Gmail) is in the user guide.

Prerequisites

• Python 3.13+
• macOS with Apple Silicon (MLX requires Metal)

Installation

git clone https://github.com/fjacquet/mailtag.git
cd mailtag
uv sync -U --all-extras

Configuration

Configuration uses two sources:

• config.toml — main config (logging, imap, gmail, fast_parse, mlx, taxonomy, webhook)
• .env — secrets only (IMAP_USER, IMAP_PASSWORD, WEBHOOK_API_KEY)

Required .env variables

[email protected]
IMAP_PASSWORD=your-password
# Only for `serve`: WEBHOOK_API_KEY=your-key

MLX Models (config.toml)

[mlx]
enabled = true
embedding_model = "nomic-ai/nomic-embed-text-v1.5"    # nomic centroids
llm_model = "mlx-community/gemma-4-e4b-it-OptiQ-4bit" # Gemma second opinion

Gmail Setup

Gmail runs through the Gmail API (OAuth), not IMAP. Create an OAuth desktop client in Google Cloud Console, save it as secrets/credentials.json, and run run --provider gmail --validate once to open the browser and save secrets/token.json. See the configuration docs for details.

Usage

python src/main.py run --provider all              # Classify all providers
python src/main.py run --provider imap             # IMAP only
python src/main.py run --provider gmail             # Gmail (through the Gmail API) only
python src/main.py run --provider imap --validate  # Read-only (no moves)
python src/main.py serve                           # Webhook API server

Taxonomy setup and legacy folder migration (dry run unless --apply):

uv run python scripts/taxonomy_setup.py scan        # read-only pass over the legacy folders
uv run python scripts/taxonomy_setup.py crosscheck  # Gemma opinion per sender
uv run streamlit run scripts/taxonomy_review.py     # local review page
uv run python scripts/taxonomy_setup.py build       # rules and nomic centroids
uv run python scripts/taxonomy_setup.py migrate [--apply]  # move legacy folder mail into the categories
uv run python scripts/taxonomy_setup.py prune [--apply]    # delete the emptied legacy folders
uv run python scripts/taxonomy_setup.py reorganize [--apply]  # PARA folders, standard Promotions

Bulk review of 5-A revoir (own the decision per domain or per sender instead of mail by mail; dry run unless --apply):

uv run python scripts/taxonomy_setup.py review-scan --provider imap|gmail    # group, Gemma suggestion
uv run streamlit run scripts/taxonomy_review.py                              # stage 5: decide
uv run python scripts/taxonomy_setup.py refile-review --provider imap|gmail [--apply]  # move covered mail

Data and Database

• db/taxonomy/: validated, learned and domain rules (validated.json, senders.json, domains.json, validated_domains.json, folder_overrides.json, control.json)
• db/pending_archive*.json: category of each mail waiting in an action folder (one file per account)
• db/backups/: copies of both, taken at the start of each run (10 per file)
• data/taxonomy_centroids.npz: nomic centroids per category
• data/legacy_folders.json: frozen list of the legacy folders (migration, centroids)
• data/non_commercial_domains.yaml: domains that never get a domain rule

Docker

The Docker image runs the webhook API with rules only (no MLX): validated and learned senders and domain rules classify; everything else goes to 5-A revoir. Do not run serve in Docker (with db/ mounted) while a run works on the Mac: flock does not cross the Docker Desktop VM boundary.