A free, privacy-focused tool to bulk unsubscribe from emails, delete emails by sender, and mark emails as read. No subscriptions, no data collection - runs 100% on your machine.
✨ No Subscription Required - Free Forever
| Feature | Description |
|---|---|
| 🚫 Bulk Unsubscribe | Find newsletters and unsubscribe with one click |
| 🗑️ Delete by Sender | See who sends you the most emails, delete in bulk |
| ✅ Mark as Read | Bulk mark thousands of unread emails as read |
| 🔒 Privacy First | Runs locally - your data never leaves your machine |
| ⚡ Super Fast | Gmail API with batch requests (100 emails per API call) |
| 🎨 Gmail-style UI | Clean, familiar interface |
Scan senders → Select → Delete thousands of emails in seconds!
- Go to Google Cloud Console
- Create a new project (or select existing)
- Search for "Gmail API" and Enable it
- Go to APIs & Services → OAuth consent screen
- Choose External
- Fill in App name: "Gmail Cleanup" (or anything)
- Add your email as Test user
- Go to Credentials → Create Credentials → OAuth 2.0 Client ID
- Application type: Desktop app
- Download the JSON file
- Rename to
credentials.json
Download the docker-compose.yml file into a folder, and put your credentials.json inside it too. Then run:
docker compose up -dOpen http://localhost:8766 in your browser.
First-time sign-in: Click "Sign In" in the web UI, then check logs for the OAuth URL:
docker logs cleanup_email-gmail-cleaner-1Copy the URL from logs, open in browser, and authorize.
Clone the repository:
git clone https://github.com/Gururagavendra/gmail-cleaner.git
cd gmail-cleanerPut your credentials.json file in the project folder.
uv sync
uv run python main.pyThe app opens at http://localhost:8766
- ✅ 100% Local - No external servers, no data collection
- ✅ Open Source - Inspect all the code yourself
- ✅ Minimal Permissions - Only requests read + modify (for mark as read)
- ✅ Your Credentials - You control your own Google OAuth app
- ✅ Gitignored Secrets -
credentials.jsonandtoken.jsonnever get committed
Q: Why do I need to create my own Google Cloud project?
Because this app accesses your Gmail. By using your own OAuth credentials, you have full control and don't need to trust a third party.
Q: Is this safe?
Yes! The code is open source - you can inspect it. Your emails are processed locally on your machine.
Q: Can I use this for multiple Gmail accounts?
Yes! Click "Sign Out" and sign in with a different account. Each account needs to be added as a test user in your Google Cloud project.
Q: Emails went to Trash, can I recover them?
Yes! The delete feature moves emails to Trash. Go to Gmail → Trash to recover within 30 days.
PRs welcome! Feel free to:
- Report bugs
- Suggest features
- Improve the UI
- Add new functionality
MIT License - Use it however you want!
Made with ❤️ to help you escape email hell