Gmail Bulk Delete by Label 🗑️

A Python tool to permanently delete thousands of Gmail emails by label in minutes. Free up your Gmail storage without paying for Google One!

✨ Features

• 🎯 Delete all emails in a specific Gmail label
• 💾 Permanent deletion - frees storage immediately (bypasses trash)
• 🚀 Fast - delete 10,000+ emails per minute
• 🔄 Auto-resume if interrupted
• ☕ Prevents Mac from sleeping during deletion
• 📊 Real-time progress tracking
• 🔒 100% local - your credentials never leave your computer

📋 Requirements

• macOS (tested on macOS 12+)
• Python 3.8 or higher
• A Gmail account
• 10 minutes for setup

🚀 Installation

Step 1: Install pyenv (if not installed)

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install pyenv
brew install pyenv

# Add pyenv to zsh config
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# Reload shell configuration
source ~/.zshrc

Step 2: Setup Project

# Clone the repository
git clone https://github.com/chungnguyen-dev/gmail-bulk-delete.git
cd gmail-bulk-delete

# Install Python 3.12 (or your preferred version 3.8+)
pyenv install 3.12.6

# Set Python version for this project
pyenv local 3.12.6

# Verify correct Python version
python --version  # Should show: Python 3.12.6

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install --upgrade pip
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Step 3: Get Gmail API Credentials

3.1 Create Google Cloud Project

1. Go to Google Cloud Console
2. Click "Select a project" → "NEW PROJECT"
3. Project name: Gmail Bulk Delete → Click "CREATE"
4. Wait ~10 seconds for creation

3.2 Enable Gmail API

1. Make sure your project is selected (check top left)
2. Go to API Library
3. Search: "Gmail API"
4. Click "Gmail API" → Click "ENABLE"

3.3 Configure OAuth Consent Screen (Updated)

1. In the Cloud Console sidebar go to:
   APIs & Services → OAuth consent screen
2. If you are redirected to Google Auth Platform / Overview:
   • Click Get Started to configure your OAuth setup.
3. Under Branding / App Information:
   • App name: Gmail Bulk Delete
   • User support email: [your email]
   • (Optional) Logo / home page
   • Click Next.
4. Under Audience:
   • Choose External
   • Click Next.
5. Contact information:
   • Enter your email address where you want to receive notifications.
   • Click Next.
6. Finish / Create:
   • Review the Google API Services User Data Policy and accept.
   • Click Create.
7. After creation you should now be in the OAuth configuration dashboard.

3.3.1 Add Gmail Scopes

1. In the OAuth screen dashboard, go to Data access → Add or remove scopes.
2. In the filter box, paste:
   https://mail.google.com/
3. Check the box next to the Gmail scope.
4. Click Update → Save.

3.3.2 Add Test Users (for External apps)

If you selected External, you need to add test users before using the OAuth flow:

1. Still in the OAuth screen menu, go to Audience → Test users.
2. Click Add users.
3. Enter your Gmail address.
4. Save.

3.4 Create OAuth Credentials

1. Go to Credentials
2. Click + CREATE CREDENTIALS → OAuth client ID.
3. Application type: Desktop app.
4. Name: Gmail Delete Desktop.
5. Click CREATE.
6. Click DOWNLOAD JSON (⬇️ icon).
7. Save the file as credentials.json in your project folder.

📖 Usage

First Time

# Make sure you're in the project folder
cd gmail-bulk-delete

# Activate virtual environment
source .venv/bin/activate

# Run the tool
python gmail_delete.py

What happens:

1. 🌐 Browser opens for Gmail authentication
2. 🔑 Login with your Google account
3. ⚠️ Click "Advanced" → "Go to Gmail Bulk Delete (unsafe)"
4. ✅ Click "Allow" to grant permissions
5. ✅ Browser shows "Authentication complete!" - close the tab
6. 📋 Terminal shows your Gmail labels
7. 🎯 Select a label by entering its number
8. 📊 Tool shows how many emails will be deleted
9. ⚠️ Type DELETE to confirm
10. 🗑️ Deletion begins with real-time progress!

Next Time

cd gmail-bulk-delete
source .venv/bin/activate
python gmail_delete.py

No browser authentication needed - your token is saved!

Example Session

============================================================
🚀 GMAIL BULK DELETE BY LABEL
============================================================

🔐 Authenticating with Gmail...
✅ Authentication successful!

📋 Fetching your Gmail labels...

