inbox-cleaner

A Python CLI tool that scans your Gmail inbox and lets you bulk unsubscribe from unwanted marketing emails, right from your terminal.

Built because I was tired of manually unsubscribing from dozens of newsletters one by one. I don't want to know when paper towels are going on sale. Wait actually I might want to-

Demo

Features

• Connects to Gmail via OAuth 2.0, your credentials never leave your machine
• Scans your inbox for subscription emails
• Groups emails by sender so you can see who's flooding your inbox
• Interactive terminal UI to select which senders to act on
• Three actions per sender: unsubscribe + trash, just trash, or just unsubscribe
• Attempts HTTP unsubscribe automatically using the List-Unsubscribe header

Requirements

• Python 3.10+
• A Google Cloud project with the Gmail API enabled
• OAuth 2.0 credentials (credentials.json)

Setup

1. Clone the repo

git clone https://github.com/rafiaauthoi/inbox-cleaner.git
cd inbox-cleaner

2. Create a virtual environment

python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Mac/Linux

3. Install dependencies

pip install -r requirements.txt

4. Set up Google Cloud credentials

• Go to console.cloud.google.com
• Create a project and enable the Gmail API
• Create OAuth 2.0 credentials (Desktop app)
• Download the JSON file and rename it to credentials.json
• Place it in the project root

5. Run

python -m inbox_cleaner.cli

A browser window will open for Google sign-in on first run. After that, your token is saved locally.

Project structure

inbox-cleaner/ ├── inbox_cleaner/ │ ├── auth.py # Gmail OAuth authentication │ ├── gmail.py # Gmail API calls (search, group, trash) │ ├── unsubscribe.py # HTTP unsubscribe logic │ └── cli.py # Terminal UI and main flow ├── requirements.txt └── README.md

Tech stack

• Python 3.12
• Gmail API via google-api-python-client
• OAuth 2.0 via google-auth-oauthlib
• Terminal UI via rich and questionary
• HTTP requests via httpx

Security

• credentials.json and token.pickle are excluded from version control via .gitignore
• OAuth scopes are limited to reading and modifying Gmail only