gmail-cleaner

# Gmail Cleaner

Bulk Gmail cleanup using the Gmail API. Processes 1000 messages per API call.

## Prerequisites

- `google-api-python-client`, `google-auth-oauthlib` Python packages (scripts auto-install if missing)
- OAuth credentials JSON from Google Cloud Console (Desktop app type)
- Token files stored as `.pkl` files per account

## Workflow

### 1. Auth (first time or new account)

```bash
python scripts/auth.py --credentials /path/to/credentials.json --token /path/to/token.pkl --scopes settings
```

- `basic` scopes: read/modify/delete messages + labels  
- `settings` scopes: adds `gmail.settings.basic` (required for creating filters)  
- Default token path: `~/.openclaw/workspace/gmail_token.pkl`
- Default creds path: `~/.openclaw/workspace/gmail_credentials.json`

For a second account, specify a different `--token` path (e.g., `gmail_token_work.pkl`).

### 2. Scan (identify what to clean)

```bash
python scripts/scan.py --token /path/to/token.pkl --sample 500
```

Shows inbox counts by category + top 40 senders. Run this first.

### 3. Clean (bulk trash/delete)

```bash
# Trash specific senders:
python scripts/clean.py --from "spam@example.com,news@example.org"

# Trash by Gmail search query:
python scripts/clean.py --query "category:promotions older_than:30d"

# From a JSON config file (list of {query, label}):
python scripts/clean.py --config senders.json

# Permanently delete instead of trash:
python scripts/clean.py --from "spam@example.com" --delete

# Dry run first:
python scripts/clean.py --from "spam@example.com" --dry-run
```

### 4. Deep Clean (comprehensive)

```bash
# Full deep clean (4 steps: trash promos → archive old → mark read → purge trash):
python scripts/deep_clean.py

# Custom age thresholds:
python scripts/deep_clean.py --promo-days 7 --archive-days 30 --unread-days 14

# Skip trash purge (keep trash for 30-day auto-delete):
python scripts/deep_clean.py --skip-trash-purge
```

### 5. Organize (labels + filters)

```bash
# Apply built-i...