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:

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 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
[email protected],Jane,Acme Corp
[email protected],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