draftmachine

# 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

```bash
draftmachine --version
```

If the command is not found, install it:

```bash
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:

```bash
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](https://console.cloud.google.com/) 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:
```csv
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](https://jinja.palletsprojects.com/) syntax. Ask the user what the email
should say, then write the template.

```markdown
---
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.

```bash
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:

```bash
draftmachine send list.csv template.md
```

If the email address is in a column other than `email`, use `--to-column`:

```bash
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) |