gmail-cleanup-agent 1.0.0

A smart agentic CLI tool to bulk delete Gmail emails using search queries

🤖 Gmail Cleanup Agent

A smart, agentic CLI tool that automatically deletes emails matching any Gmail search query — looping until your inbox is spotless.

Built with Python + Gmail API. Runs locally. Your data never leaves your machine.

---

✨ Features

• 🔍 Any Gmail query — use the full power of Gmail search syntax
• 👀 Dry-run mode — preview matching emails before deleting anything
• 🔁 Agentic loop — keeps running until zero emails match the query
• 🗑️ Trash or delete — move to Trash (recoverable) or permanently delete
• 🎨 Colorful terminal output — clear progress reporting
• ⚡ Interactive mode — guided experience for non-technical users
• 🖥️ CLI mode — scriptable for power users and automation

---

📋 Prerequisites

• Python 3.8+
• A Google account
• A Google Cloud project with Gmail API enabled (free — setup takes ~5 minutes)

---

🚀 Quick Start

Step 1 — Clone the repo

git clone https://github.com/YOUR_USERNAME/gmail-cleanup-agent.git
cd gmail-cleanup-agent

Step 2 — Set up a virtual environment

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

Step 3 — Install dependencies

pip install -r requirements.txt

Step 4 — Set up Gmail API credentials

1. Go to Google Cloud Console
2. Create a new project (e.g. gmail-cleanup)
3. Go to APIs & Services → Library → search for Gmail API → Enable it
4. Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
   • Application type: Desktop App
   • Download the JSON file → rename it to credentials.json
5. Place credentials.json in the project folder
6. Go to Google Auth Platform → Audience → Test Users → add your Gmail address

Step 5 — Run it!

python3 gmail_cleanup_agent_v2.py

A browser window will open for authentication. After that, you're good to go!

---

💻 Usage

Interactive Mode (recommended for first-time users)

Just run without any arguments — it guides you through everything:

python3 gmail_cleanup_agent_v2.py

CLI Mode (for power users)

# Preview matching emails without deleting (dry run)
python3 gmail_cleanup_agent_v2.py --query "category:promotions" --dry-run

# Move to Trash (recoverable for 30 days) — DEFAULT
python3 gmail_cleanup_agent_v2.py --query "category:promotions" --mode trash

# Permanently delete — use with caution!
python3 gmail_cleanup_agent_v2.py --query "category:promotions" --mode delete

Arguments

Argument	Short	Description
--query	-q	Gmail search query
--mode	-m	trash (default) or delete
--dry-run	-d	Preview only, no deletions

---

🔍 Useful Query Examples

Goal	Query
All promotional emails	category:promotions
All social notifications	category:social
All newsletter/updates	category:updates
Unread older than 1 year	is:unread older_than:1y
Everything from LinkedIn	from:linkedin.com
Multiple senders	from:linkedin.com OR from:facebook.com
Unread promotions only	is:unread category:promotions
Old unread emails	is:unread older_than:6m
All of the above at once	category:promotions OR category:social OR category:updates

---

🔒 Privacy & Security

• Your credentials never leave your machine — the script runs entirely locally
• credentials.json and token.pickle are listed in .gitignore — never commit them
• The app requests https://mail.google.com/ scope — required for delete operations
• You can revoke access anytime at myaccount.google.com/permissions

---

⚠️ Important Notes

• Always do a dry run first before deleting — especially with broad queries
• --mode trash is the safe default — emails stay in Trash for 30 days before permanent deletion
• Gmail API has rate limits — the agent automatically pauses between rounds to avoid hitting them
• The resultSizeEstimate shown in dry-run is capped at ~201 by the Gmail API — the real count may be much higher. The agent will keep looping until all matching emails are gone.

---

🛠️ How It Works

This is a simple agentic loop:

1. Run Gmail search query
2. If emails found → delete them in batches of 100
3. Wait briefly (rate limit protection)
4. Repeat from step 1
5. If no emails found → done ✅

It's a great example of an AI agent pattern: a loop that takes an action, observes the result, and repeats until a goal condition is met.

---

📁 Project Structure

gmail-cleanup-agent/
├── gmail_cleanup_agent_v2.py   # Main agent script
├── requirements.txt             # Python dependencies
├── README.md                    # This file
├── .gitignore                   # Excludes credentials from git
├── credentials.json             # ← YOU provide this (not in repo)
└── token.pickle                 # ← Auto-generated on first run (not in repo)

---

🤝 Contributing

Contributions welcome! Some ideas for future improvements:

• Web interface (Flask/Next.js)
• Chrome Extension
• Unsubscribe automation
• Scheduled/recurring cleanup (cron)
• Label-based archiving instead of deletion
• Support for multiple Gmail accounts

Feel free to open an issue or submit a PR!

---

📄 License

MIT License — free to use, modify, and distribute.

---

🙏 Acknowledgements

Built with Google Gmail API and Python.