Zoho Email Integration

# Zoho Email Integration

**v2.2.6** - 完整的 Zoho Mail 集成，支持 OAuth2 身份验证、REST API 后端（比 IMAP/SMTP 快 5-10 倍），以及 **Clawdbot 扩展，支持 Telegram/Discord 的 /email 命令**。针对路径遍历和命令注入进行了**安全加固**。支持 HTML 邮件、附件、批量操作和高级自动化工作流。

选择您的身份验证方式：OAuth2（推荐，安全）或应用专用密码（设置简单）。

## 🔄 更新到最新版本

```bash clawhub install zoho-email-integration --force ```

或更新所有技能： ```bash clawhub update ```

## 🔒 安全提示 (v2.2.5+)

**关键修复：** 移除了有漏洞的 JavaScript 命令处理器。如果您部署了 examples 文件夹中的 `email-command.js`，请立即更新：

```bash # Re-download the secure handler clawhub install zoho-email-integration --force cp ~/.openclaw/skills/zoho-email-integration/examples/clawdbot-extension/email-command.js /your/deployment/path/ ```

易受攻击的版本使用带有 shell 插值的 `execSync`。新版本使用带有参数数组的 `spawn` 来防止命令注入。

## ✨ 功能

### 🔐 身份验证与性能 - **OAuth2 身份验证** - 基于令牌的安全认证，支持自动刷新 - **REST API 后端** - 操作速度比 IMAP/SMTP 快 5-10 倍 - **优雅降级** - 如果 REST API 不可用，自动回退到 IMAP - **应用专用密码支持** - OAuth2 的简单替代方案

### 📧 邮件操作 - **📥 读取邮件** - 从任意文件夹（收件箱、已发送、草稿箱等）获取 - **🔍 智能搜索** - 按主题、发件人、关键词搜索，速度如 REST API - **📊 监控收件箱** - 用于通知的实时未读计数 - **📤 发送邮件** - 纯文本或 HTML，支持抄送/密送 - **🎨 HTML 邮件** - 包含专业模板的丰富格式 - **📎 附件** - 发送和下载文件附件

### ⚡ 批量与批量操作 - **批量操作** - 高效地标记、删除或移动多封邮件 - **批量操作** - 一次搜索并对数百封邮件执行操作 - **试运行模式** - 在执行前预览操作以确保安全

### 🔒 安全 - **无硬编码凭据** - 仅使用 OAuth2 令牌或环境变量 - **自动令牌刷新** - 无缝令牌续期 - **加密连接** - 所有操作均使用 SSL/TLS

## 📦 安装

```bash clawdhub install zoho-email ```

**要求：** - Python 3.x - `requests` 库（安装：`pip3 install requests`） - Zoho Mail 账户

## ⚙️ 设置

### 1. 获取应用专用密码

**重要：** 请勿使用您的 Zoho 主密码！

1. 登录 Zoho Mail 2. 转到 **Settings** → **Security** → **App Passwords** 3. 为 "Clawdbot" 或 "IMAP/SMTP Access" 生成新的应用专用密码 4. 复制该密码（下一步需要）

### 2. 配置凭据

**选项 A：环境变量**

导出您的 Zoho 凭据：

```bash export ZOHO_EMAIL="[email protected]" export ZOHO_PASSWORD="your-app-specific-password" ```

**选项 B：凭据文件**

创建 `~/.clawdbot/zoho-credentials.sh`：

```bash #!/bin/bash export ZOHO_EMAIL="[email protected]" export ZOHO_PASSWORD="your-app-specific-password" ```

使其可执行并安全： ```bash chmod 600 ~/.clawdbot/zoho-credentials.sh ```

然后在运行前获取它： ```bash source ~/.clawdbot/zoho-credentials.sh ```

### 3. 测试连接

```bash python3 scripts/zoho-email.py unread ```

预期输出： ```json {"unread_count": 5} ```

