imap-smtp-email

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 文件。

配置文件格式（共享）

# Default account
PROVIDER=163
[email protected]
PASSWORD=your_password

# File access whitelist (security)
ALLOWED_READ_DIRS=~/Downloads,~/Documents
ALLOWED_WRITE_DIRS=~/Downloads

PROVIDER 预设会自动填充 IMAP/SMTP 服务器设置。对于自定义服务器：

PROVIDER=custom
[email protected]
PASSWORD=your_password
IMAP_HOST=imap.example.com
SMTP_HOST=smtp.example.com

旧版配置文件格式

如果已有 ~/.config/imap-smtp-email/.env，它的优先级高于共享配置。格式如下：

# Default account (no prefix)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
[email protected]
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
[email protected]
SMTP_PASS=your_password
[email protected]
SMTP_REJECT_UNAUTHORIZED=true

# File access whitelist (security)
ALLOWED_READ_DIRS=~/Downloads,~/Documents
ALLOWED_WRITE_DIRS=~/Downloads

运行 bash setup.sh，将旧版配置迁移到共享格式。

多帐户

你可以在同一个配置文件中配置其他电子邮件帐户。每个帐户的所有变量都使用名称前缀（大写）。

添加帐户

运行设置脚本并选择“Add a new account”：

bash setup.sh

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

# Work account (WORK_ prefix)
WORK_PROVIDER=gmail
[email protected]
WORK_PASSWORD=app_password

使用命名帐户

在命令前添加 --account <name>：

node scripts/imap.js --account work check
node scripts/smtp.js --account work send --to [email protected] --subject Hi --body Hello

如果不指定 --account，则使用默认（无前缀）帐户。

帐户名称规则

• 只能包含字母和数字（例如，work、163、personal2）
• 不区分大小写：work 和 WORK 指向同一个帐户
• .env 中的前缀始终为大写（例如，WORK_PROVIDER）
• 所有帐户共享 ALLOWED_READ_DIRS 和 ALLOWED_WRITE_DIRS（始终不带前缀）

常见邮件服务器

提供商	IMAP 主机	IMAP 端口	SMTP 主机	SMTP 端口
163.com	imap.163.com	993	smtp.163.com	465
vip.163.com	imap.vip.163.com	993	smtp.vip.163.com	465
126.com	imap.126.com	993	smtp.126.com	465
vip.126.com	imap.vip.126.com	993	smtp.vip.126.com	465
188.com	imap.188.com	993	smtp.188.com	465
vip.188.com	imap.vip.188.com	993	smtp.vip.188.com	465
yeah.net	imap.yeah.net	993	smtp.yeah.net	465
Gmail	imap.gmail.com	993	smtp.gmail.com	587
Outlook	outlook.office365.com	993	smtp.office365.com	587
QQ 邮箱	imap.qq.com	993	smtp.qq.com	587
exmail.qq.com	imap.exmail.qq.com	993	smtp.exmail.qq.com	465

Gmail 注意事项：

• Gmail 不接受常规帐户密码
• 你必须生成应用专用密码：https://myaccount.google.com/apppasswords
• 将生成的 16 位应用专用密码用作 IMAP_PASS / SMTP_PASS
• 需要启用两步验证的 Google 帐户

163.com 注意事项：

• 请使用授权码，而非帐户密码
• 请先在网页设置中启用 IMAP/SMTP

IMAP 命令（接收邮件）

check

检查新邮件或未读邮件。

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

选项：

• --limit <n>：结果数量上限（默认值：10）
• --mailbox <name>：要检查的邮箱文件夹（默认值：INBOX）
• --recent <time>：仅显示过去 X 时间内的邮件（例如，30m、2h、7d）
• --unseen：仅显示未读邮件

输出为一个对象：{ "results": [...], "meta": {...} }（结构与 search 相同；对于 check，meta.fallbackUsed 始终为 false）。

fetch

按 UID 获取完整邮件内容。

node scripts/imap.js [--account <name>] fetch <uid> [--mailbox INBOX]

download

下载邮件中的所有附件或指定附件。

node scripts/imap.js [--account <name>] download <uid> [--mailbox INBOX] [--dir <path>] [--file <filename>]

选项：

• --mailbox <name>：邮箱文件夹（默认值：INBOX）
• --dir <path>：输出目录（默认值：当前目录）
• --file <filename>：仅下载指定附件（默认值：下载全部）