============================================================
📁 YOUR GMAIL LABELS
============================================================
  1. Newsletters
  2. Promotions  
  3. Social
  4. Old Projects
  5. Archive 2020
============================================================

Total: 5 labels

🎯 Enter label number to delete emails from (or 'q' to quit): 1

🔍 Searching for emails in label...
📧 Total found: 12,450 emails

============================================================
⚠️  CONFIRMATION REQUIRED
============================================================
Label: Newsletters
Emails to delete: 12,450
Type: PERMANENT deletion (bypass trash)
Storage freed: Immediate
============================================================

⚠️  THIS CANNOT BE UNDONE!

🔴 Type 'DELETE' to confirm (or 'cancel' to abort): DELETE

☕ Sleep prevention enabled (Mac will stay awake)

🗑️  DELETING 12,450 EMAILS
============================================================
⚠️  Permanent deletion - emails will NOT go to trash
============================================================
✅ Progress: 1,000/12,450 (8.0%)
   Speed: 12,000 emails/min | ETA: 1.0 min
✅ Progress: 5,000/12,450 (40.2%)
   Speed: 11,950 emails/min | ETA: 0.6 min
✅ Progress: 10,000/12,450 (80.3%)
   Speed: 11,920 emails/min | ETA: 0.2 min
✅ Progress: 12,450/12,450 (100.0%)
   Speed: 11,890 emails/min | ETA: 0.0 min

============================================================
📊 DELETION REPORT
============================================================
Label: Newsletters
Total found: 12,450 emails
Successfully deleted: 12,450 emails
Errors: 0
Duration: 1.0 minutes
Average speed: 11,890 emails/minute

Quota used: 650 units
Efficiency: 19.2 emails/unit
============================================================

✅ SUCCESS! Your Gmail storage has been freed.
   Deleted emails are gone permanently (not in trash)

😴 Sleep prevention disabled

🔄 Auto-Resume Feature

If the program stops (you close it, Mac sleeps, network issue):

python gmail_delete.py

You'll see:

============================================================
📂 PREVIOUS DELETION FOUND
============================================================
Label: Newsletters
Deleted: 5,000 emails
Remaining: 7,450 emails
Last saved: 2025-02-16 14:30:45
============================================================

🔄 Resume from checkpoint? (yes/no): yes

Type yes and it continues exactly where it stopped!

📊 Performance

The tool automatically manages Gmail API quotas and waits when needed.

🛠️ Troubleshooting

"credentials.json not found"

Make sure you:

1. Downloaded the OAuth credentials from Google Cloud Console
2. Saved the file as exactly credentials.json (not client_secret_....json)
3. Placed it in the gmail-bulk-delete folder

"No module named 'google'"

You forgot to activate the virtual environment:

source .venv/bin/activate

Your prompt should show (.venv) at the beginning.

"python: command not found"

Make sure pyenv is configured:

# Check Python version
python --version

# If it doesn't show 3.12.6, reinstall:
pyenv local 3.12.6

"Insufficient Permission" error

You need to add the Gmail scope in OAuth consent screen:

1. Go back to Step 3.3
2. Make sure you added: https://mail.google.com/
3. Try running the script again

Browser doesn't open

Manually copy the URL from the terminal and paste it into your browser.

🔒 Privacy & Security

What stays on your computer:

• ✅ credentials.json - OAuth client ID (from Google)
• ✅ token.pickle - Your authentication token
• ✅ deletion_checkpoint.json - Progress data (temporary)

What gets sent:

• ✅ Gmail API requests (to gmail.googleapis.com)
• ❌ Nothing else - no analytics, no tracking, no external servers

❓ FAQ

Q: Can I undo the deletion?
A: No. This is permanent deletion. That's why it asks you to type DELETE to confirm.

Q: Why permanent instead of moving to trash?
A: Emails in trash still use storage. Permanent deletion frees space immediately.

Q: Is it safe?
A: Yes. The code is open source - you can review it. It only uses official Gmail API.

Q: Will Google ban my account?
A: No. The tool respects all Gmail API quotas and limits.

Q: Can I delete from multiple labels?
A: Run the script multiple times and select different labels each time.

Q: What if I have 1 million emails?
A: It works! The tool saves progress every 1,000 emails.

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

📜 License

MIT License - see LICENSE file

⚠️ Disclaimer

This tool permanently deletes emails. Use at your own risk. Always verify which label you're selecting before confirming deletion.

---

Made with ❤️ to help people reclaim their Gmail storage

Questions? Open an issue

Find it useful? Give it a ⭐ on GitHub!