作品简介

邮件接收归档工具把邮箱里的邮件（收件箱、已发送及其他文件夹）按时间范围批量下载成本地 .eml 文件归档。起因是 Outlook 在 POP3 模式下只能接收收件箱，用它初始化接收全部邮件又会一下子撑爆 PST 文件，压缩修复对普通用户来说操作太困难——于是作者自己做了这个工具：先把邮件批量接收归档，再通过插件导入 Outlook。

工具面向不熟悉的电脑同事：双击运行，按界面提示三步完成——确认登录账号、点击开始下载、打开文件夹查看。

核心亮点

账号自动识别：自动读取本机 Outlook 登录的账号，并从程序内置的账号表匹配出密码直接填好，普通同事无需知道、也无需填写任何密码；手填账号只保存在本机配置里
下载范围可选：收件箱（含服务器上其他文件夹）、已发送邮件界面上勾选即可，时间范围可选；收件箱范围自动跳过垃圾箱、草稿、垃圾邮件
并发直下：不预先扫描邮件头直接并发下载（线程 1~8 可调），每封邮件存为一个 .eml，文件名「日期_时间_UID_主题」
多级重试：单封失败当场补拉、批次退避重试、文件夹级重试轮，尽量不漏邮件
断点续传：本地缓存记录已下载 UID，重复运行只下载新邮件；中途停止或关机后，下次点“开始下载”自动续传
只读安全：readonly + BODY.PEEK 模式，不改动邮件的已读状态，也不删除任何邮件
归档有序：收件箱、已发送邮件分别建子文件夹存放，可选按年份再分层；默认腾讯企业邮，QQ 邮箱、163 等改配置即可支持

技术与工具

技术栈：Python 3.12 + CustomTkinter（GUI）+ imapclient（IMAP）+ pywin32（账号探测兜底）+ PyInstaller（打包）
工程质量：uv 锁定依赖，pytest 测试、ruff 检查、mypy 类型检查
配置与日志：config.toml 保存服务器、下载范围与缓存设置；日志按日期分文件、保留 30 天
开发方式：程序员水平，借助 AI 编程类工具与国内低价 Flash 模型完成

开发过程

作者的理念是“想法比落地更重要”：最初只想做一个接收已发送邮件的小工具，边做边迭代，最终扩展成整个邮箱（收件箱 + 已发送邮件）的完整接收归档方案。

适用场景

企业邮箱邮件批量归档备份：按时间范围导出 .eml 存档，避免 Outlook 的 PST 文件过载
个人历史邮件批量下载留存，快速整理本地邮件资料
4 万封以上的大邮箱建议并发设 3~4，兼顾速度与稳定

原始提交内容（点开查看，可复制全文去问 AI）

邮件接收归档工具

把邮箱里的邮件（收件箱、已发送及其他文件夹）按时间范围批量下载成本地 .eml 文件归档的小工具。给不熟悉电脑的同事用：双击运行，按界面提示三步完成。

功能

账号自动识别：自动读取本机 Outlook 登录的账号，并从程序内置的账号表匹配出密码直接填好；普通同事无需知道、也无需填写任何密码
知道密码的账号（如高层账号）可在界面“登录账号”处手动填写，只保存在本机 config.toml 里，下次打开不用重填
通过 IMAP 连接邮箱（默认腾讯企业邮 imap.exmail.qq.com，其他邮箱改配置即可）
下载范围可选：收件箱（含服务器上其他文件夹）、已发送邮件，界面上勾选即可
时间范围可选：开始日期 / 结束日期（含当天），只下载区间内的邮件
自动识别“已发送”文件夹（按 \Sent 标志识别，失败时按常见名字回退）；收件箱范围自动跳过垃圾箱、草稿、垃圾邮件
收件箱、已发送邮件分别存到归档根目录下的 收件箱/、已发送邮件/ 子文件夹，其他服务器文件夹按名字建子目录存放
直接并发下载（不预先扫描邮件头），每封邮件保存为一个 .eml 文件，文件名格式：日期_时间_UID_主题.eml
多级重试：单封失败当场补拉、批次退避重试、文件夹级重试轮，尽量不漏邮件
本地下载缓存（每个文件夹一份 download_state__*.json）：已下载的 UID 记录在本地，重复运行只下载新邮件；中途停止或关机后，下次点“开始下载”自动断点续传
可选：按年份建子文件夹存放、并发线程数（1~8）
下载过程只读服务器（readonly + BODY.PEEK），不会改动邮件的已读状态，也不会删除任何邮件

