eMail manager lite

# Email Manager Lite v0.2

一个用于 OpenClaw 的完全独立的电子邮件管理技能。使用标准的 IMAP 和 SMTP 协议，无任何外部依赖。

## ✨ v0.2 新功能

### 🔍 高级搜索与筛选 - 按发件人搜索 (`--from`) - 按主题关键词搜索 (`--subject`) - 按日期范围筛选 (`--since`, `--before`) - 按已读/未读状态筛选 (`--seen`, `--unseen`) - 在邮件正文中搜索 (`--body`，警告：可能较慢)

### 📁 文件夹管理 - 使用 `folders` 命令列出所有 IMAP 文件夹 - 使用 `move` 命令在文件夹之间移动邮件 - 自动验证文件夹是否存在

### 📎 附件信息 - 自动检测附件 - 显示附件详细信息： - 文件名 - MIME 类型 - 文件大小（格式化的 KB/MB） - 显示在 `read` 和 `search` 结果中

## 🔧 安装

```bash cd skills/portable-email-manager npm install ```

依赖项已包含在 `package.json` 中： - `nodemailer` - SMTP 邮件发送 - `imap-simple` - IMAP 操作 - `mailparser` - 邮件解析和附件检测

## 🔐 凭证

设置以下环境变量：

```bash export EMAIL_USER="[email protected]" export EMAIL_PASS="your-app-password" ```

**建议：** 对于 Gmail、Outlook、Zoho，请使用应用专用密码 而不是主密码。

### 提供商设置

**Zoho Mail（默认）：** - 已配置为使用 `smtp.zoho.eu` 和 `imap.zoho.eu` - 生成应用专用密码：https://accounts.zoho.eu/home#security/apppasswords

**Gmail：** - 编辑 `scripts/email.js` 并更改： ```javascript host: 'smtp.gmail.com' // SMTP host: 'imap.gmail.com' // IMAP ``` - 启用两步验证 并创建应用专用密码：https://myaccount.google.com/apppasswords

**Outlook/Hotmail：** - 编辑以使用 `smtp.office365.com` / `outlook.office365.com` - SMTP 端口 587 (TLS)

## 📖 用法

### 发送邮件

```bash ./scripts/email.js send "[email protected]" "Subject" "Email body text" ```

**示例：** ```bash ./scripts/email.js send "[email protected]" "Weekly Report" "Attached is this week's summary." ```

### 阅读最近的邮件

```bash ./scripts/email.js read [limit] ```

**示例：** ```bash # Read last 5 emails (default) ./scripts/email.js read

# Read last 20 emails ./scripts/email.js read 20 ```

**输出包括：** - UID（用于移动的唯一 ID） - 发件人/收件人地址 - 主题和日期 - 附件计数和详细信息 - 邮件正文预览（前 500 个字符）

### 高级搜索

```bash ./scripts/email.js search [options] ```

**搜索选项：**

| 选项 | 描述 | 示例 | |--------|-------------|---------| | `--from <email>` | 按发件人筛选 | `--from "[email protected]"` | | `--subject <text>` | 按主题关键词筛选 | `--subject "invoice"` | | `--since <date>` | 该日期之后的邮件 | `--since "Jan 1, 2026"` | | `--before <date>` | 该日期之前的邮件 | `--before "Feb 1, 2026"` | | `--unseen` | 仅未读邮件 | `--unseen` | | `--seen` | 仅已读邮件 | `--seen` | | `--body <text>` | 在正文中搜索（慢！） | `--body "meeting"` | | `--limit <n>` | 最大结果数 | `--limit 10` |

**示例：**

```bash # Find unread emails from specific sender ./scripts/email.js search --from "[email protected]" --unseen

# Search by subject ./scripts/email.js search --subject "invoice" --limit 5

# Date range search ./scripts/email.js search --since "Jan 15, 2026" --before "Feb 1, 2026"

# Search in body (use sparingly - can be slow) ./scripts/email.js search --body "quarterly review"

# Combine multiple filters ./scripts/email.js search --from "[email protected]" --subject "urgent" --unseen --limit 3 ```

### 列出文件夹

```bash ./scripts/email.js folders ```

显示所有 IMAP 文件夹的分层树及其属性。

**示例输出：** ``` 📁 INBOX 📁 Sent 📁 Archive 📁 Drafts 📁 Spam 📁 Trash ```

### 将邮件移动到文件夹

```bash ./scripts/email.js move <uid> <folder-name> ```

**重要：** - 从 `read` 或 `search` 输出中获取 `uid` - 文件夹名称区分大小写 - 脚本会在移动前验证文件夹是否存在

**示例：**

