mailops — 邮件操作工具箱

通用邮件操作工具。支持 QQ/163 双邮箱，Maildir + IMAP 直连双模式，YAML/JSON 配置驱动。 内置 SMTP 发送，无需系统 mailx。

Changelog / 更新记录

v0.2.6（2026-09-03）

• 修复：中文附件名显示为“未命名”：send / send_email 的附件头改用 RFC 2231 编码（filename*=utf-8''…），QQ/163/Outlook 可正确显示中文附件名。

安装

pip install -e .

依赖: click>=8, pyyaml>=6（pip 自动安装）。

快速开始

# 查看所有命令
mailops --help

# 查看邮箱账户配置
mailops config

# 一站式同步+下载（推荐）
mailops pull                       # 默认 QQ
mailops -m 163 pull                # 163 IMAP 同步+下载
mailops pull --no-sync             # 跳过同步，仅下载
mailops pull --no-download         # 仅同步不下载

# 列出最近邮件
mailops list -n 10

# 邮件统计
mailops stats

# 搜索邮件
mailops search "发票"

# 查看邮件内容
mailops show <UID>

# 下载邮件（不先同步）
mailops download

# 按关键词搜索 PDF 文档并下载（原 maildl.py 功能）
mailops download-docs -t 发票 -n 100

# 发送邮件
mailops send -t me@163.com -s "日报" -b "详见附件" -a report.pdf

# 执行工作流
mailops workflow run 163-invoice-to-qq

# 邮件自动分类归档
mailops organize --dry-run          # 预览
mailops organize -a 163             # 执行

# 指定邮箱
mailops -m qq list
mailops -m 163 list

下载输出结构

archive/
  2026-05-28_...电子发票..._5864ea/
    body.md                           ← Markdown 正文（含 From/To/Date 元数据）
    26117000000762997017.pdf          ← 附件
    26117000000762997017.zip
  2026-06-12_周五闲谈..._acf207/
    body.md
    logo.png

配置

邮箱账户 (config/accounts.yml)

default_mailbox: qq
output_dir: archive

mailboxes:
  qq:
    display: QQ邮箱
    type: maildir
    path: ~/Mail/QQ/INBOX
    mbsync_channel: QQ

  "163":                               # 数字 key 必须加引号
    display: 163邮箱
    type: imap
    host: imap.163.com
    user: songwupei@163.com
    pass_file: ~/.config/aerc/163-pass
    pass_env: MAIL163_SMTP_PASS_AERC
    maildir_path: ~/Mail/163/INBOX    # IMAP 同步目标

smtp:
  default: qq
  accounts:
    qq:
      host: smtp.qq.com
      port: 465
      user: songwupei@qq.com
      pass_file: ~/.config/aerc/qq-pass

文档类型 (config/types.json)

用于 download-docs 命令，定义关键词匹配规则。

工作流 (config/workflow.json)

用于 mailops workflow 命令，定义自动化的同步→下载→转发流程。

邮件分类规则 (~/.config/aerc/mail-rules.yml)

用于 mailops organize 命令，按规则自动分类/归档邮件。示例：

accounts:
  "163":
    maildir: ~/Mail/163
    rules:
      - name: github
        match:
          from: "(?i)@github\\.com"
          list_id: "(?i)github"
          match_any: true
        action:
          move: GitHub
      - name: archive-old
        match:
          older_than: 7d
        action:
          move: "Archive/{year}/{month}"

参考 config/mail-rules.example.yml。

命令一览

从 mail-dl 迁移

原 src/ 下的独立脚本转为 mailops CLI 子命令：

旧脚本保留，可直接运行。run.sh / watch-mail.sh 也保留不动。

两种邮箱源

PDF 提取策略（download-docs）

1. 附件优先 — 直接从邮件 PDF 附件提取
2. 正文链接 — 匹配正文中 pdf/download 路径、.pdf 结尾的 URL
3. 去重 — 按文档编号 + PDF 哈希双重去重，每个类型独立 CSV

发送邮件（Python 接入）

from mailops.forwarder import send_email
from mailops.config import get_smtp_config

send_email(
    get_smtp_config(),
    to_addr="me@163.com",
    subject="日报",
    body="详见附件",
    attachments=["report.pdf"],
    from_addr="me@qq.com",
    cc=["cc@qq.com"],
)

SMTP 账户配置在 accounts.yml → smtp，无需系统 mailx。

环境初始化

见 setup-arec.sh（一键配置 aerc + mbsync + Maildir）。