gmail-cleanup

Reclaim your Gmail inbox — safely. One-click unsubscribe (RFC 8058), declarative filter management, scheduled autopilot, and a hard-coded KEEP list that physically cannot unsubscribe you from your bank.

$ gmail-cleanup autopilot

🤖 gmail-cleanup autopilot — full inbox cleanup
━━━ Phase 1/4: Apply Gmail filters ━━━
   ✅ 8 upgraded, 4 created (all archive + mark read)
━━━ Phase 2/4: Unsubscribe noise senders (last 30d, min-count 2) ━━━
   ✅ 25 unsubscribed via RFC 8058 one-click POST, 61 inbox messages archived
━━━ Phase 3/4: Mark archived-unread as read ━━━
   ✅ 4,710 messages marked read
━━━ Phase 4/4: Verify previously-unsubscribed senders ━━━
   ⚠️  2 stuck (re-run with --escalate to auto-block)
   ✅ 18 silent (unsubs stuck)

🎉 Autopilot complete. Inbox: 144 (was 7,283) · Unread: 150 (was 4,858)

✨ Why it's different

📦 Installation

End users — isolated install via pipx (recommended):

pipx install gmail-inbox-cleanup

The PyPI package is gmail-inbox-cleanup (the gmail-cleanup name on PyPI belongs to an unrelated project); the command it installs is gmail-cleanup.

Developers — clone and edit:

git clone https://github.com/bgorzelic/gmail-cleanup.git
cd gmail-cleanup
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Requirements: Python 3.11+ and a Google Cloud project with the Gmail API enabled (the setup wizard walks you through both).

💡 Hitting OAuth errors? See TROUBLESHOOTING.md. The most common gotcha (consent screen / test users for unverified apps) is handled by the setup wizard in v0.5.1+.

🚀 Quick start

# First time — interactive wizard handles GCP, OAuth, config in 7 steps:
gmail-cleanup setup

# Daily use — one command runs the full cleanup pipeline:
gmail-cleanup autopilot

# Glance at inbox health:
gmail-cleanup status

# Two weeks later — escalate any unsubs that didn't stick:
gmail-cleanup autopilot --escalate

--dry-run previews any destructive command. --quiet for cron-friendly silent runs. --verbose for debug.

🧠 How it works

Every sender falls into one of three buckets:

                ┌──────────────────────────────────┐
  inbox mail ──▶│ Real human (humans.yaml)         │──▶  ⭐ star + important + spam-shield
                ├──────────────────────────────────┤
                │ Must-keep automation (keep.yaml) │──▶  🔒 NEVER unsubscribe (safety rail)
                │  banks, .gov, health, brokerage  │
                ├──────────────────────────────────┤
                │ Noise (kill.yaml + auto-discover)│──▶  🗑  one-click unsub + archive
                └──────────────────────────────────┘

Tune the buckets by editing the YAML files in ~/.gmail_cli/lists/ — no Python required.

How a sender gets picked

No AI, no guessing — deterministic rules over email headers, so every decision is explainable:

1. Group inbox mail by sender (From header).
2. Target a sender if it sent at least --min-count messages in the window, or matches kill.yaml.
3. Protect: drop anyone in humans.yaml (exact match — always wins), then anyone matching keep.yaml (substring).
4. Require a List-Unsubscribe header. No header means a person or a transactional sender — skipped, not archived.
5. Unsubscribe by the best method offered: RFC 8058 one-click POST → HTTPS GET → mailto:.
6. Archive that sender's inbox mail (never delete).
7. Verify later: mail still arriving after the unsubscribe plus a 2-day grace period marks the sender stuck; --escalate then blocks it.

Gentle on the Gmail API

Scans are batched and paced to Google's documented per-user quota (100 units/s), back off on rate limits (honoring Retry-After), and remember a throttle so a scheduled run never piles on. A 3,000-message inbox scans in about 10 minutes.

🛠 The autopilot pipeline

gmail-cleanup autopilot
   │
   ├── Phase 1  filters apply        Declare categorization rules to Gmail (idempotent)
   ├── Phase 2  unsubscribe          Find recent noise, hit RFC 8058 one-click, archive
   ├── Phase 3  mark-read            Clear the archived-but-unread backlog
   └── Phase 4  verify               Audit previous unsubs; --escalate to block stuck ones

Each phase also works standalone. Autopilot is the convenience composition.

📖 Commands

All destructive commands prompt for confirmation unless you pass --yes. Global flags: --quiet, --verbose, --all-accounts.

🔐 Safety model

Four YAML lists govern behavior. Each one is the packaged seed (shipped inside the package) merged with your own copy in ~/.gmail_cli/lists/<name>.yaml. Edit your copies to tune the tool — no Python required. Everything the tool writes goes to ~/.gmail_cli/lists/, never into the installed package.

The unsubscribe flow prefers RFC 8058 one-click POST (the standard Gmail/Apple now require for bulk senders). Falls back to GET, then mailto. Senders without any List-Unsubscribe header are skipped, not silently archived — that's a guard against accidentally archiving a real person.

See gmail_cleanup/lists/README.md for the conflict-resolution rules between the four files.

👥 Multi-account

gmail-cleanup accounts add work@company.com   --label work
gmail-cleanup accounts add personal@gmail.com --label personal
gmail-cleanup accounts list

# Run the same command across every configured account:
gmail-cleanup autopilot --all-accounts
gmail-cleanup stats     --all-accounts
gmail-cleanup verify    --all-accounts

Partial-failure semantics: if one account errors, the others still run. Failures are reported at the end. Exit code = number of failed accounts (0 = all clean).

🤖 Daily autopilot (macOS)

# Install a launchd job that runs autopilot every day at 08:00 local:
gmail-cleanup schedule install --time 08:00 --escalate

# Check it's wired up:
gmail-cleanup schedule status

# Remove it:
gmail-cleanup schedule uninstall

Linux (systemd) and Windows (Task Scheduler) integrations are on the roadmap.

🛠 Development

pip install -e ".[dev]"
pytest                # 200+ tests, <1s
ruff check .          # lint
ruff format .         # format

CI runs pytest on Python 3.11/3.12/3.13 for every push and PR.

📚 Documentation

• ARCHITECTURE.md — 5-minute tour of the codebase
• TROUBLESHOOTING.md — common first-run issues
• CHANGELOG.md — version history
• HANDOFF.md — current session state
• ROADMAP.md — what's planned
• CONTRIBUTING.md — how to contribute
• gmail_cleanup/lists/README.md — list conflict-resolution rules
• docs/AAR-2026-09-30.md — after-action report: the v0.6.0 release and first live cleanup
• docs/superpowers/specs/ — design specs for major features
• docs/superpowers/plans/ — implementation plans

🤝 Contributing

Issues, PRs, and discussion all welcome. Start with CONTRIBUTING.md — it covers the safety invariants you must not break.

The cardinal rule: the tool's job is to never unsubscribe you from your bank. Anything that loosens the KEEP list semantics for convenience will be rejected.

📄 License

MIT — see LICENSE.

_{Built by Brian Gorzelic. Safety-tested on a 7,283-email backlog before any of you used it.}