IMAP/SMTP 邮件工具

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

配置

运行安装脚本以安装依赖并配置您的邮箱账户：

bash setup.sh

若不使用 setup.sh 而手动执行命令，请先安装依赖：

npm install --production

配置文件存储于 ~/.config/mail-skills/.env（与 caldav-sync 技能共享，升级技能时保留不变）。若未找到共享配置，则技能依次检查：~/.config/imap-smtp-email/.env（旧版路径），然后是技能目录下的 .env 文件。

配置文件格式（共享）

# 默认账户
PROVIDER=163
USERNAME=your@163.com
PASSWORD=your_password

# 文件访问白名单（安全机制）
ALLOWED_READ_DIRS=~/Downloads,~/Documents
ALLOWED_WRITE_DIRS=~/Downloads

PROVIDER 预设值将自动填充 IMAP/SMTP 服务器设置。如需自定义服务器，请使用以下格式：

PROVIDER=custom
USERNAME=your@email.com
PASSWORD=your_password
IMAP_HOST=imap.example.com
SMTP_HOST=smtp.example.com

旧版配置文件格式

若您已存在 ~/.config/imap-smtp-email/.env，该文件将优先于共享配置被加载。其格式如下：

# 默认账户（无前缀）
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your@email.com
IMAP_PASS=your_password
IMAP_TLS=true
IMAP_REJECT_UNAUTHORIZED=true
IMAP_MAILBOX=INBOX

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your@email.com
SMTP_PASS=your_password
SMTP_FROM=your@email.com
SMTP_REJECT_UNAUTHORIZED=true

# 文件访问白名单（安全机制）
ALLOWED_READ_DIRS=~/Downloads,~/Documents
ALLOWED_WRITE_DIRS=~/Downloads

运行 bash setup.sh 可将您的旧版配置迁移至共享格式。

多账户支持

您可在同一配置文件中配置多个邮箱账户。每个额外账户的所有变量均需添加大写名称前缀。

添加账户

运行安装脚本并选择 “Add a new account”（添加新账户）：

bash setup.sh

或手动向 ~/.config/mail-skills/.env 添加带前缀的变量：

# 工作账户（WORK_ 前缀）
WORK_PROVIDER=gmail
WORK_USERNAME=me@company.com
WORK_PASSWORD=app_password

使用指定账户

在命令前添加 --account 参数：

node scripts/imap.js --account work check
node scripts/smtp.js --account work send --to foo@bar.com --subject Hi --body Hello

若未指定 --account，则默认使用（无前缀的）主账户。

账户名称规则

• 仅允许字母与数字（例如：work、163、personal2）
• 不区分大小写：work 与 WORK 指向同一账户
• .env 中的前缀始终为大写（例如：WORK_PROVIDER）
• ALLOWED_READ_DIRS 和 ALLOWED_WRITE_DIRS 对所有账户全局共享（始终无前缀）

常用邮件服务器

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 [--account ] check [--limit 10] [--mailbox INBOX] [--recent 2h]

选项说明：

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

fetch

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

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

智能优先级提醒

获取邮件后，Agent 应识别可能需要您紧急处理的消息。以下类型的邮件应被标记并在终端中回显：

财务类：发票、付款通知、收据、账单

合同类：协议、签名、法律文件

待操作类：审批请求、审阅任务、截止日期、会议确认

紧急类：标为高优先级，或包含紧急性指示词（如“urgent”、“ASAP”、“立即”等）

被标记的邮件将在行首添加 [!] 前缀，便于快速扫描：

text
[!] Invoice #2024-001 from billing@company.com
[!] Urgent: Contract review needed from legal@firm.com
[!] Meeting confirmation: Q4 planning tomorrow 10am

download

下载某封邮件中的全部附件，或指定某一附件。

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

选项说明：

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

search

按条件搜索邮件。

node scripts/imap.js [--account ] search [options]

选项：
  --unseen           仅未读邮件
  --seen             仅已读邮件
  --from      发件人地址包含指定字符串
  --subject    主题包含指定文本
  --recent     最近 X 时间内（例如：30m、2h、7d）
  --since      指定日期之后（格式：YYYY-MM-DD）
  --before     指定日期之前（格式：YYYY-MM-DD）
  --limit         最多返回结果数（默认：20）
  --mailbox    搜索目标邮箱（默认：INBOX）
  --sort       排序方式：uid（默认，速度快）或 date（严格按 INTERNALDATE 排序；
                     将拉取全部匹配项，适用于存在 COPY 过或时间错乱邮件的邮箱）

mark-read / mark-unread

将一条或多条消息标记为已读或未读。

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

list-mailboxes

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

node scripts/imap.js [--account ] list-mailboxes

list-accounts

列出所有已配置的邮箱账户。

node scripts/imap.js list-accounts
node scripts/smtp.js list-accounts

显示账户名、邮箱地址、服务器地址及配置状态。

SMTP 命令（发送邮件）

send

通过 SMTP 发送邮件。

node scripts/smtp.js [--account ] 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"

test

通过向自身发送测试邮件来验证 SMTP 连接是否正常。

node scripts/smtp.js [--account ] test

安全说明

• 配置文件存储于 ~/.config/mail-skills/.env（或旧版路径 ~/.config/imap-smtp-email/.env），权限为 600（仅属主可读写）
• Gmail：拒绝使用常规密码 —— 请前往 https://myaccount.google.com/apppasswords 生成 App Password
• 163.com：请使用授权码（授权码），而非账户密码

故障排查

连接超时：

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

认证失败：

• 确认用户名（通常为完整邮箱地址）是否正确
• 确认密码是否正确
• 163.com：请使用授权码，而非账户密码
• Gmail：常规密码无效 —— 请前往 https://myaccount.google.com/apppasswords 生成 App Password

TLS/SSL 错误：

• 确保 IMAP_TLS / SMTP_SECURE 设置与服务器要求一致
• 对于自签名证书：设置 IMAP_REJECT_UNAUTHORIZED=false 或 SMTP_REJECT_UNAUTHORIZED=false

相关技能

• caldav-sync —— 基于 CalDAV 协议的日历与任务管理技能。支持 Google Calendar、iCloud、NetEase 等服务的事件、待办事项及忙闲查询管理。安装命令如下：

  npx skills add https://github.com/gzlicanyi/mail-skills -s caldav-sync
  

反馈

欢迎在 github.com/gzlicanyi/mail-skills 提交问题（Issues）或 Pull Request。