CLI and MCP for agents

Quick start (CLI)

Dry-run first — it connects to nothing and sends nothing, it just shows you exactly what would be sent. The CSV needs a header row; the email column is auto-detected and every header is available to your template as a merge field.

npx @robindarlington/mail-merge --csv data.csv --template msg.txt

Dry-run, test, send

The default run is a dry-run. Add --test you@example.com to send the whole batch to a single address as a full rehearsal, then --send to deliver one personalized email per recipient. SMTP details are read from the environment, never from flags — the password never lands in argv, shell history, or logs. Connection is verified with transport.verify() before any message is sent.

Use it from an MCP client

Add this to your MCP client (for example Claude Desktop's config) to expose the engine as typed tools:

{
  "mcpServers": {
    "mail-merge": {
      "command": "npx",
      "args": ["-y", "@robindarlington/mail-merge", "mcp"]
    }
  }
}

The server exposes four tools: validate-csv (columns, row count, detected email column, invalid-email count), preview-merge (the merged subject and body per row — read-only, sends nothing), test-send (send the whole batch to one address), and send (one personalized email per row).

Live send is deliberately gated so an agent cannot fire a batch in a single step. The first send call returns a preview plus a one-time confirmToken and delivers nothing; the second call must echo that exact token with identical parameters to actually deliver. A replayed, unknown, or mismatched token is refused.