```bash # First, find the email and note its UID ./scripts/email.js search --from "[email protected]" # Output shows: UID: 12345

# Move to Archive folder ./scripts/email.js move 12345 "Archive"

# Move to custom folder ./scripts/email.js move 67890 "Projects/Work" ```

**错误处理：** - 如果文件夹不存在，则显示可用文件夹列表 - 在尝试移动之前验证 UID 是否存在

### 帮助

```bash ./scripts/email.js help ```

显示包含所有命令和示例的完整使用指南。

## 🎯 使用案例

### 每日邮件分类 ```bash # Check unread emails ./scripts/email.js search --unseen --limit 10

# Move newsletters to folder ./scripts/email.js search --from "[email protected]" --limit 1 ./scripts/email.js move <uid> "Newsletters" ```

### 查找特定邮件 ```bash # Search by sender and subject ./scripts/email.js search --from "[email protected]" --subject "proposal"

# Search by date ./scripts/email.js search --since "Jan 20, 2026" --subject "meeting notes" ```

### 归档旧邮件 ```bash # Find old read emails ./scripts/email.js search --before "Dec 1, 2025" --seen --limit 50

# Move each to Archive (use UID from output) ./scripts/email.js move <uid> "Archive" ```

### 检查附件 ```bash # Read recent emails and see attachment info ./scripts/email.js read 10

# Search output automatically shows: # - Number of attachments # - Filename, type, and size for each ```

## 🔒 安全

- 凭证永远不会被记录或存储在文件中 - 所有连接均使用 TLS/SSL 加密 - 建议使用应用专用密码代替账户密码 - 除 IMAP/SMTP 连接外，没有任何数据离开您的机器

## ⚙️ 配置

默认配置已针对 **Zoho Mail EU** 进行了优化。

要使用其他提供商，请编辑 `scripts/email.js`：

```javascript // SMTP Configuration const smtpConfig = { host: 'smtp.your-provider.com', port: 465, // or 587 for TLS secure: true, // true for SSL (465), false for TLS (587) auth: { user: EMAIL_USER, pass: EMAIL_PASS } };

// IMAP Configuration const imapConfig = { imap: { user: EMAIL_USER, password: EMAIL_PASS, host: 'imap.your-provider.com', port: 993, tls: true, authTimeout: 20000 } }; ```

## 🚀 性能说明

- **正文搜索** (`--body`) 在大型邮箱上可能会很慢 - 请谨慎使用 - **主题/发件人搜索** 速度很快 - 使用 IMAP 服务器端筛选 - **日期筛选** 效率很高 - 使用 `--limit` 限制结果以加快响应速度

## 🐛 故障排除

**“Authentication failed”（认证失败）** - 验证 EMAIL_USER 和 EMAIL_PASS 设置正确 - 使用应用专用密码，而不是账户密码 - 检查提供商设置（2FA、安全性较低的应用等）

**“Folder not found”（未找到文件夹）** - 使用 `folders` 命令查看确切的文件夹名称 - 文件夹名称区分大小写 - 某些提供商使用不同的名称（例如，“Sent Items”与“Sent”）

**“Connection timeout”（连接超时）** - 检查防火墙/网络设置 - 验证 IMAP/SMTP 端口是否可访问 - 尝试在配置中增加 `authTimeout`

**“No emails found”（未找到邮件）** - 检查搜索条件 - 验证收件箱中是否存在邮件（而不是其他文件夹） - 尝试更广泛的搜索（移除某些筛选器）

## 📝 版本历史

### v0.2.0（当前版本） - ✨ 带有多种筛选器的高级搜索 - 📁 文件夹管理（列表、移动） - 📎 附件检测和信息 - 🎨 改进的输出格式 - 📚 全面的文档

### v0.1.0 - 基本的发送/阅读功能 - Zoho Mail 支持 - IMAP/SMTP 基础

## 🤝 兼容性

已测试： - ✅ Zoho Mail (欧盟与美国) - ✅ Gmail - ✅ Outlook/Hotmail - ✅ iCloud Mail - ✅ 自定义 IMAP/SMTP 服务器

## 💡 提示

1. **使用 UID 进行自动化：** 保存搜索结果中的 UID 以通过编程方式移动邮件 2. **组合筛选器：** 多个筛选器会创建 AND 条件以进行精确搜索 3. **文件夹组织：** 先列出文件夹以规划您的组织策略 4. **日期格式：** 使用自然语言日期，如“Jan 1, 2026”或“December 25, 2025” 5. **附件筛选：** 在搜索输出中查找“Attachments: X”以查找包含文件的邮件

## 📄 许可证

ISC - 可在您的 OpenClaw 设置中自由使用。