qqmail-cli

腾讯企业邮箱 IMAP 命令行客户端，用于浏览邮件、查看正文、下载附件。所有输出均为 JSON 格式。

核心亮点

• JSON 输出 — 所有命令输出结构化 JSON，默认格式化，--compact 紧凑输出
• 零配置登录 — .env 文件管理账号密码，一条命令验证连通性
• 中文文件夹名自动解码 — Modified UTF-7 编码的文件夹名自动解码
• 纯标准库 IMAP 通信 — 不依赖第三方 IMAP 库

安装

依赖 uv 管理 Python 环境和依赖：

uv sync

安装后可直接使用 qqmail 命令：

qqmail login

也可通过 uv run main.py 执行。

配置

创建 .env 文件，程序会依次从当前工作目录和 ~/.config/qqmail-cli/ 查找并加载（两者都配置时，当前目录优先）：

IMAP_HOST=imap.exmail.qq.com
IMAP_PORT=993
IMAP_USER=your_email@example.com
IMAP_PASSWORD=your_password_or_app_token

使用方法

所有命令默认输出格式化 JSON，加 --compact 输出紧凑 JSON。

验证登录

qqmail login

列举邮箱文件夹

qqmail folders

浏览邮件（分页）

# 查看 INBOX 第一页（默认每页 20 封）
qqmail mails

# 指定文件夹和页码
qqmail mails --folder "Sent Messages" --page 2

# 调整每页数量
qqmail mails --size 50

搜索邮件

--since 为必填参数。--from 和 --subject 为可选过滤条件。

# 搜索指定日期以来的邮件
qqmail mails search --since 2026-04-13

# 按发件人过滤
qqmail mails search --since 2026-04-13 --from sender@example.com

# 按主题关键词过滤
qqmail mails search --since 2026-04-13 --subject 周报

# 组合过滤 + 限制数量
qqmail mails search --since 2026-04-13 --before 2026-04-20 \
  --from sender@example.com --subject 周报 --limit 5

查看邮件详情

qqmail mail 1555

# 查看完整内容（含转发的历史邮件）
qqmail mail 1555 --raw

# 指定文件夹
qqmail mail 1555 --folder "Sent Messages"

输出包含：id、from、to、cc、subject、date、body、attachments。

操作附件

# 列出附件
qqmail attachments list 1555

# 下载全部附件
qqmail attachments download 1555 -o /tmp/attachments

# 只下载指定附件
qqmail attachments download 1555 -f "周报.xlsx" -o /tmp/attachments

命令速查

全局选项：--compact 紧凑 JSON 输出。

许可证

MIT License