gmail-cleaner

CLI tool for cleaning up Gmail accounts. Save attachments, analyze file types, and find the biggest space hogs in your inbox.

Setup

1. Create a Google Cloud project and enable the Gmail API
2. Create OAuth 2.0 credentials (Desktop app) and download credentials.json to the project root
3. Add your email as a test user in the OAuth consent screen
4. Install:

python -m venv .venv
source .venv/Scripts/activate  # Windows/Git Bash
# source .venv/bin/activate    # Mac/Linux
pip install -e .

Commands

save-attachments

Save email attachments filtered by size, sender, and file type.

gmail-cleaner save-attachments --min-size 5MB --max-size 25MB
gmail-cleaner save-attachments --from user@example.com --min-size 1MB
gmail-cleaner save-attachments --min-size 1MB --file-type jpg png --output-dir ./photos

Saves a manifest.json alongside attachments with full email metadata (subject, sender, recipients, date, labels, body).

get-attachment-types

List unique attachment file types grouped by sender.

gmail-cleaner get-attachment-types
gmail-cleaner get-attachment-types --from user@example.com

top-senders

Rank senders by number and total size of large attachments.

gmail-cleaner top-senders --min-size 5MB
gmail-cleaner top-senders --min-size 1MB --after 2024/01/01 --before 2025/01/01