A four-part toolkit that clears a cluttered Gmail inbox and builds the rules that keep it clear — as a byproduct of the cleanup itself. It runs entirely on your own machine against your own Google project, works on metadata only, never reads the body of your email, and never permanently deletes anything.
Clearing the backlog is the easy part. The reason you're back at 5,000 unread a year later is that nobody sets up rules afterward — the cleanup burns the energy you'd need to build the system that prevents the next one.
This toolkit flips that. Every time you tell it "trash everything from this sender," it doesn't just clear the backlog — it also creates a Gmail filter that automatically handles future mail from that sender. One decision, applied backward and forward. The rules aren't a separate chore you'll never get to. They fall out of the work you're already doing.
Think of it as an assembly line. The first two stages only read — they cannot change anything. The last two can write, but default to a dry run and ask you to confirm before touching a single message.
It works on the facts about each email — who, what subject, what date — never the body. A privacy win and a speed win: metadata is tiny, so tens of thousands of messages process fast.
Cleanup moves mail to Trash (recoverable 30 days) or Archive (kept forever, just out of the inbox). The permanent-delete operation is deliberately never used.
The path at a glance. The full guide in the repo spells out every click and command, including the one-time Google setup. This is the map.
You create your own credential that authorizes this toolkit to access your mailbox. You can't use anyone else's, and no one can use yours — that's the design, and it's what keeps your inbox safe.
Keep credentials.json private — treat it like a password. The included .gitignore blocks it from being committed by accident.
Check you have Python, then install the two libraries the scripts need.
Completely safe — it only reads. The first run opens your browser to sign in. When it finishes, open sender_report.html and study it. This report is the thinking part; the scripts are just muscle.
Edit the RULES block with senders from your report, then run with no flag. A dry run changes nothing — it shows how many messages each rule would affect. Read those counts.
When the counts look right, add --execute. It asks you to type yes before anything happens, then cleans up and creates your filters.
Run analyze.py for the deeper report, then use cleanup_advanced.py for mixed senders. The guide includes a copy-paste prompt that hands your analysis to an AI assistant to draft the advanced rules — you review and approve every one.
The golden rule: always dry-run and read the counts before any --execute. If a rule you expected to hit thousands shows zero, your pattern is probably mistyped. Nothing replaces your own eyes on the dry-run output.
Free and open-source under the MIT license. Clone it, read the guide, clean your inbox.
github.com/courtney-buck/gmail-cleanup-toolkit →