Gururagavendra/gmail-cleaner

What is it?

Key features

• 01Bulk unsubscribe from newsletters from a single interface
• 02Delete emails by sender, including multiple senders at once, with progress tracking
• 03Filter by date range, email size, Gmail category, sender, and labels
• 04Bulk mark as read, archive, apply or remove labels, and mark important
• 05Export sender email metadata to CSV
• 06Runs locally with Docker or Python, with credentials you control

Use cases

• Cutting down a cluttered inbox full of promotional newsletters
• Clearing out years of mail from a few noisy senders
• Marking thousands of old unread emails as read in one pass
• Auditing which senders email you most before deciding what to unsubscribe from

Quick start

1. 1

   Clone the repository

   git clone https://github.com/Gururagavendra/gmail-cleaner.git
2. 2

   Navigate to the project folder

   cd gmail-cleaner
3. 3

   Install dependencies with uv

   uv sync
4. 4

   Run the app and open http://localhost:8766

   uv run python main.py

Things to know

• !You must create your own Google Cloud OAuth credentials (credentials.json) before it works.
• !Setup involves Google Cloud Console, test-user configuration and OAuth redirect URIs, which can be fiddly.
• !Remote or Docker use with a web OAuth client requires a domain name, since IP addresses are not allowed as redirect URIs.

Topics

FAQ

What is gmail-cleaner?

A free, self-hosted Python tool that runs locally to bulk unsubscribe from newsletters, delete emails by sender, and mark emails as read in Gmail. Gmail Cleaner is a local web app for tidying a Gmail inbox. It lets you find newsletters and unsubscribe from them, scan which senders email you most often, and delete or archive their messages in bulk. It also supports marking large numbers of unread emails as read, managing labels, marking messages important, and exporting sender metadata to CSV.

Is gmail-cleaner free to use? What license does it have?

gmail-cleaner is open source under the MIT license. Check the license terms before using it in commercial products.

Is gmail-cleaner still maintained?

Updated within 6 months. The last commit to gmail-cleaner was on Aug 18, 2026.

What can I use gmail-cleaner for?

Cutting down a cluttered inbox full of promotional newsletters Clearing out years of mail from a few noisy senders Marking thousands of old unread emails as read in one pass Auditing which senders email you most before deciding what to unsubscribe from

How do I install gmail-cleaner?

Clone the repository: git clone https://github.com/Gururagavendra/gmail-cleaner.git Navigate to the project folder: cd gmail-cleaner Install dependencies with uv: uv sync Run the app and open http://localhost:8766: uv run python main.py

Where can I get gmail-cleaner?

The source code and installation instructions are on GitHub: https://github.com/Gururagavendra/gmail-cleaner