mail-cli

从 IMAP 邮箱抓取未读邮件，输出结构化 JSON，供 AI Agent 进一步处理。

IMAP 邮箱  →  mail-cli fetch  →  ParsedEmail[] JSON  →  AI Agent

安装

npm install -g @some-skills/mail-cli

或在项目本地构建：

npm install
npm run build

快速上手

第一步：初始化配置

mail-cli config init

配置文件生成于 ~/.config/mail-to-task/config.yml。编辑它，填入邮箱信息：

profiles:
  work:
    imap:
      host: imap.qq.com
      port: 993
      user: [email protected]
      password: ${MAIL_PASSWORD}   # 通过环境变量注入
      tls: true

密码必须通过环境变量注入，禁止明文写入配置：

export MAIL_PASSWORD="你的邮箱授权码"

第二步：抓取未读邮件

mail-cli fetch --profile work

输出 ParsedEmail[] JSON 到 stdout，示例字段：

[
  {
    "uid": "1234",
    "messageId": "<[email protected]>",
    "from": [{ "name": "张三", "address": "[email protected]" }],
    "subject": "下周五提交季报",
    "textBody": "...",
    "markdownBody": "...",
    "date": "2026-06-05T08:00:00.000Z",
    "attachments": []
  }
]

完整命令参考

mail-cli fetch

抓取指定 profile 的未读邮件，输出 ParsedEmail[] JSON。

mail-cli fetch [options]

选项：
  -p, --profile <name>   使用的邮箱配置（默认：work）
  -h, --help             显示帮助

mail-cli config

mail-cli config show                          # 查看当前配置文件路径和内容
mail-cli config init [--profile work]         # 生成默认配置文件
mail-cli config init --force                  # 强制覆盖已有配置
mail-cli config set scheduler.maxPerFetch 30  # 修改配置项

配置文件详解

默认路径：~/.config/mail-to-task/config.yml

参考 config.example.yml 查看完整示例。

| 配置项 | 说明 | 默认值 | |--------|------|--------| | profiles.<name>.imap | IMAP 连接信息 | — | | profiles.<name>.folders.inbox | 收件箱文件夹名 | INBOX | | profiles.<name>.folders.processed | 已处理文件夹（可选，移动用） | — | | filters.exclude | 排除规则（from、subject_contains）| — | | scheduler.max_per_fetch | 每次最多处理邮件数 | 20 | | scheduler.mark_as_read | 处理后标记为已读 | true | | scheduler.move_to_folder | 处理后移动到 processed 文件夹 | false |

多邮箱配置

在 profiles 下添加多个账号，--profile 切换：

profiles:
  work:
    imap:
      host: imap.qq.com
      user: [email protected]
      password: ${WORK_MAIL_PASSWORD}
      ...
  personal:
    imap:
      host: imap.163.com
      user: [email protected]
      password: ${PERSONAL_MAIL_PASSWORD}
      ...

mail-cli fetch --profile personal

开发

npm install
npm run dev -- fetch --profile work   # 本地运行（ts-node）
npm run build                          # 编译 TypeScript → dist/
npm test                               # 运行测试
npm run lint                           # ESLint 检查

依赖

| 用途 | 库 | |------|----| | IMAP 连接 | imapflow | | 邮件解析（含 GBK/GB2312）| mailparser | | HTML → Markdown | cheerio + turndown | | 配置读取 | cosmiconfig + yaml | | CLI 框架 | commander | | 日志 | pino（邮件地址自动脱敏）|