Part no. GC-01 · self-hosted · The mail sorter
GmailCleaner
A self-hosted Gmail engine that shows you the cleanup plan, then waits for your approval.
Built by Deepesh Kumar
The problem
An inbox fills up with newsletters, promotions and threads that need a reply, all mixed together.
Cleanup tools usually mean a subscription, your mail on someone else's servers, and actions taken before you've seen them.
What I built
A privacy-first Gmail engine that runs on a schedule in your own Google Cloud project, or on your own machine. No shared servers, analytics or telemetry.
Its rule is show first, act second: it finds the junk, sorts what matters and drafts the cleanup, then nothing is unsubscribed or binned until you approve it on the dashboard.
How it works
- 01 · Scan
Fetches message metadata only. Email bodies are never fetched; Gemini sees sender, subject, a short snippet and labels.
- 02 · Sort
Gemini triages mail into Needs reply, FYI, Promotions and Junk. Low-confidence calls are flagged for review instead of guessed.
- 03 · Plan
The unsubscribe engine reads List-Unsubscribe headers (RFC 2369 and one-click RFC 8058). Bulk cleanup groups clutter by sender domain and repeating subject patterns, ranked by volume, unread rate and how promotional it looks.
- 04 · Wait
Every scan writes a pending-actions report where every item starts unconfirmed, and sends a one-page daily digest. You approve on the dashboard, or pre-approve senders with trusted rules you write yourself.
- 05 · Act
Only confirmed items run, each one once: one-click POST, then HTTP, then mailto for unsubscribes; cleanup groups go to Trash. Gmail Pub/Sub pushes start triage within seconds of new mail.
Results
- Nothing is unsubscribed or cleaned up without explicit approval, or a trusted rule you wrote.
- Cleaned-up mail goes to Trash, so it stays recoverable for 30 days.
- Runs entirely inside your own GCP project, within the free tier for personal use.
- Open source under the MIT licence, with CI on every push.
Tech stack
- Python
- Gmail API + OAuth 2.0
- Gemini
- Cloud Run
- Cloud Scheduler
- Pub/Sub
- Cloud Storage
- Secret Manager
- SQLite
On the monitor
The daily digest: the inbox, sorted, with actions waiting for approval.