## 🚀 使用

所有命令都需要通过环境变量设置的凭据。

### 快速命令（常见任务）

```bash # Diagnose setup (recommended first step) python3 scripts/zoho-email.py doctor

# Unread count (great for briefings) python3 scripts/zoho-email.py unread

# Search inbox python3 scripts/zoho-email.py search "invoice"

# Get a specific email (folder + id) python3 scripts/zoho-email.py get INBOX <id>

# Send a simple email python3 scripts/zoho-email.py send [email protected] "Subject" "Body text"

# Empty Spam (safe by default: DRY RUN) python3 scripts/zoho-email.py empty-spam # Execute for real python3 scripts/zoho-email.py empty-spam --execute

# Empty Trash (safe by default: DRY RUN) python3 scripts/zoho-email.py empty-trash # Execute for real python3 scripts/zoho-email.py empty-trash --execute ```

### 发送 HTML 邮件

发送丰富、格式化的 HTML 邮件，支持 multipart/alternative（同时包含 HTML 和纯文本版本）：

**CLI 命令：** ```bash # Send HTML from a file python3 scripts/zoho-email.py send-html [email protected] "Newsletter" examples/templates/newsletter.html

# Send HTML from inline text python3 scripts/zoho-email.py send-html [email protected] "Welcome" "<h1>Hello!</h1><p>Welcome to our service.</p>"

# Preview HTML email before sending python3 scripts/zoho-email.py preview-html examples/templates/newsletter.html ```

**Python API：** ```python from scripts.zoho_email import ZohoEmail

zoho = ZohoEmail()

# Method 1: Send HTML with auto-generated plain text fallback zoho.send_html_email( to="[email protected]", subject="Newsletter", html_body="<h1>Hello!</h1><p>Welcome!</p>" )

# Method 2: Send HTML with custom plain text version zoho.send_email( to="[email protected]", subject="Newsletter", body="Plain text version of your email", html_body="<h1>Hello!</h1><p>HTML version of your email</p>" )

# Load HTML from template file with open('examples/templates/newsletter.html', 'r') as f: html_content = f.read()

zoho.send_html_email( to="[email protected]", subject="Monthly Newsletter", html_body=html_content ) ```

**功能：** - ✅ 多部分替代邮件（HTML + 纯文本） - ✅ 自动生成的纯文本回退 - ✅ 从文件或内联字符串加载 HTML - ✅ 发送前的预览模式以进行测试 - ✅ 完整的 CSS 样式支持 - ✅ 适用于所有邮件客户端

**模板：** `examples/templates/` 中提供现成模板： - `newsletter.html` - 专业简报布局 - `announcement.html` - 带有横幅的重要公告 - `welcome.html` - 入门欢迎邮件 - `simple.html` - 用于快速定制的基本 HTML 模板

### 检查未读数

```bash python3 scripts/zoho-email.py unread ```

非常适合晨间简报或通知系统。

### 搜索收件箱

```bash python3 scripts/zoho-email.py search "invoice" ```

返回最近 10 封匹配邮件，包含主题、发件人、日期和正文预览。

### 搜索已发送邮件

```bash python3 scripts/zoho-email.py search-sent "client name" ```

返回最近 5 封匹配的已发送邮件。

### 获取特定邮件

```bash python3 scripts/zoho-email.py get Inbox 4590 python3 scripts/zoho-email.py get Sent 1234 ```

返回完整邮件内容，包括完整正文。

### 发送邮件

```bash python3 scripts/zoho-email.py send "[email protected]" "Subject" "Email body here" ```

### 发送带附件的邮件

```bash python3 scripts/zoho-email.py send "[email protected]" "Invoice" "Please find the invoice attached" --attach invoice.pdf --attach receipt.jpg ```

支持使用 `--attach` 标志发送多个附件。

### 列出邮件附件

```bash python3 scripts/zoho-email.py list-attachments Inbox 4590 ```

