gmail-no-send

一个 Gmail 命令行工具，完全无法发送邮件。不是“不会”发送——而是根本不能发送。代码库中**不存在任何发送功能**。

安装

要求 Python 3.9 或更高版本。

cd /scripts/gmail-no-send
pip install -e .

或直接从 GitHub 仓库安装：

pip install git+https://github.com/meimakes/gmail-no-send.git

首次认证

每位用户都需要配置独立的 Google Cloud OAuth 凭据：

1. 在 console.cloud.google.com 创建项目
2. 启用 Gmail API
3. 创建 OAuth 2.0 凭据（选择“桌面应用”类型）
4. 下载 client_secret.json

然后执行认证：

gmail-no-send auth --client-secret /path/to/client_secret.json --account myname

该命令将打开浏览器完成 Google OAuth 授权流程。生成的访问令牌将保存至 ~/.config/gmail-no-send/token.json，并支持自动刷新。

命令列表

所有命令均需指定 --account 参数（名称需与认证时使用的名称一致）。

搜索

gmail-no-send search --account mei --query "from:someone@example.com newer_than:7d" --max 10

返回包含消息 ID 和会话 ID 的 JSON 数组。

读取

gmail-no-send read --account mei --message-id 

返回完整的消息载荷（包括邮件头、正文及标签信息）。

创建草稿

gmail-no-send draft-create --account mei --to "someone@example.com" --subject "Re: topic" --body "Draft text here"
gmail-no-send draft-create --account mei --to "someone@example.com" --subject "Long draft" --body-file /path/to/body.txt

更新草稿

gmail-no-send draft-update --account mei --draft-id  --to "someone@example.com" --subject "Updated" --body "New body"

归档

gmail-no-send archive --account mei --message-id 

移除 INBOX 标签（邮件仍保留在“全部邮件”中）。

安全模型

• 不存在发送命令。 本 CLI 仅提供 6 个命令：auth、search、read、draft-create、draft-update、archive —— 其中**无一具备发送能力**。
• OAuth 权限范围说明： Gmail API 并未提供“仅限草稿”的权限范围（scope）。当前使用的 compose 范围在技术上允许通过 API 发送邮件。本工具在应用层强制禁止发送行为——代码中**根本不调用任何发送端点**。
• 审计日志： 所有操作均记录至 ~/.config/gmail-no-send/audit.log，每条日志附带时间戳。
• 令牌存储： ~/.config/gmail-no-send/token.json 文件为用户本地独占，不与其他用户共享。

如需更深入的安全分析，请参阅 references/threat-model.md。

智能体（Agent）使用注意事项

• 搜索（search）仅返回消息 ID，不返回内容；如需获取实际邮件内容，请调用 read 命令。
• 创建草稿（draft-create）会返回草稿 ID，供后续更新使用。
• 对于较长的草稿正文，建议使用 --body-file 参数而非 --body，以避免 Shell 字符转义问题。
• 本工具**不支持附件、自定义标签或过滤器**——设计上即保持极简。