search

使用筛选条件搜索邮件。

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

Options:
  --unseen           Only unread messages
  --seen             Only read messages
  --from <email>     From address contains
  --subject <text>   Subject contains
  --recent <time>    From last X time (e.g., 30m, 2h, 7d)
  --since <date>     After date (YYYY-MM-DD)
  --before <date>    Before date (YYYY-MM-DD)
  --limit <n>        Max results (default: 20)
  --mailbox <name>   Mailbox to search (default: INBOX)
  --sort <mode>      uid (default, fast) or date (strict INTERNALDATE sort;
                     fetches all matches, use when mailbox has COPY'd/backdated mail)

输出为一个对象：{ "results": [...], "meta": {...} }，其中 results 是消息对象数组，meta 包含 fallbackUsed、provider、scope、scanned、matched、returned、truncated 和可选的 note。

对于 163/126/188/yeah.net（网易）账户，IMAP 服务端会在文本搜索（--from/--subject）时静默返回空结果。系统会自动在客户端进行筛选：服务端 SEARCH 仅保留日期/标记条件，然后获取邮件并在本地筛选。搜索 --from/--subject 且未指定日期/标记范围时，只会扫描最近 200 封邮件（meta.truncated=true）——添加 --recent/--since 可扩大搜索范围。

mark-read / mark-unread

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

node scripts/imap.js [--account <name>] mark-read <uid> [uid2 uid3...]
node scripts/imap.js [--account <name>] mark-unread <uid> [uid2 uid3...]

list-mailboxes

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

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

list-accounts

列出所有已配置的电子邮件账户。

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

显示账户名称、电子邮件地址、服务器地址和配置状态。

SMTP 命令（发送邮件）

send

通过 SMTP 发送邮件。

node scripts/smtp.js [--account <name>] send --to <email> --subject <text> [options]

必需：

• --to <email>：收件人（多个收件人以逗号分隔）
• --subject <text>：邮件主题，或使用 --subject-file <file>

可选：

• --body <text>：纯文本正文
• --html：以 HTML 格式发送正文
• --body-file <file>：从文件读取正文
• --html-file <file>：从文件读取 HTML
• --cc <email>：抄送收件人
• --bcc <email>：密送收件人
• --attach <file>：附件（以逗号分隔）
• --from <email>：覆盖默认发件人

示例：

# Simple text email
node scripts/smtp.js send --to [email protected] --subject "Hello" --body "World"

# HTML email
node scripts/smtp.js send --to [email protected] --subject "Newsletter" --html --body "<h1>Welcome</h1>"

# Email with attachment
node scripts/smtp.js send --to [email protected] --subject "Report" --body "Please find attached" --attach report.pdf

# Multiple recipients
node scripts/smtp.js send --to "[email protected],[email protected]" --cc "[email protected]" --subject "Update" --body "Team update"

test

发送测试邮件给自己，以测试 SMTP 连接。

node scripts/smtp.js [--account <name>] test

安全说明

• 配置存储在 ~/.config/mail-skills/.env（旧版配置路径为 ~/.config/imap-smtp-email/.env），权限为 600（仅所有者可读写）
• Gmail：普通密码会被拒绝——请在 https://myaccount.google.com/apppasswords 生成应用专用密码
• 对于 163.com：请使用授权码，而非账户密码

故障排除

连接超时：

• 确认服务器正在运行且可访问
• 检查主机/端口配置

身份验证失败：

• 确认用户名正确（通常是完整的电子邮件地址）
• 检查密码是否正确
• 对于 163.com：请使用授权码，而非账户密码
• 对于 Gmail：普通密码无法使用——请在 https://myaccount.google.com/apppasswords 生成应用专用密码

TLS/SSL 错误：

• 根据服务器要求设置 IMAP_TLS/SMTP_SECURE
• 对于自签名证书：设置 IMAP_REJECT_UNAUTHORIZED=false 或 SMTP_REJECT_UNAUTHORIZED=false

相关技能

• caldav-sync - 通过 CalDAV 协议管理日历和任务。使用 Google Calendar、iCloud、网易等服务管理事件、待办事项和忙闲查询。使用以下命令安装：

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

反馈

欢迎在 github.com/gzlicanyi/mail-skills 提交问题和拉取请求。