返回包含附件详细信息的 JSON： ```json [ { "index": 0, "filename": "invoice.pdf", "content_type": "application/pdf", "size": 52341 }, { "index": 1, "filename": "receipt.jpg", "content_type": "image/jpeg", "size": 128973 } ] ```

### 下载附件

```bash # Download first attachment (index 0) with original filename python3 scripts/zoho-email.py download-attachment Inbox 4590 0

# Download second attachment (index 1) with custom filename python3 scripts/zoho-email.py download-attachment Inbox 4590 1 my-receipt.jpg ```

返回包含下载详细信息的 JSON： ```json { "filename": "invoice.pdf", "output_path": "invoice.pdf", "size": 52341, "content_type": "application/pdf" } ```

## 🤖 Clawdbot 集成示例

### 晨间简报

检查未读邮件并报告：

```bash UNREAD=$(python3 scripts/zoho-email.py unread | jq -r '.unread_count') echo "📧 You have $UNREAD unread emails" ```

### 邮件监控

监控 VIP 邮件：

```bash RESULTS=$(python3 scripts/zoho-email.py search "Important Client") COUNT=$(echo "$RESULTS" | jq '. | length')

if [ $COUNT -gt 0 ]; then echo "⚠️ New email from Important Client!" fi ```

### 自动回复

搜索和回复工作流：

```bash # Find latest invoice inquiry EMAIL=$(python3 scripts/zoho-email.py search "invoice" | jq -r '.[0]') FROM=$(echo "$EMAIL" | jq -r '.from')

# Send reply python3 scripts/zoho-email.py send "$FROM" "Re: Invoice" "Thanks for your inquiry..." ```

### 附件工作流

自动下载发票附件：

```bash # Search for invoice emails EMAILS=$(python3 scripts/zoho-email.py search "invoice")

# Get latest email ID EMAIL_ID=$(echo "$EMAILS" | jq -r '.[0].id')

# List attachments ATTACHMENTS=$(python3 scripts/zoho-email.py list-attachments Inbox "$EMAIL_ID")

# Download all PDF attachments echo "$ATTACHMENTS" | jq -r '.[] | select(.content_type == "application/pdf") | .index' | while read INDEX; do python3 scripts/zoho-email.py download-attachment Inbox "$EMAIL_ID" "$INDEX" "invoice_${INDEX}.pdf" echo "Downloaded invoice_${INDEX}.pdf" done ```

发送带附件的报告：

```bash # Generate report python3 generate_report.py > report.txt

# Send with attachment python3 scripts/zoho-email.py send "[email protected]" "Weekly Report" "Please see attached report" --attach report.txt --attach chart.png ```

## 📚 Python API

导入模块以进行编程使用：

```python from scripts.zoho_email import ZohoEmail

zoho = ZohoEmail()

# Search emails results = zoho.search_emails(folder="INBOX", query='SUBJECT "invoice"', limit=10)

# Get specific email email = zoho.get_email(folder="Sent", email_id="4590")

# Send plain text email zoho.send_email( to="[email protected]", subject="Hello", body="Message text", cc="[email protected]" # optional )

# Send HTML email (auto-generated plain text fallback) zoho.send_html_email( to="[email protected]", subject="Newsletter", html_body="<h1>Welcome!</h1><p>Rich HTML content here</p>", text_body="Welcome! Plain text version here" # optional, auto-generated if not provided )

# Send multipart email (HTML + custom plain text) zoho.send_email( to="[email protected]", subject="Update", body="Plain text version", html_body="<h1>HTML version</h1>", cc="[email protected]" )

# Send email with attachments zoho.send_email_with_attachment( to="[email protected]", subject="Invoice", body="Please find the invoice attached", attachments=["invoice.pdf", "receipt.jpg"], cc="[email protected]" # optional )

# List attachments attachments = zoho.get_attachments(folder="INBOX", email_id="4590") for att in attachments: print(f"{att['index']}: {att['filename']} ({att['size']} bytes)")

# Download attachment result = zoho.download_attachment( folder="INBOX", email_id="4590", attachment_index=0, output_path="downloaded_file.pdf" # optional, uses original filename if not provided )

# Check unread count count = zoho.get_unread_count() ```

