Gmail Email Cleanmail

A 100% local Gmail inbox analysis and cleanup tool. Helps you identify bulk senders, unsubscribe from newsletters, and clean up your inbox efficiently.

---

Privacy First

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   YOUR DATA NEVER LEAVES YOUR COMPUTER                         │
│                                                                 │
│   • All processing happens locally on your machine             │
│   • No external servers, no cloud storage, no tracking         │
│   • OAuth tokens stored only in local files                    │
│   • No analytics, telemetry, or data collection                │
│   • Open source - verify the code yourself                     │
│                                                                 │
│   The only network requests are directly to Gmail's API        │
│   using YOUR credentials on YOUR machine.                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Features

• Multi-account support - Connect and analyze multiple Gmail accounts
• Smart aggregation - Group emails by sender and domain
• Bulk actions - Mark as spam or trash entire senders/domains at once
• One-click unsubscribe - Uses List-Unsubscribe headers when available
• Gmail search filters - Focus on promotions, old emails, large attachments, etc.
• Privacy focused - Everything runs locally, nothing is transmitted externally

---

Quick Start

1. Clone the Repository

git clone https://github.com/kiwicro/Gmail-Email-Cleaner.git
cd Gmail-Email-Cleaner

2. Install Dependencies

Requires Python 3.10 or higher.

pip install -r requirements.txt

3. Set Up Google Cloud Credentials (One-Time Setup)

You need to create your own OAuth credentials. This takes about 5 minutes.

See detailed instructions below

4. Run the Tool

python run.py

Open your browser to http://127.0.0.1:5000

---

Google Cloud Setup

Since this tool accesses your Gmail, you need to create your own Google Cloud credentials. This ensures YOU control access to YOUR data.

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Sign in with your Google account
3. Click Select a Project (top navigation bar) → New Project
4. Enter project name: Gmail Cleanmail (or any name you prefer)
5. Click Create
6. Wait for creation, then make sure the project is selected

Step 2: Enable Gmail API

1. In the left sidebar, click APIs & Services → Library
2. Search for "Gmail API"
3. Click on Gmail API in the results
4. Click the blue Enable button

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select External and click Create
3. Fill in the required fields:
   • App name: Gmail Cleanmail
   • User support email: Select your email
   • Developer contact email: Enter your email
4. Click Save and Continue
5. On the Scopes page:
   • Click Add or Remove Scopes
   • Find and check these scopes:
     • https://www.googleapis.com/auth/gmail.readonly
     • https://www.googleapis.com/auth/gmail.modify
     • https://www.googleapis.com/auth/gmail.settings.basic
   • Click Update
6. Click Save and Continue
7. On Test users page:
   • Click + Add Users
   • Enter your Gmail address (the one you want to clean)
   • Add any other Gmail addresses you want to use
   • Click Add
8. Click Save and Continue → Back to Dashboard

Step 4: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click + Create Credentials → OAuth client ID
3. Select Desktop app as Application type
4. Name it: Gmail Cleanmail Desktop
5. Click Create
6. In the popup, click Download JSON
7. Rename the downloaded file to exactly: credentials.json
8. Move the file to: Gmail-Email-Cleaner/config/credentials.json

Step 5: First Run Authentication

1. Run python run.py
2. Click "+ Add Gmail Account" in the web interface
3. A browser window opens for Google sign-in
4. Sign in with a Gmail account you added as a test user
5. Click through the permissions (you may see "unverified app" warning - this is normal for personal projects, click "Advanced" → "Go to Gmail Cleanmail")
6. Grant the requested permissions
7. Done! The account appears in your dashboard

---

Usage

Scanning Your Inbox

1. After connecting your account(s), click "Scan All Emails"
2. Wait for the scan to complete (progress bar shows status)
3. View results by Sender or Domain

Optional: Use Gmail Search Filters

Enter filters in the search box before scanning:

Filter	What it does
category:promotions	Marketing emails only
category:social	Social media notifications
category:updates	Receipts, confirmations
is:unread	Only unread emails
older_than:1y	Emails older than 1 year
older_than:6m	Emails older than 6 months
larger:5M	Large emails (5MB+)
has:attachment	Emails with attachments

Combine filters: category:promotions older_than:6m

Taking Action

For each sender or domain, you can:

• View - See all emails from that sender
• Unsubscribe - Open the unsubscribe link (if available)
• Spam - Move all emails to spam folder
• Trash - Move all emails to trash

Use checkboxes for bulk actions on multiple senders at once.

---

Project Structure

