Gmail Cleaner: a self-hosted Gmail API cleanup tool with your own OAuth credentials
Cleanup your gmail | delete, mark as read, unsubsribe from uncessary things u dont like
At a glance
- What is it?
- Gmail Cleaner is a Python and Docker tool that bulk unsubscribes, deletes by sender and marks mail as read through the Gmail API, using OAuth credentials you create yourself. The privacy model is real, but the setup cost and the maintainer's own note about delayed responses are part of the decision.
- Who is it for?
- Adopt Gmail Cleaner if you are comfortable creating a Google Cloud project, enabling the Gmail API and managing your own credentials.json, and if you want delete, unsubscribe, archive and label actions run from your own machine. Do not adopt it if you need a hosted service, a signed support contract or a tool that reads message bodies, because the documentation describes metadata and sender-level operations.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 29 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The mailbox problem Gmail Cleaner targets
Gmail's own interface handles one sender at a time. If a newsletter has sent you 400 messages, the web UI makes you select them, confirm, and repeat. Gmail Cleaner exists to collapse that into a single action per sender. The README frames the audience directly: people who want to bulk unsubscribe from emails, delete emails by sender, and mark emails as read, with no subscription and no data collection. The repository also acknowledges a second audience in the README itself, users who reached out saying they like the idea but do not have the technical expertise to run it. That admission is useful. It tells you the project's real barrier is not the feature set but the Google Cloud Console setup, and it is why the README links a YouTube walkthrough and offers a paid one-on-one session. The tool is for a single user cleaning their own mailbox, not for an IT team managing many accounts. Nothing in the material describes multi-tenant operation, shared credential pools or admin delegation.
How the Gmail API calls are structured and batched
The architecture is a local Python application that talks to the Gmail API and serves a browser UI. The README lists the feature set as operations on senders: bulk unsubscribe, delete by sender, bulk delete across multiple senders with progress tracking, mark as read, archive, create and apply labels, mark important, and export sender metadata to CSV. Filters narrow the working set by date range, email size, category (Promotions, Social, Updates, Forums, Primary), sender and labels. The one performance detail the README states is that requests are batched at 100 emails per API call. That matters because Gmail API quota is consumed per call, not per message, so batching is the difference between a usable run and a throttled one. The README claims minimal permissions, requesting read plus modify. Read plus modify is worth pausing on: modify is what allows delete, archive, label changes and mark-as-read, so the scope is broader than a read-only analytics tool would need. The privacy claim rests on the code running locally and credentials staying in files that are gitignored, not on a narrow OAuth scope. credentials.json and token.json are excluded from version control per the README.
Getting it running: credentials, Docker and the port you actually open
Setup starts outside the repository. You create a Google Cloud project, search for Gmail API and enable it, then go through Google Auth Platform, set Audience to External, and add your own Gmail address under Test users. Skipping the test user step is the most common way to hit an access error, because an External app in testing only admits listed accounts. You then create a client under Clients, download the JSON, and rename it to credentials.json in the project folder. The application type depends on how you run it. Local Python with a browser wants Desktop app and needs no redirect URI. Docker on localhost wants Web application with redirect URI http://localhost:8767/. The README is explicit that redirect URIs must use a domain name and that Google OAuth does not allow IP addresses, so a server reachable only by IP needs a dynamic DNS name or a reverse proxy. Installation is git clone https://github.com/Gururagavendra/gmail-cleaner.git, then cd gmail-cleaner, then placing credentials.json. Docker runs with docker compose pull && docker compose up and the UI is at http://localhost:8766. Note the two ports: 8766 for the web UI, 8767 for the OAuth redirect. Local Python runs with uv run python main.py, and the prerequisites list Python 3.9+ and uv. After starting, you click Sign In and the README says to check the logs for the OAuth URL.
Where Gmail Cleaner breaks down or is the wrong tool
The largest documented risk is maintenance attention. The README opens with a note from the maintainer saying they are taking time off, cannot address all issues and pull requests, and ask for a month or two before normal response resumes. For a tool that depends on Google's OAuth console, whose wording and screens change without notice, that gap matters: a setup guide that drifts from the current console is the difference between a working install and an afternoon of confusion. The second limitation is scope. The stated permissions are read plus modify, and the feature list is sender-level. If you need to search message bodies, extract attachments, or run content-based rules, this is the wrong shape of tool. The third is deployment friction. The redirect URI rules rule out a plain IP-addressed server, and every user must create their own Google Cloud project and OAuth client, which the README presents as a privacy feature and which is also an unavoidable per-user setup cost. The fourth is that unsubscribe is not guaranteed. The README describes finding newsletters and unsubscribing with one click, but the actual outcome depends on what the sender does with the request, and nothing in the material promises a confirmation path.
How it differs from Gmail's built-in filters and from IMAP scripts
Gmail's native filters are the closest alternative and they work differently. A filter is a standing rule evaluated on incoming mail: it can label, archive or delete messages as they arrive, and it runs server-side with no local process and no OAuth client of your own. Gmail Cleaner is retrospective and manual. It scans what is already in the mailbox, groups by sender, and applies an action to that existing set. If your problem is future mail, filters solve it and Gmail Cleaner does not. If your problem is the 12,000 messages already sitting in Promotions, filters do nothing and Gmail Cleaner is the right shape. The other alternative is a hand-written IMAP or Gmail API script, which gives you full control over scope and logic but leaves you writing batching, pagination, progress reporting and a UI. Gmail Cleaner's contribution is that it packages the batching at 100 messages per call, the sender aggregation, the CSV export and a browser interface, and ships it as a Docker image. That is a meaningful amount of plumbing you would otherwise rebuild, and it is the honest reason to pick it over a fifty-line script.
Maintenance cost, release cadence and the MIT licence
The release history shows v1.3.0 on 2025-12-23, preceded by v1.2.2 and v1.2.1 on 2025-12-21, so two patch releases landed within two days of the feature release. That pattern suggests active iteration during that window rather than a long-stable surface. The last push recorded is 2026-08-18, and the maintainer's note about stepping back sits at the top of the README, so treat upgrade cadence as unpredictable and pin the Docker image rather than tracking latest if you care about reproducibility. The licence is MIT, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. MIT also means no warranty and no liability, which for a tool holding a token that can delete mail is worth reading literally. The repository is not archived, so the code remains available and forkable. If the maintainer's pause becomes permanent, MIT lets you fork and maintain your own copy, but you inherit the Google Cloud Console setup guide and will need to keep it current yourself. This is not legal advice; read the LICENSE file in the repository for the actual terms.
A concrete judgement before you install it
The privacy story here is genuine and narrow. Code runs on your machine, credentials live in credentials.json and token.json, both gitignored, and you own the Google Cloud project. That is a different proposition from a hosted cleaner that asks you to grant mailbox access to a third party. But the cost is real and front-loaded: a Google Cloud project, an enabled Gmail API, an External consent screen with your address under Test users, a client whose type must match your deployment, and a redirect URI that must be a domain rather than an IP. If any of those steps is wrong, the app starts and the sign-in fails, and the README's own remedy is to check the logs for the OAuth URL. Decide based on that trade. If you already run Docker and have created an OAuth client before, the setup is a short evening and the batched sender operations earn their place. If you have never opened the Google Cloud Console, budget for the YouTube walkthrough or the paid session, and factor in that the maintainer is currently asking for one to two months before normal response times return.
Editorial conclusion
Adopt Gmail Cleaner if you are comfortable creating a Google Cloud project, enabling the Gmail API and managing your own credentials.json, and if you want delete, unsubscribe, archive and label actions run from your own machine. Do not adopt it if you need a hosted service, a signed support contract or a tool that reads message bodies, because the documentation describes metadata and sender-level operations. Before committing, verify the redirect URI matches your deployment shape (Desktop app for local Python, Web application with http://localhost:8767/ for Docker), confirm your Google Cloud consent screen has your address added under Test users, and check the issue tracker for response times given the maintainer's note that replies are currently delayed by a month or two.
Community notes