## 📖 HTML 邮件示例

查看 `examples/send-html-newsletter.py` 中的完整示例：

```bash # Run the HTML email examples python3 examples/send-html-newsletter.py ```

这展示了： - 发送简单的内联 HTML - 加载并发送 HTML 模板 - 自定义纯文本回退 - 专业的邮件布局

**快速开始：** ```python #!/usr/bin/env python3 from scripts.zoho_email import ZohoEmail

zoho = ZohoEmail()

# Load a template with open('examples/templates/welcome.html', 'r') as f: html = f.read()

# Send to recipient zoho.send_html_email( to="[email protected]", subject="🎉 Welcome to Our Platform!", html_body=html ) ```

## 📁 文件夹参考

常见的 Zoho Mail 文件夹：

- `INBOX` - 主收件箱 - `Sent` - 已发送邮件 - `Drafts` - 草稿邮件 - `Spam` - 垃圾邮件文件夹 - `Trash` - 已删除邮件 - 自定义文件夹（例如 `INBOX/ClientName`）

## 🔧 高级配置

覆盖默认的 IMAP/SMTP 服务器（如果使用自托管的 Zoho Mail）：

```bash export ZOHO_IMAP="imap.yourdomain.com" export ZOHO_SMTP="smtp.yourdomain.com" export ZOHO_IMAP_PORT="993" export ZOHO_SMTP_PORT="465" ```

## ❓ 故障排除

### 身份验证失败

- 确保在 Zoho Mail 设置中启用了 IMAP - 使用**应用专用密码**，而不是您的主密码 - 验证凭据是否正确导出

### 连接超时

- 检查防火墙是否允许端口 993 (IMAP) 和 465 (SMTP) - 验证 Zoho Mail 服务器状态 - 尝试使用不同的网络（企业防火墙可能会阻止 IMAP）

### 搜索无结果

- IMAP 搜索不区分大小写 - 尝试使用更广泛的关键词 - 验证文件夹名称正确（区分大小写）

### "ZOHO_EMAIL and ZOHO_PASSWORD must be set"

您忘记导出凭据了！请运行：

```bash export ZOHO_EMAIL="[email protected]" export ZOHO_PASSWORD="your-app-password" ```

## 🛣️ 路线图

### ✅ 已完成 (v2.0.0)

- [x] **OAuth2 身份验证** - 基于令牌的安全认证，支持自动刷新 - [x] **Zoho Mail REST API** - 比 IMAP/SMTP 快 5-10 倍 - [x] **附件支持** - 下载和发送附件 - [x] **HTML 邮件撰写** - 包含模板的丰富格式 - [x] **批量操作** - 标记、删除、移动多封邮件 - [x] **批量操作** - 一次搜索并对多封邮件执行操作

### 🔮 未来增强

- [ ] **邮件线程/会话** - 将相关邮件分组 - [ ] **标签管理** - 创建和管理 Zoho Mail 标签 - [ ] **草稿邮件管理** - 创建、编辑和发送草稿 - [ ] **定时发送** - 安排稍后发送邮件 - [ ] **邮件模板** - 带有变量的可重用邮件模板 - [ ] **Webhooks** - 新邮件的实时通知 - [ ] **高级搜索** - 按大小、是否有附件、日期范围过滤 - [ ] **Zoho 日历集成** - 从邮件创建事件 - [ ] **Zoho CRM 集成** - 同步联系人和活动

## 📝 注意事项

