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:

~/.draftmachine/client_secret.json

~/.draftmachine/creds.json

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:

1. Go to Google Cloud Console and create a project (or pick an existing one).
2. Navigate to APIs & Services → Enable APIs & Services and enable the Gmail API.
3. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
4. Choose Desktop app as the application type.
5. Click Download JSON and save the file to

   ~/.draftmachine/client_secret.json

   .
   • You may need to

     mkdir ~/.draftmachine

     first.
6. 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

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

.csv

Example:

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

Markdown template

The template is a

.md

---
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

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

--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

command not found: draftmachine

pip install draftmachine

No such file: client_secret.json

403 Forbidden

draftmachine setup

429 Too Many Requests

UndefinedError: '...' is undefined