draftmachine 0.1.0

CLI mail merge tool that creates Gmail drafts from a CSV and Markdown template

DraftMachine

CLI mail merge tool — creates Gmail drafts from a CSV and a Markdown template.

Every existing CLI mail merge tool sends immediately. DraftMachine creates drafts instead: review them in Gmail's UI, edit any outliers, then send when ready.

Install

pip install draftmachine

Or from source:

git clone https://github.com/YOUR_USERNAME/draftmachine
cd draftmachine
pip install .

Quick start

1. Set up your GCP credential (one-time):

   draftmachine setup
   

2. Create a template (template.md):

   ---
   subject: Hey {{first_name}}, quick note about {{company}}
   ---
   
   Hi {{first_name}},
   
   I noticed that **{{company}}** is doing great things lately.
   
   Best,
   John
   

3. Create your email list (list.csv):

   email,first_name,company
   [e-mail],Alice,Acme
   [e-mail],Bob,Globex
   

4. Preview before creating (renders row 1, no API calls):

   draftmachine send list.csv template.md --preview
   

5. Create the drafts:

   draftmachine send list.csv template.md
   # ✓ Created 2 drafts. Open Gmail to review.
   

Template syntax

Templates are Markdown files with YAML frontmatter. Any CSV column header becomes a {{variable}} in the template.

Jinja2 is the template engine — conditionals, filters, and loops all work:

---
subject: {% if vip %}[VIP] {% endif %}Hi {{first_name}}
---

Hi {{first_name}},

{% if company %}
You're at **{{company}}** — let's talk.
{% else %}
I'd love to connect.
{% endif %}

Options

Flag	Description	Default
--preview	Render row 1 to terminal, no API calls	off
--to-column	CSV column to use as recipient address	email

# Use a different column as the email address
draftmachine send list.csv template.md --to-column=work_email

GCP credential setup (manual steps)

draftmachine setup walks you through this, but here are the steps:

1. Go to Google Cloud Console
2. Create a project (or select an existing one)
3. Enable the Gmail API: APIs & Services → Enable APIs → search "Gmail API" → Enable
4. Create an OAuth credential: APIs & Services → Credentials → + Create Credentials → OAuth client ID
   • Application type: Desktop app
5. Download the JSON file and move it to ~/.draftmachine/client_secret.json
6. Run draftmachine setup to complete the OAuth consent flow

The tool uses the gmail.compose scope — draft creation only, no ability to send or read your email.

Note: For personal use (your own Gmail account), the "This app is not verified" warning is expected and safe to proceed through. For distribution to other users, Google's OAuth app verification is required.

Known limitations

• --preview shows row 1 only. It's a quick sanity check, not a full dry-run. Pass 1 (the two-pass render) validates all rows before any drafts are created — so template errors on any row are caught before Gmail is touched.

• Quota errors leave partial state. If the Gmail API returns a 429 (quota exceeded) partway through draft creation, some drafts will have been created and others won't. DraftMachine reports how many succeeded. V1 has no resume mechanism — check your Gmail Drafts folder before retrying to avoid duplicates.

• Always uses your Gmail account's default sender. If you have send-as aliases configured, the draft's From address will be your primary Gmail address. --from alias support is planned.

Development

git clone https://github.com/YOUR_USERNAME/draftmachine
cd draftmachine
pip install -e ".[dev]"
pytest

License

MIT