Metadata-Version: 2.4
Name: draftmachine
Version: 0.1.0
Summary: CLI mail merge tool that creates Gmail drafts from a CSV and Markdown template
License: MIT
Keywords: cli,email,gmail,mail-merge
Requires-Python: >=3.8
Requires-Dist: click>=8.0
Requires-Dist: google-api-python-client>=2.0
Requires-Dist: google-auth-oauthlib>=1.0
Requires-Dist: google-auth>=2.0
Requires-Dist: jinja2>=3.0
Requires-Dist: markdown>=3.0
Requires-Dist: python-frontmatter>=1.0
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install draftmachine
```

Or from source:

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

## Quick start

1. **Set up your GCP credential** (one-time):
   ```bash
   draftmachine setup
   ```

2. **Create a template** (`template.md`):
   ```markdown
   ---
   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`):
   ```csv
   email,first_name,company
   alice@example.com,Alice,Acme
   bob@example.com,Bob,Globex
   ```

4. **Preview before creating** (renders row 1, no API calls):
   ```bash
   draftmachine send list.csv template.md --preview
   ```

5. **Create the drafts**:
   ```bash
   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:

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

```bash
# 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](https://console.cloud.google.com/)
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

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

## License

MIT
