Metadata-Version: 2.4
Name: mailops
Version: 0.2.5
Summary: 邮件操作工具箱 — 下载、统计、搜索、转发、附件管理、发送
Author: Song Wupei
License-Expression: MIT
Project-URL: Repository, https://codeberg.org/songwupei/mailops
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Communications :: Email :: Email Clients (MUA)
Classifier: Topic :: Communications :: Email :: Post-Office :: IMAP
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8
Requires-Dist: pyyaml>=6

# mailops — 邮件操作工具箱

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

## 安装

```bash
pip install -e .
```

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

## 快速开始

```bash
# 查看所有命令
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`)

```yaml
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` 命令，按规则自动分类/归档邮件。示例：

```yaml
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`。

## 命令一览

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

## 从 mail-dl 迁移

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

| 旧脚本 | 新命令 |
|--------|--------|
| `maildl.py` | `mailops download-docs` |
| `mailfwd.py` | `mailops forward` |
| `sync163.py` | `sync_account.py 163` (IMAP → Maildir，索引去重) + `mailops organize` |
| `mbsync` | `sync_account.py QQ` (IMAP → Maildir，索引去重，本地删除不重下) |
| `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 接入）

```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）。
