Gmail Cleaner

A simple CLI tool to bulk delete emails from your Gmail inbox. Find your top email senders and delete them in one go.

Features

• Scan subscription emails (newsletters, promotions)
• Scan unread emails
• View top 20 senders by email count
• Bulk delete emails by sender
• Allowlist domains you want to keep
• Deletion history log

Setup

1. Create Google Cloud Project

1. Go to Google Cloud Console
2. Click Select a project → New Project
3. Name it (e.g., "Gmail Cleaner") and click Create

2. Enable Gmail API

1. In your project, go to APIs & Services → Library
2. Search for "Gmail API"
3. Click Gmail API → Enable

3. Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select External → Create
3. Fill in required fields:
   • App name: Gmail Cleaner
   • User support email: your email
   • Developer contact: your email
4. Click Save and Continue
5. On Scopes page, click Save and Continue (no changes needed)
6. On Test users page:
   • Click Add Users
   • Add your Gmail address
   • Click Save and Continue

4. Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Name: Gmail Cleaner
5. Click Create
6. Click Download JSON
7. Rename the file to credentials.json and move it to this folder

5. Install Dependencies

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

6. Run

python gmail_cleaner.py

On first run, a browser window will open for Google authentication. Sign in and click Continue (you may see a warning about unverified app - this is normal for personal projects).

Usage

Interactive Mode

python gmail_cleaner.py

Gmail Cleaner

What do you want to scan?
  1 - Top subscription emailers
  2 - Most unread emails
  q - Quit

> 1

Scanning top 1000 subscription emails...
  Processed 1000/1000...

Top 20 subscription senders:

#    Sender                              Emails
--------------------------------------------------
1    Newsletter Daily                       234
2    LinkedIn                               189
3    Medium                                 145
...

Commands:
  1,3,5    - Delete emails from these senders
  all      - Delete all listed
  keep 2,4 - Add to allowlist (won't show again)
  r        - Rescan (choose type)
  q        - Quit

> 1,3
Delete from: newsletter.com, medium.com? (y/n): y
  Deleting from newsletter.com... 234 emails trashed
  Deleting from medium.com... 145 emails trashed

Moved 379 emails to trash.

Direct Delete Mode

Delete all emails from a specific sender:

python gmail_cleaner.py newsletter@example.com
python gmail_cleaner.py linkedin.com

Files

File	Description
credentials.json	Your Google OAuth credentials (DO NOT SHARE)
token.pickle	Saved auth token (DO NOT SHARE)
allowlist.txt	Domains to skip when scanning
deleted_log.txt	History of deleted emails

Security

• credentials.json and token.pickle contain sensitive data - never commit them
• The tool only moves emails to Trash (recoverable for 30 days)
• You can revoke access anytime at Google Account Permissions

License

MIT