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:

• - You need to bulk-delete or archive 50+ emails matching a pattern (sender domain, subject keyword)
• The inbox has a large backlog from known noisy senders (GitHub notifications, Slack digests, newsletters)
• You want a dry-run preview before committing any destructive action
• You need reproducible triage logic stored as config (not one-off manual clicks)

Do NOT use inbox-cleanup when:

• - Reading or searching for a specific email — use IMAP tools or webmail directly
• Triaging fewer than ~10 emails — just do it manually
• You want to reply, forward, or compose — this is delete/archive only
• You're unsure what's in the inbox — always dry-run first, never run live blind

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:

• - Transactional emails — order confirmations, shipping notices, receipts (needed for expense tracking)
• Auth codes / OTPs / 2FA emails — one-time codes, password resets
• Legal / compliance — invoices, tax docs, terms-of-service change notices
• Bank / financial — statements, transaction alerts
• Domain / hosting renewals — expiry notices from registrars, DNS providers

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

CODEBLOCK0

Key Files

• - scripts/inbox_cleanup.py — main cleanup script (dry-run by default)
• INLINECODE2 — pattern config template

Quick Start

CODEBLOCK1

What a Successful Dry-Run Looks Like

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

CODEBLOCK2

If the numbers look wrong (e.g. 0 matches when you expected hundreds), check:

1. 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

CODEBLOCK3

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

Config File Format (YAML)

CODEBLOCK4

Design Notes

• - UIDs not sequence numbers: The script always uses UID FETCH/UID STORE to

• - Dry-run by default: Always preview before committing. Pass --no-dry-run to apply.
• Batch fetching: Headers fetched in batches of 50 for large inboxes. One-at-a-time

• - Progress logging: Stdout log with counts per domain and final report JSON.
• STARTTLS support: Needed for Proton Bridge (port 1143 with self-signed cert).

Secret Management

Credentials via env vars or 1Password:

CODEBLOCK5

Common Mistakes

1. 1. Running live without a dry-run first

1. 2. Domain mismatch — listing github.com but emails come from noreply.github.com

1. 3. ARCHIVE_FOLDER doesn't exist in the mailbox

1. 4. Proton Bridge not running when script executes

1. 5. leave_domains not populated

1. 6. STARTTLS vs SSL confusion