fltr-mail

Organizes emails in catch-all domain inboxes by sorting them into subfolders based on the recipient address.

Why this exists

Catch-all domains are great for privacy - you can give every service a unique address like amazon@yourdomain.com. The downside: everything lands in one inbox. After a few years, you've got thousands of emails from dozens of aliases, all jumbled together. Good luck finding that one receipt.

fltr-mail fixes this by sorting emails into subfolders based on who they were sent to:

INBOX/
  amazon/       <- emails sent to amazon@yourdomain.com
  github/       <- emails sent to github@yourdomain.com
  newsletter/   <- emails sent to newsletter@yourdomain.com

Requirements

• Python 3.11+
• uv (recommended) or pip
• An IMAP-enabled email account

Installation

git clone git@github.com:nostoslabs/fltr-mail.git
cd fltr-mail

# With uv
uv sync

# Or with pip
pip install -e .

Configuration

cp .env.example .env

Edit .env:

IMAP_HOST=imap.example.com
IMAP_PORT=993
IMAP_SSL=true
IMAP_USER=your-email@example.com
IMAP_PASS=your-password
MAIL_DOMAIN=yourdomain.com

Provider examples

Mailfence:

IMAP_HOST=imap.mailfence.com
IMAP_PORT=993
IMAP_SSL=true

ProtonMail (via Bridge):

IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SSL=false
IMAP_PASS=<password-from-proton-bridge>

Fastmail:

IMAP_HOST=imap.fastmail.com
IMAP_PORT=993
IMAP_SSL=true

Usage

Test connection

uv run fltr test-connection

View stats

See email counts by recipient address:

uv run fltr stats

Total emails: 1247
Unique addresses: 43

  amazon: 312 (25.0%)
  github: 198 (15.9%)
  newsletter: 87 (7.0%)
  ...

List folders

uv run fltr folders

Dry run (preview)

See what would be moved without touching anything:

uv run fltr organize

Move emails

uv run fltr organize --execute

Options

  -x, --execute       Actually move emails (default is dry-run)
  -f, --folder TEXT   Source folder [default: INBOX]
  -n, --limit INT     Max emails to process
  -e, --env PATH      Path to .env file

Examples

# Process first 100 emails only
uv run fltr organize --limit 100 --execute

# Organize a different folder
uv run fltr organize --folder "Archive" --execute

# Use a specific config
uv run fltr organize --env /path/to/.env --execute

How it works

1. Connects via IMAP
2. Fetches headers (To, From, Subject) for each email
3. Extracts the local part of addresses matching your domain (amazon from amazon@yourdomain.com)
4. Creates subfolders as needed (INBOX/amazon)
5. Copies each email to its subfolder
6. Marks originals as deleted
7. Expunges at the end

A progress bar shows what's being processed.

Safety

Nothing moves unless you pass --execute. Emails are copied first, then marked deleted - the expunge only runs after all copies succeed. If you kill the script mid-run, you might end up with duplicates, but you won't lose mail.

Development

uv sync --group dev
uv run ruff check src/
uv run pytest

License

MIT