IMAP/SMTP 邮件工具

通过 IMAP 协议读取、搜索和管理邮件；通过 SMTP 协议发送邮件。支持 Gmail、Outlook、163.com 以及任意标准 IMAP/SMTP 服务器。

配置

在技能目录下创建 .env 文件，或直接设置环境变量：

# IMAP 配置（接收邮件）
IMAP_HOST=imap.gmail.com          # 服务器主机名
IMAP_PORT=993                     # 服务器端口
IMAP_USER=your@email.com
IMAP_PASS=your_password
IMAP_TLS=true                     # 启用 TLS/SSL 连接
IMAP_REJECT_UNAUTHORIZED=true     # 自签名证书时设为 false
IMAP_MAILBOX=INBOX                # 默认邮箱

# SMTP 配置（发送邮件）
SMTP_HOST=smtp.gmail.com          # SMTP 服务器主机名
SMTP_PORT=587                     # SMTP 端口（587 用于 STARTTLS，465 用于 SSL）
SMTP_SECURE=false                 # true 表示使用 SSL（端口 465），false 表示使用 STARTTLS（端口 587）
SMTP_USER=your@gmail.com          # 您的邮箱地址
SMTP_PASS=your_password           # 密码或应用专用密码
SMTP_FROM=your@gmail.com          # 默认发件人邮箱（可选）
SMTP_REJECT_UNAUTHORIZED=true     # 自签名证书时设为 false

常用邮件服务商配置

Gmail 注意事项：

• Gmail 不接受您的常规账户密码
• 您必须生成一个 App Password（应用专用密码）：https://myaccount.google.com/apppasswords
• 将生成的 16 位 App Password 用作 IMAP_PASS / SMTP_PASS
• 需启用 Google 账户的两步验证功能

163.com 注意事项：

• 请使用 授权码（非账户密码）
• 需先在网页版设置中启用 IMAP/SMTP 功能

IMAP 命令（接收邮件）

check

检查新邮件或未读邮件。

node scripts/imap.js check [--limit 10] [--mailbox INBOX] [--recent 2h]

选项说明：

• --limit ：最多返回结果数（默认：10）
• --mailbox ：指定邮箱（默认：INBOX）
• --recent ：仅显示最近 X 时间内的邮件（例如：30m、2h、7d）

fetch

根据 UID 获取完整邮件内容。

node scripts/imap.js fetch  [--mailbox INBOX]

download

下载某封邮件的所有附件，或指定某个附件。

node scripts/imap.js download  [--mailbox INBOX] [--dir ] [--file ]

选项说明：

• --mailbox ：指定邮箱（默认：INBOX）
• --dir ：输出目录（默认：当前目录）
• --file ：仅下载指定名称的附件（默认：下载全部附件）

search

按条件搜索邮件。

node scripts/imap.js search [options]

选项：
  --unseen           仅匹配未读邮件
  --seen             仅匹配已读邮件
  --from      发件人地址包含指定字符串
  --subject    主题包含指定文本
  --recent     最近 X 时间内（例如：30m、2h、7d）
  --since      指定日期之后（格式：YYYY-MM-DD）
  --before     指定日期之前（格式：YYYY-MM-DD）
  --limit         最多返回结果数（默认：20）
  --mailbox    搜索目标邮箱（默认：INBOX）

mark-read / mark-unread

将邮件标记为已读或未读。

node scripts/imap.js mark-read  [uid2 uid3...]
node scripts/imap.js mark-unread  [uid2 uid3...]

list-mailboxes

列出所有可用邮箱/文件夹。

node scripts/imap.js list-mailboxes

SMTP 命令（发送邮件）

send

通过 SMTP 发送邮件。

node scripts/smtp.js send --to  --subject  [options]

必需参数：

• --to ：收件人地址（多个地址以英文逗号分隔）
• --subject ：邮件主题，或使用 --subject-file 指定主题文件

可选参数：

• --body ：纯文本正文内容
• --html：将正文作为 HTML 发送
• --body-file ：从文件读取正文内容
• --html-file ：从文件读取 HTML 内容
• --cc ：抄送收件人
• --bcc ：密送收件人
• --attach ：附件路径（多个附件以英文逗号分隔）
• --from ：覆盖默认发件人地址

使用示例：

# 简单文本邮件
node scripts/smtp.js send --to recipient@example.com --subject "Hello" --body "World"

