DraftMachine — Gmail Mail Merge via CLI
DraftMachine creates Gmail drafts from a CSV list + Markdown template. Drafts land in the
user's Gmail Drafts folder for review before sending — nothing gets sent automatically.
Step 1 — Check installation
draftmachine --version
If the command is not found, install it:
pip install draftmachine
Step 2 — Check Gmail credentials
Two files must exist:
| File | Purpose |
|---|
~/.draftmachine/client_secret.json | OAuth app credential downloaded from Google Cloud Console |
~/.draftmachine/creds.json | Cached OAuth token (created automatically by draftmachine setup) |
Check for them:
ls ~/.draftmachine/
If client_secret.json is missing — walk the user through GCP setup
Tell the user they need to do a one-time setup to connect DraftMachine to their Gmail:
- Go to Google Cloud Console and create a project (or pick an existing one).
- Navigate to APIs & Services → Enable APIs & Services and enable the Gmail API.
- Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
- Choose Desktop app as the application type.
- Click Download JSON and save the file to
~/.draftmachine/client_secret.json.
- You may need to
mkdir ~/.draftmachine first.
- Run
draftmachine setup — this opens a browser window, asks for Gmail permission (draft-only scope), and saves the token.
If client_secret.json exists but creds.json is missing
Run draftmachine setup to complete the OAuth consent flow.
If both files exist
Credentials are ready — skip to Step 3.
Step 3 — Gather the recipient list and compose the template
CSV file
The CSV needs at minimum an email column (default column name: email). Any other columns become
available as template variables. Ask the user what data they have. If they paste data in the
conversation, write it to a .csv file.
Example:
email,first_name,company
jane@example.com,Jane,Acme Corp
bob@example.com,Bob,
Markdown template
The template is a .md file with a YAML frontmatter block for the subject line and a Markdown
body using Jinja2 syntax. Ask the user what the email
should say, then write the template.
---
subject: "Quick note for {{ first_name }}"
---
Hi {{ first_name }},
{% if company %}
I came across {{ company }} and thought you might find this useful.
{% endif %}
[Body of the message here]
Best,
[Sender name]
Tips for good templates:
- Use
{{ variable }} to insert CSV column values.
- Wrap optional content in
{% if variable %}...{% endif %} so missing values don't cause awkward blanks.
- The subject line supports Jinja2 too.
- Filters like
{{ first_name | title }} and loops are supported.
Step 4 — Preview before creating drafts
Always run --preview first. It renders the first row only to the terminal — no API calls, no
drafts created. This is a fast sanity check for template errors and formatting.
draftmachine send list.csv template.md --preview
If the rendered output looks right, proceed. If there are errors (undefined variables, broken
conditionals, etc.), fix the template and re-preview.
Step 5 — Create the drafts
Once the preview looks good:
draftmachine send list.csv template.md
If the email address is in a column other than email, use --to-column:
draftmachine send list.csv template.md --to-column work_email
DraftMachine uses a two-pass strategy: it renders all rows first (aborting early if any row
has template errors), then creates all drafts via the Gmail API. This means it's all-or-nothing
per run — no partial draft batches on template errors.
Step 6 — Report back
After the command completes, tell the user:
- How many drafts were created.
- That the drafts are in their Gmail Drafts folder, ready to review and send.
- A reminder to check for any rows that were skipped (DraftMachine warns about empty/missing
to addresses in the terminal output).
Error reference
| Error | Fix |
|---|
command not found: draftmachine | pip install draftmachine |
No such file: client_secret.json | Complete GCP + OAuth setup (Step 2) |
403 Forbidden | OAuth token lacks correct scope — re-run draftmachine setup |
429 Too Many Requests | Gmail API rate limit hit; DraftMachine retries 3× with backoff. If it persists, wait and re-run |
UndefinedError: '...' is undefined | CSV column name in template doesn't match actual column header |
| Partial drafts on 429 | No resume; re-run the full command after a short wait (may create duplicates — delete extra drafts) |