- **搜索限制：** 默认返回最近 5-10 封邮件（可在代码中配置） - **正文截断：** 搜索结果显示前 500 个字符 - **编码：** 处理 UTF-8 和各种邮件编码 - **安全性：** 凭据除了发送到 Zoho 服务器外，绝不会离开您的系统

## 🤝 贡献

发现错误或想要贡献？请在 GitHub 上提交问题或 PR！

## 📄 许可证

MIT 许可证 - 可自由使用、修改和分发。

---

**创建时间：** 2026-01-29 **状态：** 生产就绪 ✅ **要求：** Python 3.x。对于 REST API 模式：`pip install -r requirements.txt`（包含 `requests`）。

## 🔄 批量操作

v1.1 中的新功能！使用批量命令高效处理多封邮件。

### 将多封邮件标记为已读

```bash python3 scripts/zoho-email.py mark-read INBOX 1001 1002 1003 ```

在一个命令中将几封邮件标记为已读。非常适合清除通知。

### 将多封邮件标记为未读

```bash python3 scripts/zoho-email.py mark-unread INBOX 1004 1005 ```

标记重要邮件以便稍后查看。

### 删除多封邮件

```bash python3 scripts/zoho-email.py delete INBOX 2001 2002 2003 ```

**安全：** 删除前会要求确认。邮件将被移至废纸篓（而非永久删除）。

### 在文件夹之间移动邮件

```bash python3 scripts/zoho-email.py move INBOX "Archive/2024" 3001 3002 3003 ```

通过将邮件移动到自定义文件夹来整理邮件。

### 使用搜索进行批量操作

对匹配搜索查询的所有邮件执行操作：

```bash # Dry run first - see what would be affected python3 scripts/zoho-email.py bulk-action \ --folder INBOX \ --search 'SUBJECT "newsletter"' \ --action mark-read \ --dry-run

# Execute the action python3 scripts/zoho-email.py bulk-action \ --folder INBOX \ --search 'SUBJECT "newsletter"' \ --action mark-read ```

**可用操作：** - `mark-read` - 将所有匹配邮件标记为已读 - `mark-unread` - 将所有匹配邮件标记为未读 - `delete` - 将所有匹配邮件移至废纸篓

**搜索查询示例：** ```bash # By subject --search 'SUBJECT "invoice"'

# By sender --search 'FROM "[email protected]"'

# Unread emails --search 'UNSEEN'

# Combine criteria (AND) --search '(SUBJECT "urgent" FROM "[email protected]")'

# Date range --search 'SINCE 01-Jan-2024' ```

### Python 中的批量操作

```python from scripts.zoho_email import ZohoEmail

zoho = ZohoEmail()

# Mark multiple emails as read result = zoho.mark_as_read(['1001', '1002', '1003'], folder="INBOX") print(f"Success: {len(result['success'])}, Failed: {len(result['failed'])}")

# Delete multiple emails result = zoho.delete_emails(['2001', '2002'], folder="INBOX")

# Move emails to another folder result = zoho.move_emails( email_ids=['3001', '3002'], target_folder="Archive/2024", source_folder="INBOX" )

# Bulk action with search result = zoho.bulk_action( query='SUBJECT "newsletter"', action='mark-read', folder="INBOX", dry_run=True # Preview first )

print(f"Found {result['total_found']} emails") print(f"Will process {result['to_process']} emails")

# Execute for real result = zoho.bulk_action( query='SUBJECT "newsletter"', action='mark-read', folder="INBOX", dry_run=False ) ```

### 批量清理示例

自动清理旧简报：

```bash # 1. Preview what will be deleted python3 scripts/zoho-email.py bulk-action \ --folder INBOX \ --search 'SUBJECT "newsletter"' \ --action delete \ --dry-run

# 2. Review the preview output

# 3. Execute if satisfied python3 scripts/zoho-email.py bulk-action \ --folder INBOX \ --search 'SUBJECT "newsletter"' \ --action delete ```

请参阅 `examples/batch-cleanup.py` 获取完整的自动清理脚本。