# HTML 邮件
node scripts/smtp.js send --to recipient@example.com --subject "Newsletter" --html --body "
Welcome
"

# 带附件的邮件
node scripts/smtp.js send --to recipient@example.com --subject "Report" --body "Please find attached" --attach report.pdf

# 多收件人邮件
node scripts/smtp.js send --to "a@example.com,b@example.com" --cc "c@example.com" --subject "Update" --body "Team update"

开发邮件工作流

核心原则

模板仅用于结构参考——务必为每位收件人定制内容。

错误做法（应避免）：

• ❌ 直接发送未经修改的模板邮件
• ❌ 在模板中硬编码客户名称、所在地或公司信息
• ❌ 向错误地区发送地域限定内容

正确做法：

• ✅ 仅复用模板结构（问候 → 公司介绍 → 附件 → 行动号召 → 签名）
• ✅ 根据客户信息（公司名、国家/地区、行业等）定制内容
• ✅ 为每位收件人动态生成 HTML 内容

发送前检查清单

1. [ ] **收集客户信息**
   - 公司名称
   - 国家/地区
   - 所属行业/业务类型
   - 联系人姓名（如有）
   - 邮箱地址

2. [ ] **生成个性化邮件内容**
   - 根据客户所在地/行业定制问候语
   - 针对不同市场调整语气与重点
   - 生成 HTML 文件或准备 `--body` 内容

3. [ ] **准备附件**
   - 产品目录 PDF
   - 定制报价单（如适用）
   - 确保所有文件路径正确无误

4. [ ] **一次性发送完整邮件**
   - 包含全部附件
   - 使用个性化内容
   - 添加专业签名

完整发送命令示例

cd $WORKSPACE/skills/imap-smtp-email

node scripts/smtp.js send 
  --to "customer@example.com" 
  --subject "Product Catalog from Your Company" 
  --html 
  --body-file "/path/to/customized-email.html" 
  --attach "/path/to/catalogue.pdf,/path/to/quotation.pdf"

OKKI CRM 集成（可选）

本技能支持与 OKKI CRM 自动同步，用于追踪邮件沟通记录。

配置

在 .env 中设置以下环境变量：

# OKKI CRM 集成
OKKI_CLI_PATH=/path/to/okki.py
VECTOR_SEARCH_PATH=/path/to/search-customers.py
PYTHON_VENV_PATH=python3

功能特性

• 通过域名或向量搜索自动匹配客户
• 在 OKKI 中创建邮件轨迹（trail_type=102）
• 创建报价单轨迹（trail_type=101）
• 通过 /tmp/okki-sync-processed.json 实现去重
• 未匹配邮件日志写入 /tmp/okki-unmatched-emails.log

手动同步命令

node okki-sync.js quotation '{"dataFile":"/path/to/data.json","quotationNo":"QT-xxx"}'

Discord 审核集成（可选）

配置 Discord 频道以支持邮件审核工作流。

配置

编辑 config/discord-config.json：

{
  "channel_id": "",
  "guild_id": "",
  "review_channel": "email-review",
  "timeout_minutes": 30
}

设置环境变量：

DISCORD_BOT_TOKEN=your-discord-bot-token

依赖项

npm install

安全注意事项

• 凭证信息请存放在 .env 文件中，并确保该文件已加入 .gitignore
• Gmail：不接受常规账户密码，请前往 https://myaccount.google.com/apppasswords 生成 App Password
• 163.com：请使用授权码（授权码），而非账户密码

故障排查

连接超时：

• 确认服务器正在运行且网络可达
• 检查主机名与端口配置是否正确

认证失败：

• 确认用户名（通常为完整邮箱地址）正确
• 确认密码正确
• 163.com 用户请使用授权码，而非账户密码
• Gmail 用户请勿使用常规密码——必须使用 App Password

TLS/SSL 错误：

• 确保 IMAP_TLS / SMTP_SECURE 设置与服务器要求一致
• 若使用自签名证书，请设置 IMAP_REJECT_UNAUTHORIZED=false 或 SMTP_REJECT_UNAUTHORIZED=false

相关文件

• 主脚本：scripts/imap.js、scripts/smtp.js
• OKKI 同步：okki-sync.js
• Discord 审核：discord-review.js
• 配置文件：config/discord-config.json、profiles/user-map.json