本地 Gmail 清理工具：无需将邮件发送至第三方服务器
某一天，我们打开邮箱，看到数万封未读邮件。五年前购物的商店折扣、服务摘要、任务追踪通知。手动在 Gmail 自己的界面中清理简直是一场噩梦，因为 Google 的网页客户端对超过 50-100 条消息的选择处理得非常勉强。
大多数商业邮件清理工具采用订阅模式运营。它们请求完全账户访问权限，并将你的邮件发送到自己的服务器进行分析。gmail-cleaner 项目的作者采取了不同的方式：编写了一个轻量级的本地工具，带有 Web 界面，通过官方 Gmail API 仅在你的机器上运行。
为什么要在本地运行清理
该项目的主要理念是完全隐私。无第三方后端、无外部数据库、无付费计划。整个技术栈在本地运行，你的任何数据都不会外传。
该应用解决了四个常见问题：
- 查找新闻通讯并帮助一键取消订阅。
- 按发件人分组邮件，显示谁最让你的收件箱杂乱。
- 批量删除或归档来自选定收件人的邮件线程。
- 在几秒钟内将数千封邮件标记为已读。
所有已删除的邮件都会进入 Gmail 标准垃圾箱。如果你不小心删除了需要的内容，可以通过 Google 标准网页界面在 30 天内恢复数据。
为了加快速度，该工具使用 Gmail API 批量请求，每次调用最多打包 100 个操作。这就是为什么清理数千封邮件只需很短的时间。
内部结构和工作原理
底层使用 Python 3.9+ 和一个 Web 服务器，以 Gmail 本身的风格提供简洁的界面。
从安全角度来看，你在 Google Cloud Console 中创建自己的应用。这意味着 OAuth 令牌只属于你自己，权限请求仅限最小必要范围：读取和修改移动邮件到垃圾箱以及更改已读状态的权限。
文件 credentials.json 和 token.json 存储在本地。在 Docker 构建中为此提供了单独的卷 ./data，因此重启容器后无需重新授权。
如何部署项目
运行项目最简单的方式是通过 Docker。对于喜欢虚拟环境的人，也可以使用 uv 包管理器。
首先，你需要进入 Google Cloud Console，创建一个项目，启用 Gmail API，并生成 OAuth 客户端 ID（Docker 使用 Web 应用类型，直接运行 Python 则使用桌面应用类型）。确保在 OAuth 同意屏幕上将你的邮箱添加到测试用户列表中。
将下载的文件保存为项目根目录下的 credentials.json。
通过 Docker 运行
克隆仓库：
git clone https://github.com/Gururagavendra/gmail-cleaner.git
cd gmail-cleaner
将 credentials.json 文件放在旁边并启动容器：
docker compose pull && docker compose up
然后在浏览器中打开 http://localhost:8766，点击登录按钮，从容器日志中获取 Google 授权链接，并确认访问权限。
通过 Python 和 uv 运行
如果你不想设置 Docker，可以通过 uv 直接运行脚本：
uv sync
uv run python main.py
界面将在同一地址 http://localhost:8766 可用。
过滤器和数据导出
除了简单的清理，项目还包括高级过滤器。你可以通过附件大小、日期范围或标准 Gmail 类别（推广、社交、动态、论坛、主要）来排序邮件。
如果你需要在删除旧工作邮件之前保留有关发件人和日期的信息，界面可以将元数据导出为 CSV。
谁会发现这很有用
该项目非常适合收件箱已超过 50,000 条消息并接近 Google Drive 免费存储空间限制的任何人。
是的，初始设置需要 5-10 分钟在 Google Cloud Console 中操作并创建 OAuth 密钥。但作为回报，你获得了一个不在第三方服务器上读取你的邮件、对于基本清理功能也不需要每月订阅的工具。
相关项目