# 🤖 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.

![Python](https://img.shields.io/badge/python-3.8+-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Gmail API](https://img.shields.io/badge/Gmail-API-red)

---

## ✨ 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

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

### Step 2 — Set up a virtual environment

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

### Step 3 — Install dependencies

```bash
pip install -r requirements.txt
```

### Step 4 — Set up Gmail API credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com)
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!

```bash
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:

```bash
python3 gmail_cleanup_agent_v2.py
```

### CLI Mode (for power users)

```bash
# 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](https://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](https://developers.google.com/gmail/api) and Python.
