DraftMachine — 通过 CLI 实现 Gmail 邮件合并

DraftMachine 从 CSV 列表 + Markdown 模板生成 Gmail 草稿。所有草稿将直接存入用户的 Gmail「草稿」文件夹，供人工审核后再发送——不会自动发出任何邮件。

步骤 1 — 检查是否已安装

draftmachine --version

若命令未找到，请先安装：

pip install draftmachine

步骤 2 — 检查 Gmail 凭据

必须存在以下两个文件：

检查文件是否存在：

ls ~/.draftmachine/

若缺少 client_secret.json — 引导用户完成 GCP 配置

请告知用户：需执行一次性的设置，以将 DraftMachine 连接到其 Gmail 账户：

1. 访问 Google Cloud Console，新建一个项目（或选择已有项目）。
2. 进入 API 和服务 → 启用 API 和服务，启用 Gmail API。
3. 进入 API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID。
4. 选择应用类型为 桌面应用。
5. 点击 下载 JSON，并将该文件保存至 ~/.draftmachine/client_secret.json。
   • 如目录不存在，可先执行 mkdir ~/.draftmachine 创建。
6. 运行 draftmachine setup —— 此操作将打开浏览器窗口，请求 Gmail 权限（仅限草稿范围），并保存获取的 token。

若 client_secret.json 存在但 creds.json 缺失

运行 draftmachine setup 以完成 OAuth 授权流程。

若两个文件均已存在

凭据已就绪 —— 可跳至步骤 3。

步骤 3 — 收集收件人列表并编写模板

CSV 文件

CSV 至少需包含一个邮箱列（默认列为 email）。其余任意列名均可作为模板变量使用。请询问用户手头有哪些数据；若用户在对话中粘贴了数据，请将其写入一个 .csv 文件。

示例：

email,first_name,company
jane@example.com,Jane,Acme Corp
bob@example.com,Bob,

Markdown 模板

模板是一个 .md 文件，包含 YAML frontmatter 区块用于定义主题行（subject），正文部分使用 Jinja2 语法书写 Markdown。请询问用户邮件正文应表达什么内容，然后据此编写模板。

---
subject: "致 {{ first_name }} 的简短备注"
---
您好 {{ first_name }}，

{% if company %}
我了解到贵司 {{ company }}，认为这封邮件或许对您有帮助。
{% endif %}

[此处填写邮件正文]

此致  
[发件人姓名]

优质模板编写提示：

• 使用 {{ variable }} 插入 CSV 中对应列的值。
• 对可选内容使用 {% if variable %}...{% endif %} 包裹，避免因字段缺失导致格式异常或空白段落。
• 主题行（subject）同样支持 Jinja2 语法。
• 支持过滤器（如 {{ first_name | title }}）和循环等 Jinja2 特性。

步骤 4 — 创建草稿前预览

务必先运行 --preview 参数。它仅在终端中渲染 CSV 的第一行，不调用任何 API，也不创建任何草稿。这是快速验证模板语法与格式是否正确的安全检查方式。

draftmachine send list.csv template.md --preview

若渲染结果符合预期，即可继续；若出现错误（如未定义变量、条件语句异常等），请修正模板后重新预览。

步骤 5 — 创建草稿

确认预览无误后，执行：

draftmachine send list.csv template.md

若邮箱地址所在列名不是 email，请使用 --to-column 指定：

draftmachine send list.csv template.md --to-column work_email

DraftMachine 采用两阶段策略：首先完整渲染所有行（任一行模板出错即提前中止），再统一通过 Gmail API 批量创建草稿。这意味着每次运行均为“全有或全无”——模板错误时不会产生部分草稿。

步骤 6 — 向用户反馈结果

命令执行完成后，请向用户说明以下信息：

• 共创建了多少封草稿。
• 这些草稿已出现在其 Gmail「草稿」文件夹中，可随时人工审阅并发送。
• 提醒用户检查终端输出中关于跳过行的警告（DraftMachine 会在收件人地址为空或缺失时于终端中给出提示）。

错误参考