gmail-inbox-zero

Gmail 收件箱零分类 - 使用 gog CLI 和 Telegram 按钮进行交互式收件箱管理。当用户想要实现收件箱清零、以交互方式分类 Gmail 收件箱、使用 AI 摘要和批处理操作（存档、过滤、取消订阅）处理所有收件箱邮件（已读和未读）时使用。基于 OAuth，无需密码。

# Gmail Inbox Zero Triage

Achieve inbox zero with AI-powered email triage! Process ALL Gmail inbox messages interactively with summaries and batch actions using OAuth (no passwords needed).

## Features

✅ **OAuth-based** - No passwords, secure authentication via gog  
✅ **AI summaries** - Quick 1-line summary of each email  
✅ **Batch processing** - Queue actions instantly, execute at the end  
✅ **Telegram buttons** - Archive, Filter, Unsubscribe, View  
✅ **Inbox zero focus** - Process ALL inbox messages (read + unread)  
✅ **Fast workflow** - No waiting between actions

## Workflow

1. **User triggers:** "Triage my emails" or "Process my inbox"
2. **Fetch ALL inbox messages** from Gmail (up to 20 at a time)
3. **Display all emails at once** with:
   - Subject and sender
   - AI-generated summary (1 line)
   - Telegram inline buttons for actions
4. **User clicks actions** for each email (queued instantly, no API calls yet)
5. **User clicks "Done"** button to execute all queued actions in batch
6. **Repeat until inbox zero!** 🎯

## Prerequisites

**Requires:** `gog` CLI with authenticated Gmail account.

Check if already set up:
```bash
gog auth list
```

If not set up, user needs to run `gog auth add` (see gog skill for OAuth setup).

Set environment variable for keyring password:
```bash
export GOG_KEYRING_PASSWORD="your-password"
```

## Telegram Button Layout

Each email displays with 4 action buttons:

```
[📥 Archive] [🔍 Filter]
[🚫 Unsub]   [📧 View]
```

- **📥 Archive** - Remove from inbox, mark as read
- **🔍 Filter** - Create filter to auto-archive future emails from sender
- **🚫 Unsubscribe** - Find and open unsubscribe link
- **📧 View** - Show full email content
- **No click** = Skip (leave in inbox)

At the end:
```
[✅ Done - Execute All Actions]
```

## Action Queue System

Actions are queued using short callback codes to avoid Telegram's 64-char limit:

- `q:a:0` = queue archive, message index 0
- `q:f:0` = queue filter, message index 0  
- `q:u:0` = queue unsubscribe, message index 0
- `q:v:0` = view full email, message index 0 (executes immediately)
- `q:done` = execute all queued actions

Queue is managed via `scripts/queue_manager.py` and stored in `action_queue.json`.

## Scripts

### gog_processor.py

Main processor for Gmail operations via gog CLI.

**List inbox messages:**
```bash
python3 scripts/gog_processor.py list <account> [limit]
```

**Archive a message:**
```bash
python3 scripts/gog_processor.py archive <account> <msg_id>
```

**Find unsubscribe link:**
```bash
python3 scripts/gog_processor.py unsubscribe <account> <msg_id>
```

**Create filter:**
```bash
python3 scripts/gog_processor.py filter <account> "<from_header>"
```

**Get message body:**
```bash
python3 scripts/gog_processor.py body <account> <msg_id>
```

### queue_manager.py

Manages action queue for batch execution.

**Add action to queue:**
```bash
python3 scripts/queue_manager.py add <action> <msg_id> [from_header]
```

**Get queue:**
```bash
python3 scripts/queue_manager.py get
```

**Clear queue:**
```bash
python3 scripts/queue_manager.py clear
```

### execute_queue.py

Executes all queued actions in batch.

```bash
python3 scripts/execute_queue.py <account>
```

Returns JSON with results of all executed actions.

## Implementation Steps

1. **Load current batch:** Fetch inbox messages and save to `current_batch.json`
2. **Display all emails:** Show each with summary and buttons
3. **Handle button callbacks:**
   - Archive/Filter/Unsub: Add to queue via `queue_manager.py`
   - View: Fetch and display full email immediately
   - Done: Execute queue via `execute_queue.py`
4. **Show results:** Report archived count and remaining inbox count
5. **Repeat if needed:** Fetch next batch or celebrate inbox zero

## AI Summary Guidelines

Generate concise 1-line summaries:

- **Receipts/Invoices:** "Payment receipt for $X. Financial record."
- **Security alerts:** "Security notification about [action]. [Important/Standard] alert."
- **Newsletters:** "Newsletter about [topic]. No action required."
- **Calendar:** "Calendar [event type] for [date/time]."
- **Legal:** "Legal [document type]. [Brief context]."

Keep it simple, factual, and action-oriented.

## Security Notes

- **OAuth-based authentication** - No passwords needed, uses gog's OAuth tokens
- **Tokens stored securely** by gog CLI in system keychain
- **Read/modify permissions** - gog only gets access to what user grants
- **Queue stored locally** - Action queue is temporary, cleared after execution

## Error Handling

Common issues:
- **gog not authenticated:** Run `gog auth add <account>`
- **Account not found:** Check `gog auth list` for available accounts
- **No inbox messages:** Success state - inbox zero achieved!
- **Permission denied:** User may need to re-authenticate with gog
- **Keyring password:** Set `GOG_KEYRING_PASSWORD` environment variable

