gmail-cleaner

批量清理和整理 Gmail 帐户。当要求清理 Gmail、删除垃圾邮件、垃圾通讯/促销电子邮件、按发件人批量删除电子邮件、创建标签、设置自动过滤器或从垃圾箱恢复电子邮件时使用。通过 OAuth 令牌文件处理单个或多个 Gmail 帐户。可与任何使用 Gmail API 的 Gmail 帐户配合使用。

# 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-in label set (Business, Banking, Tech, Personal, Trading, Social):
python scripts/organize.py

# Custom labels/rules/filters from JSON:
python scripts/organize.py --config labels.json

# Labels only (no filters):
python scripts/organize.py --skip-filters
```

### 6. Restore (rescue emails from trash)

```bash
# Restore all emails from a sender + apply a label:
python scripts/restore.py --from healthbeat@mail.health.harvard.edu --label "Harvard Health"

# Restore by query:
python scripts/restore.py --query "from:apple.com in:trash" --label "Tech/Apple"
```

## Multiple Accounts

Run each script with a different `--token` path per account:

```bash
python scripts/scan.py    --token ~/.openclaw/workspace/gmail_token_personal.pkl
python scripts/scan.py    --token ~/.openclaw/workspace/gmail_token_work.pkl
python scripts/deep_clean.py --token ~/.openclaw/workspace/gmail_token_work.pkl
```

## Common Patterns

**Full cleanup for one account:**
```bash
python scripts/auth.py --scopes settings
python scripts/scan.py                         # identify top senders
python scripts/clean.py --from "..."          # trash specific senders
python scripts/deep_clean.py                   # clean categories
python scripts/organize.py                     # create labels + filters
```

**Rescue important emails caught in bulk delete:**
```bash
python scripts/restore.py --from important@example.com --label "Important"
```

**Senders config file format** for `clean.py --config`:
```json
[
  {"query": "from:temu@eu.temuemail.com", "label": "Temu"},
  {"query": "category:promotions older_than:7d", "label": "Old Promos"}
]
```

## Notes

- `batchModify` moves to TRASH — Gmail auto-purges after 30 days
- `batchDelete` is permanent and irreversible — always dry-run first
- Gmail filter creation requires `gmail.settings.basic` scope — re-auth with `--scopes settings` if filters fail with 403
- `scan.py` samples N messages; large inboxes may need `--sample 2000` for accuracy
- Credentials JSON comes from Google Cloud Console → APIs & Services → Credentials → OAuth 2.0 → Desktop → Download JSON

---

## 中文说明

# Gmail Cleaner

使用 Gmail API 批量清理 Gmail。每次 API 调用处理 1000 封邮件。

## 前置条件

- `google-api-python-client`、`google-auth-oauthlib` Python 包（脚本会在缺失时自动安装）
- 来自 Google Cloud Console 的 OAuth 凭据 JSON（Desktop app 类型）
- 每个帐户的令牌文件以 `.pkl` 文件形式存储

## 工作流程

### 1. 认证（首次或新增帐户）

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

- `basic` 权限范围：读取/修改/删除邮件 + 标签
- `settings` 权限范围：增加 `gmail.settings.basic`（创建过滤器所必需）
- 默认令牌路径：`~/.openclaw/workspace/gmail_token.pkl`
- 默认凭据路径：`~/.openclaw/workspace/gmail_credentials.json`

对于第二个帐户，请指定不同的 `--token` 路径（例如 `gmail_token_work.pkl`）。

### 2. 扫描（识别需要清理的内容）

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

按类别显示收件箱数量 + 前 40 名发件人。请先运行此命令。

### 3. 清理（批量移入垃圾箱/删除）

```bash
# 将特定发件人移入垃圾箱：
python scripts/clean.py --from "spam@example.com,news@example.org"

# 按 Gmail 搜索查询移入垃圾箱：
python scripts/clean.py --query "category:promotions older_than:30d"

# 从 JSON 配置文件读取（{query, label} 列表）：
python scripts/clean.py --config senders.json

# 永久删除而非移入垃圾箱：
python scripts/clean.py --from "spam@example.com" --delete

# 先做试运行：
python scripts/clean.py --from "spam@example.com" --dry-run
```

### 4. 深度清理（全面）

```bash
# 完整深度清理（4 步：促销邮件移入垃圾箱 → 归档旧邮件 → 标为已读 → 清空垃圾箱）：
python scripts/deep_clean.py

# 自定义时间阈值：
python scripts/deep_clean.py --promo-days 7 --archive-days 30 --unread-days 14

# 跳过清空垃圾箱（保留垃圾箱以便 30 天后自动删除）：
python scripts/deep_clean.py --skip-trash-purge
```

### 5. 整理（标签 + 过滤器）

```bash
# 应用内置标签集（Business、Banking、Tech、Personal、Trading、Social）：
python scripts/organize.py

# 从 JSON 自定义标签/规则/过滤器：
python scripts/organize.py --config labels.json

# 仅标签（无过滤器）：
python scripts/organize.py --skip-filters
```

### 6. 恢复（从垃圾箱抢救邮件）

```bash
# 恢复某发件人的所有邮件 + 应用标签：
python scripts/restore.py --from healthbeat@mail.health.harvard.edu --label "Harvard Health"

# 按查询恢复：
python scripts/restore.py --query "from:apple.com in:trash" --label "Tech/Apple"
```

## 多个帐户

为每个帐户使用不同的 `--token` 路径运行每个脚本：

```bash
python scripts/scan.py    --token ~/.openclaw/workspace/gmail_token_personal.pkl
python scripts/scan.py    --token ~/.openclaw/workspace/gmail_token_work.pkl
python scripts/deep_clean.py --token ~/.openclaw/workspace/gmail_token_work.pkl
```

## 常见模式

**对单个帐户进行完整清理：**
```bash
python scripts/auth.py --scopes settings
python scripts/scan.py                         # 识别主要发件人
python scripts/clean.py --from "..."          # 将特定发件人移入垃圾箱
python scripts/deep_clean.py                   # 清理类别
python scripts/organize.py                     # 创建标签 + 过滤器
```

**抢救批量删除中误删的重要邮件：**
```bash
python scripts/restore.py --from important@example.com --label "Important"
```

`clean.py --config` 使用的**发件人配置文件格式：**
```json
[
  {"query": "from:temu@eu.temuemail.com", "label": "Temu"},
  {"query": "category:promotions older_than:7d", "label": "Old Promos"}
]
```

## 注意事项

- `batchModify` 将邮件移入 TRASH（垃圾箱）——Gmail 在 30 天后自动清除
- `batchDelete` 为永久且不可逆操作——请务必先做试运行
- 创建 Gmail 过滤器需要 `gmail.settings.basic` 权限范围——如果过滤器以 403 失败，请使用 `--scopes settings` 重新认证
- `scan.py` 采样 N 封邮件；大型收件箱可能需要 `--sample 2000` 以提高准确性
- 凭据 JSON 来自 Google Cloud Console → APIs & Services → Credentials → OAuth 2.0 → Desktop → Download JSON