DEV Community

Jude Hilgendorf
Jude Hilgendorf

Posted on

I Built a Chrome Extension That Bulk-Cleans Gmail in One Click (and Why You Probably Need It)

#chromeextension #javascript #opensource #productivity

I Built a Chrome Extension That Bulk-Cleans Gmail in One Click

If you're like me, your Gmail inbox is a graveyard of newsletters you never read, promo emails from 2019, and 40MB attachments from a group project you forgot about. Google gives you 15GB free, and somehow that "free" tier feels like extortion the second you cross it.

So I built Gmail One-Click Cleaner — an open-source, Manifest V3 Chrome extension that bulk-cleans Gmail in one click. No servers, no analytics, no API keys. Everything runs in your browser.

The problem

The "obvious" solution everyone reaches for is one of those services that asks for full Gmail OAuth scope. You hand over your entire mail history to a startup you've never heard of, and they delete some emails for you. That's a wild trade.

I wanted something that:

  • Runs 100% locally — never touches my email content over the network
  • Uses Gmail's own UI to do the deletion (so it's basically simulating what I'd do manually)
  • Has safety rails so I don't accidentally nuke important stuff
  • Is fast enough to clean tens of thousands of emails without me babysitting it

What it does

It runs configurable cleanup rules against your inbox. Out of the box it ships with categories like:

  • Promotions older than 6 months
  • Social updates older than 1 year
  • Anything with "unsubscribe" older than 1 year
  • Attachments larger than 10MB older than 6 months

You pick a rule set (Light / Normal / Deep), pick a mode (Live / Review / Dry-Run), and hit go. A live dashboard shows progress, per-rule results, and estimated MB freed.

Architecture (the interesting bit)

The whole thing is a Manifest V3 extension, which forced me into some interesting design decisions:

manifest.json         → MV3 manifest, minimal permissions
background.js         → Service worker (alarms, messaging, stats)
contentScript.js      → Gmail DOM automation (injected into Gmail)
popup.html/js         → Extension popup UI
progress.html/js      → Live progress dashboard
options.html/js       → Rules & settings
shared.css/js         → Design tokens + GCC utility namespace
browser-polyfill.js   → Cross-browser shim (Chrome, Edge, Brave, Firefox)
Enter fullscreen mode Exit fullscreen mode

The cleanup engine lives in contentScript.js. It uses Gmail's existing search syntax — the same thing you'd type into the search bar — to scope each rule:

// Example: pull anything in promotions older than 6 months
const query = "category:promotions older_than:6m";

// Then we drive Gmail's UI: open search, select all matching threads,
// click "Select all conversations that match this search", click Trash.
Enter fullscreen mode Exit fullscreen mode

Sounds simple, but Gmail's UI is a moving target. Every few months the DOM shifts. So I built helpers around MutationObserver to wait for elements rather than setTimeout everywhere — that one change cut flakiness by maybe 80%.

The safety rails

The first version of this thing scared me. So I wired in real guardrails:

Minimum age cutoff. Every rule has a "never touch anything newer than X" floor. Default is 3 months. You'd be amazed how often this saves you.

Global whitelist. Senders or domains you protect from every rule, no matter what. Bank, employer, family — done.

Safe Mode. Skips categories that are statistically dangerous: receipts, order confirmations, shipping updates. Even if a rule matches, Safe Mode will block it.

Skip starred & important. On by default. Gmail's "Important" classifier isn't perfect, but it's good enough as a backstop.

Dry-Run mode. Run any rule set and just count matches. No deletion. This is the mode I always tell new users to start in.

Even with all that, Gmail keeps trashed mail for ~30 days, so worst case you've got a recovery window.

Privacy: this part actually matters

The thing I'm proudest of is the permissions footprint. The whole extension needs:

"permissions": ["activeTab", "scripting", "tabs", "storage"],
"host_permissions": ["https://mail.google.com/*"]
Enter fullscreen mode Exit fullscreen mode

That's it. No <all_urls>. No identity. No webRequest. Storage is local (your settings live in chrome.storage.local, never synced unless you toggle it). There is no backend. There is no analytics SDK. There is no telemetry. The repo's open source — go check manifest.json yourself.

If you've ever installed a "free" extension and felt that creeping suspicion, this should feel different.

Why I built this

I'm a CompTIA-track cybersecurity student who reads a lot of breach reports for fun. Most "free" tools that touch email are not free — you're paying with your data, and the second their startup pivots or gets acquired, the rules change.

I wanted a tool I'd actually trust on my own inbox. So I built it, used it, and shipped it.

Try it

Grab it here: github.com/TiltedLunar123/gmail-one-click-cleaner

If you find it useful, a star helps a ton. PRs welcome — there's a CONTRIBUTING.md with the dev setup and a Jest test suite to keep things honest.

What's the most ridiculous thing your Gmail is hoarding right now? Drop a screenshot in the comments — I'm taking nominations for default rules in v5.

Top comments (0)