Inbox Cleanup

inbox-cleanup

Bulk IMAP email triage: classify → delete/archive by sender domain, subject keywords, or custom patterns.

When to Use This / When NOT to Use This

Use inbox-cleanup when:

Do NOT use inbox-cleanup when:

Boundary with other skills: This skill does NOT read email content for decision-making (no NLP/LLM classification). It matches on sender domain and subject string patterns only. For content-aware triage, a different approach is needed.

⚠️ What NOT to Delete

Some email categories look like noise but must be preserved:

Safeguard pattern: Add these sender domains to leave_domains in your config. When in doubt, archive instead of delete.

leave_domains:
  - ato.gov.au          # Australian Tax Office
  - myob.com            # Accounting
  - godaddy.com         # Domain registrar
  - cloudflare.com      # DNS / hosting
  - stripe.com          # Payments
  - paypal.com          # Payments
  - no-reply@apple.com  # Apple receipts

Key Files

Quick Start

# Step 1: Always dry-run first — no changes made, just a preview
python3 scripts/inbox_cleanup.py --config my_patterns.yaml --dry-run
Step 2: Review the output. If it looks right:
python3 scripts/inbox_cleanup.py --config my_patterns.yaml

What a Successful Dry-Run Looks Like

When dry-run completes, you'll see output like:

[DRY RUN] Would delete 142 emails from github.com
[DRY RUN] Would delete 38 emails from slack.com
[DRY RUN] Would archive 17 emails from notion.so
[DRY RUN] Would archive 9 emails matching keyword "newsletter"
[DRY RUN] Skipping 3 emails from leave_domains (stripe.com, paypal.com)
─────────────────────────────────────────────
Total would-delete: 180
Total would-archive: 26
Total skipped (leave_domains): 3

If the numbers look wrong (e.g. 0 matches when you expected hundreds), check: 1. The IMAP_HOST / IMAP_PORT / IMAP_USER env vars are set 2. The sender domains in your config match exactly (e.g. noreply.github.com ≠ github.com) 3. The script connected to the right IMAP folder (default: INBOX)

Required Env Vars

IMAP_HOST=127.0.0.1          # IMAP server host (127.0.0.1 for Proton Bridge local proxy)
IMAP_PORT=1143               # Port: 993 = direct SSL, 1143 = Proton Bridge STARTTLS
IMAP_USER=you@example.com    # Your IMAP login username
IMAP_PASSWORD=yourpassword   # IMAP password (use op read for 1Password)
IMAP_STARTTLS=true           # true = STARTTLS upgrade after connect (Proton Bridge); false = SSL-from-start
IMAP_SKIP_CERT_VERIFY=true   # true = accept self-signed cert (required for Proton Bridge)
ARCHIVE_FOLDER=Archive        # Exact IMAP folder name to move archived emails into (must already exist)

Or use --imap-* CLI flags. See python3 scripts/inbox_cleanup.py --help.

Config File Format (YAML)

# Sender domains whose emails should be permanently deleted
delete_domains:
  - github.com           # GitHub notifications (Issues, PRs, Actions)
  - noreply.github.com   # GitHub no-reply (different subdomain — list both if needed)
  - slack.com            # Slack digest/notification emails
Sender domains whose emails should be moved to Archive (not deleted)
archive_domains:
  - notion.so            # Notion share notifications
  - coinbase.com         # Crypto price alerts
Subject line keywords — emails matching any of these are archived (case-insensitive)
archive_keywords:
  - newsletter           # Matches "The Weekly Newsletter", "Newsletter #42", etc.
  - digest               # "Daily Digest", "Weekly Digest"
  - weekly roundup       # Exact substring match
Subject line regex patterns — emails matching any of these are deleted
Note: patterns are Python re.search() — anchored with ^ if you want start-of-line match
delete_subject_patterns:
  - "^\\[GitHub\\]"      # Subjects starting with "[GitHub]"
Sender domains that should NEVER be touched — overrides all other rules
Add banks, payment processors, auth providers, registrars here
leave_domains:
  - important-bank.com
  - stripe.com
  - paypal.com

Design Notes

Secret Management

Credentials via env vars or 1Password:

# Via env vars
export IMAP_PASSWORD="$(op read 'op://Vault/Email Account/password')"
python3 scripts/inbox_cleanup.py --config patterns.yaml

Common Mistakes

1. Running live without a dry-run first - Deleted emails may not be recoverable from all IMAP servers - Always run --dry-run first and review the counts

2. Domain mismatch — listing github.com but emails come from noreply.github.com - IMAP From headers often use subdomains. List both: github.com AND noreply.github.com - Run dry-run and check the "0 matches" — then inspect an actual email's From header

3. ARCHIVE_FOLDER doesn't exist in the mailbox - The script will error on archive operations if the folder isn't pre-created - Create the folder in webmail or your email client first

4. Proton Bridge not running when script executes - Port 1143 will refuse the connection - Ensure Proton Bridge desktop app is open and logged in before running

5. leave_domains not populated - Without leave_domains, the script will happily delete emails from payment processors, banks, and auth providers if they match another rule - Always populate leave_domains before any live run

6. STARTTLS vs SSL confusion - Direct IMAP SSL (Gmail, Fastmail): IMAP_PORT=993, IMAP_STARTTLS=false - Proton Bridge local proxy: IMAP_PORT=1143, IMAP_STARTTLS=true, IMAP_SKIP_CERT_VERIFY=true - Mixing these up causes connection failures or cert errors

# Step 1: Always dry-run first — no changes made, just a preview
python3 scripts/inbox_cleanup.py --config my_patterns.yaml --dry-run
Step 2: Review the output. If it looks right:
python3 scripts/inbox_cleanup.py --config my_patterns.yaml