## Dependencies

- **gog CLI** - Must be installed and authenticated (see gog skill)
- **Python 3** - Standard library only (subprocess, json, re, pathlib)

No additional pip packages needed.

## Tips for Best Experience

- **Process regularly:** Triage inbox daily to maintain inbox zero
- **Use filters liberally:** Auto-archive recurring newsletters and notifications
- **Archive aggressively:** If you don't need it now, archive it (searchable in All Mail)
- **Batch mode is fast:** Process 10-20 emails in under a minute
- **Trust the summaries:** AI summaries are accurate for quick decisions

---

## 中文说明

# Gmail 收件箱零分类

借助 AI 驱动的邮件分类实现收件箱清零！使用 OAuth（无需密码）以交互方式处理所有 Gmail 收件箱邮件，附带摘要和批处理操作。

## 功能特性

✅ **基于 OAuth** - 无需密码，通过 gog 进行安全认证  
✅ **AI 摘要** - 为每封邮件生成快速的一行摘要  
✅ **批处理** - 即时将操作加入队列，最后统一执行  
✅ **Telegram 按钮** - 存档、过滤、取消订阅、查看  
✅ **专注收件箱清零** - 处理所有收件箱邮件（已读 + 未读）  
✅ **快速工作流** - 操作之间无需等待

## 工作流程

1. **用户触发：** "Triage my emails" 或 "Process my inbox"
2. **从 Gmail 拉取所有收件箱邮件**（每次最多 20 封）
3. **一次性展示所有邮件**，包括：
   - 主题和发件人
   - AI 生成的摘要（一行）
   - 用于操作的 Telegram 内联按钮
4. **用户为每封邮件点击操作**（即时入队，尚未发起 API 调用）
5. **用户点击 "Done" 按钮**以批量执行所有已入队的操作
6. **重复直到收件箱清零！** 🎯

## 前置条件

**需要：** 已通过认证的 Gmail 账户的 `gog` CLI。

检查是否已设置：
```bash
gog auth list
```

若未设置，用户需运行 `gog auth add`（OAuth 设置参见 gog 技能）。

设置密钥环密码的环境变量：
```bash
export GOG_KEYRING_PASSWORD="your-password"
```

## Telegram 按钮布局

每封邮件展示 4 个操作按钮：

```
[📥 Archive] [🔍 Filter]
[🚫 Unsub]   [📧 View]
```

- **📥 Archive** - 移出收件箱，标记为已读
- **🔍 Filter** - 创建过滤器以自动存档来自该发件人的后续邮件
- **🚫 Unsubscribe** - 查找并打开取消订阅链接
- **📧 View** - 显示完整邮件内容
- **不点击** = 跳过（保留在收件箱中）

最后：
```
[✅ Done - Execute All Actions]
```

## 操作队列系统

操作使用简短的回调代码入队，以避免 Telegram 的 64 字符限制：

- `q:a:0` = 入队存档，邮件索引 0
- `q:f:0` = 入队过滤，邮件索引 0  
- `q:u:0` = 入队取消订阅，邮件索引 0
- `q:v:0` = 查看完整邮件，邮件索引 0（立即执行）
- `q:done` = 执行所有已入队操作

队列通过 `scripts/queue_manager.py` 管理，并存储在 `action_queue.json` 中。

## 脚本

### gog_processor.py

通过 gog CLI 执行 Gmail 操作的主处理器。

**列出收件箱邮件：**
```bash
python3 scripts/gog_processor.py list <account> [limit]
```

**存档邮件：**
```bash
python3 scripts/gog_processor.py archive <account> <msg_id>
```

**查找取消订阅链接：**
```bash
python3 scripts/gog_processor.py unsubscribe <account> <msg_id>
```

**创建过滤器：**
```bash
python3 scripts/gog_processor.py filter <account> "<from_header>"
```

**获取邮件正文：**
```bash
python3 scripts/gog_processor.py body <account> <msg_id>
```

### queue_manager.py

管理用于批量执行的操作队列。

**将操作加入队列：**
```bash
python3 scripts/queue_manager.py add <action> <msg_id> [from_header]
```

**获取队列：**
```bash
python3 scripts/queue_manager.py get
```

**清空队列：**
```bash
python3 scripts/queue_manager.py clear
```

### execute_queue.py

批量执行所有已入队的操作。

```bash
python3 scripts/execute_queue.py <account>
```

返回包含所有已执行操作结果的 JSON。

## 实现步骤

1. **加载当前批次：** 拉取收件箱邮件并保存到 `current_batch.json`
2. **展示所有邮件：** 展示每封邮件的摘要和按钮
3. **处理按钮回调：**
   - 存档/过滤/取消订阅：通过 `queue_manager.py` 加入队列
   - 查看：立即拉取并展示完整邮件
   - 完成：通过 `execute_queue.py` 执行队列
4. **展示结果：** 报告已存档数量和剩余收件箱数量
5. **如需则重复：** 拉取下一批次或庆祝收件箱清零

## AI 摘要准则

生成简洁的一行摘要：

- **收据/发票：** "Payment receipt for $X. Financial