Gmail-Email-Cleaner/
├── config/
│   └── credentials.json    ← Your OAuth credentials (you create this)
├── data/
│   └── tokens/             ← OAuth tokens (created automatically)
├── src/
│   ├── gmail_client.py     # Gmail API wrapper
│   ├── aggregator.py       # Email analysis logic
│   └── app.py              # Flask web server
├── templates/
│   └── index.html          # Web UI
├── static/
│   ├── style.css
│   └── app.js
├── requirements.txt
├── run.py                  ← Entry point
└── README.md

---

Security & Privacy

Privacy Guarantees

Guarantee	How It's Enforced
Data never leaves your machine	Server binds to 127.0.0.1 only - not accessible from network
No email content stored on disk	All scan data held in memory, cleared on app restart
No analytics or telemetry	Zero external API calls except Gmail API
No third-party services	Direct OAuth with Google - no middleman
Open source	Full code available for inspection

OAuth Scopes Explained

This tool requests only the minimum permissions needed:

Scope	Purpose	What It Allows
gmail.readonly	Read email headers	Sender, subject, date, snippets - NOT full body
gmail.modify	Take action on emails	Move to spam/trash, mark read
gmail.settings.basic	Create filters	Auto-trash future emails from senders

This tool CANNOT:

• ❌ Read full email body content
• ❌ Send emails on your behalf
• ❌ Permanently delete emails (only trash - recoverable for 30 days)
• ❌ Access contacts, calendar, or other Google services

Token Storage Security

Protection	Implementation
File permissions	Tokens saved with 600 permissions (owner read/write only) on Unix
Local storage only	Tokens stored in data/tokens/ - excluded from git
No encryption	Tokens are plain JSON - protected by OS file permissions
Easy revocation	Delete token files or revoke via Google Account

Application Security

Vulnerability	Protection
Path Traversal	Account IDs sanitized - only alphanumeric, underscore, hyphen allowed
XSS (Cross-Site Scripting)	All user data escaped before rendering via escapeHtml() and escapeAttr()
Malicious URLs	Unsubscribe links validated - only http/https/mailto allowed, localhost blocked
Input Injection	All API parameters validated and bounds-checked
Session Hijacking	Cryptographically random session keys, regenerated each restart
Memory Leaks	Automatic cleanup of old scan progress entries

Where Your Data Lives

Data	Location	Persistence	Shared Externally?
OAuth credentials	config/credentials.json	Until you delete	❌ Never
OAuth tokens	data/tokens/*.json	Until you delete	❌ Never
Email metadata	Memory only	Until app restart	❌ Never
Scan results	Memory only	Until app restart	❌ Never

Revoking Access

Option 1: Remove from Google Account

1. Go to Google Account Permissions
2. Find "Gmail Cleanmail" (or your app name)
3. Click Remove Access

Option 2: Delete Local Tokens

# Delete all stored tokens
rm data/tokens/*_token.json

Option 3: Both (recommended for complete removal)

1. Revoke access in Google Account
2. Delete local token files
3. Optionally delete config/credentials.json

---

Troubleshooting

"credentials.json not found"

Make sure you:

1. Downloaded the OAuth credentials from Google Cloud Console
2. Renamed the file to exactly credentials.json
3. Placed it in the config/ folder

"Access blocked: This app's request is invalid"

Your OAuth consent screen needs configuration:

1. Go to Google Cloud Console → OAuth consent screen
2. Make sure you added the Gmail API scopes
3. Make sure you added yourself as a test user

"Error 403: access_denied"

You need to add your Gmail address as a test user:

1. Google Cloud Console → OAuth consent screen
2. Go to "Test users" section
3. Add your Gmail address

"Token expired" or authentication errors

Delete the token file and re-authenticate:

1. Delete files in data/tokens/
2. Restart the app
3. Click "Add Gmail Account" again

App shows "unverified" warning

This is normal for personal OAuth apps. Click:

1. Advanced
2. Go to Gmail Cleanmail (unsafe)

This warning appears because the app isn't verified by Google (which requires a review process meant for public apps). Since this runs locally and you created the credentials yourself, it's safe.

---

Command Line Options

python run.py --help

Options:
  -p, --port PORT   Port to run on (default: 5000)
  --debug           Enable debug mode (for development)

---

Contributing

Issues and pull requests welcome! This is a personal tool shared for anyone who finds it useful.

---

Support

If you find this tool useful, consider supporting the project:

---

License

MIT License - Free to use, modify, and distribute.

---

Disclaimer

This tool is provided as-is. Always review what you're deleting before taking bulk actions. Trashed emails can be recovered within 30 days from Gmail's Trash folder.