Gmail Cleaner

A Ruby script that automatically cleans up old emails from your Gmail account by deleting messages older than specified thresholds across different categories.

Features

• Category-based cleanup: Handles Forums, Purchases, Social, Updates, Promotions, and all old emails
• OAuth 2.0 authentication: Secure Google API authentication with token storage
• Batch processing: Efficiently processes emails in batches of 500
• Configurable thresholds: Different retention periods for different email categories

Prerequisites

• Ruby (check .ruby-version for version)
• Gmail account with API access
• Google Cloud Platform project with Gmail API enabled

Installation

1. Clone the repository

   git clone <repository-url>
   cd gmail-cleaner

2. Install dependencies

   bundle install

3. Set up Google Cloud Platform

   • Go to Google Cloud Console
   • Create a new project
   • Enable the Gmail API
   • Create OAuth 2.0 credentials:
     • Application type: Desktop app
     • Download the client_secret.json file
   • Place client_secret.json in the project root

Configuration

Gmail API Scopes

The script uses these scopes:

• https://www.googleapis.com/auth/gmail.modify - Read, send, delete, and manage email
• https://mail.google.com/ - Full access to the account

Retention Periods

Category	Retention
Forums	3 months
Purchases	6 months
Social	3 months
Updates	6 months
Promotions	3 months
All other emails	10 years

Modify the queries array in app.rb to adjust these thresholds.

Usage

1. Run the script

   ruby app.rb

2. First-time authorization

   • A local OAuth server starts on http://localhost:8888
   • Your default browser opens to Google's login page
   • After authorizing, tokens are saved to token.json
   • Subsequent runs use cached credentials

3. Monitor progress

   • The script displays each query being processed
   • Shows batch deletion progress
   • Reports total emails deleted

Files

File	Description
app.rb	Main Ruby script
Gemfile	Ruby dependencies
client_secret.json	Google OAuth credentials (you provide)
token.json	Cached OAuth tokens (auto-generated)

Security

Important: Never commit client_secret.json or token.json to version control!

This project includes a .gitignore that excludes:

• client_secret.json - Your OAuth client secret
• token.json - Cached authentication tokens
• .DS_Store - macOS system files

If you accidentally commit these files, revoke them immediately in Google Cloud Console and create new credentials.

Troubleshooting

"Error: No code received"

• Ensure the OAuth redirect URI matches your Google Cloud Console configuration

"Failed to get credentials"

• Delete token.json and re-run the script to re-authenticate

"Token file not found"

• Run ruby app.rb to trigger the OAuth flow

API quota errors

• The script processes in batches with minimal delay
• For very large mailboxes, consider running during off-peak hours

License

MIT License