快速开始（使用者）

双击 mail_downloader.exe（首次运行会自动在旁边生成 config.toml，启动即最大化窗口）
界面会自动识别并填好登录账号和密码（前提：电脑上的 Outlook 登录过公司邮箱），一般无需填写；两个输入框都留空即可
勾选下载范围（收件箱 / 已发送邮件）、按需填时间范围，点“开始下载”，完成后点“打开保存目录”查看 .eml 文件

配置文件说明（config.toml）

[mail]
host = "imap.exmail.qq.com"   # IMAP 服务器地址
port = 993                    # 993 = SSL 加密，一般不改
email = ""                    # 邮箱账号：一般留空，软件自动识别本机 Outlook 账号
password = ""                 # 密码：一般留空，从程序内置账号表自动匹配
folder = "Sent"               # Sent = 自动识别已发送；也可填具体文件夹名

[download]
save_dir = "邮件归档"          # 归档根目录，收件箱/已发送邮件各建子文件夹存放
since = ""                    # 开始日期，如 "2024-01-01"；空 = 不限
before = ""                   # 结束日期（含当天），如 "2024-12-31"；空 = 不限
folders = ["sent"]            # 下载范围："inbox" 收件箱、"sent" 已发送
group_by_year = false         # true = 按年份建子文件夹（2023、2024…）
concurrency = 3               # 并发线程数，1~8；4 万封以上建议 3~4
ignore_cache = false          # true = 忽略本地记录全部重新下载

账号密码一般留空即可；界面手填的账号密码会在点“开始下载”时自动保存回 config.toml（只存使用者自己电脑上）。想让软件把所有邮件重新下载一遍：点界面上的“清空下载缓存”按钮，或把 ignore_cache 改成 true 跑一次再改回来。

常见邮箱的 IMAP 设置

邮箱	host	密码说明
腾讯企业邮	`imap.exmail.qq.com`	网页版登录密码
QQ 个人邮箱	`imap.qq.com`	设置账户开启 IMAP 并生成授权码
网易 163	`imap.163.com`	需开启 IMAP 并使用授权码

开发者指南

技术栈：Python 3.12 + CustomTkinter（GUI）+ imapclient（IMAP）+ pywin32（账号探测兜底）+ PyInstaller（打包）。

uv sync --locked          # 还原环境
uv run pytest             # 运行测试
uv run ruff check src tests
uv run mypy src
uv run mail_downloader   # 开发态启动
uv run python scripts/build.py  # 打包，产出 dist/mail_downloader/{windows,macos,linux}/
uv run --python 3.12 ../python-dev/scripts/py/verify_delivery.py --dist-dir dist --app-name mail_downloader

代码结构：

src/mail_downloader/
 config.py          # config.toml 读取与校验（含默认模板、账号密码写回）
 local_account.py   # 本机 Outlook 账号探测（注册表/COM）+ 内置账号密码表
 mail_client.py     # IMAP 会话：连接、识别文件夹、按 UID 批量拉取
 state.py           # 本地下载缓存（每个文件夹一份，断点续传）
 core.py            # 下载编排：多文件夹循环、多线程并发、多级重试、进度上报
 logging_setup.py   # 日志（按日期分文件、5MB、保留 30 天）
 main.py            # 入口
 ui/app.py          # CustomTkinter 界面（登录账号自动识别、最大化启动）

日志位置：开发态在项目 logs/；打包后在 %LOCALAPPDATA%\mail_downloader\logs\。