mailops 0.2.3

邮件操作工具箱 — 下载、统计、搜索、转发、附件管理、发送

mailops — 邮件操作工具箱

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

安装

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 [e-mail] -s "日报" -b "详见附件" -a report.pdf

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

# 指定邮箱
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: [e-mail]
    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: [e-mail]
      pass_file: ~/.config/aerc/qq-pass

文档类型 (config/types.json)

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

工作流 (config/workflow.json)

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

命令一览

命令	说明
pull	一站式同步+下载（mbsync/IMAP → 文件夹/body.md/附件）
list	列出邮件（分页、按日期排序）
show	查看邮件详情
search	搜索邮件（按主题/发件人/正文）
stats	邮件统计（总量、发件人排行、附件分布）
download	下载附件和正文（本地扫描，不先同步）
download-docs	按关键词搜索 PDF 下载（原 maildl.py）
send	发送邮件（支持多附件、抄送）
forward	转发已下载文档
fetch	同步 IMAP → Maildir
workflow	管理工作流
config	查看配置

从 mail-dl 迁移

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

旧脚本	新命令
maildl.py	mailops download-docs
mailfwd.py	mailops forward
sync163.py	mailops fetch -m 163
run-wf.py	mailops workflow
mailx (系统命令)	mailops send

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

两种邮箱源

邮箱	同步方式	拉取命令
QQ	maildir（mbsync）	mailops pull
163	IMAP 直连（含 ID 兼容）	mailops -m 163 pull

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="[e-mail]",
    subject="日报",
    body="详见附件",
    attachments=["report.pdf"],
    from_addr="[e-mail]",
    cc=["[e-mail]"],
)

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

环境初始化

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