Templates

A template is a reusable subject and body with variables in it. Every new account starts with five: welcome, verify email, password reset, payment receipt, and a product update.

Sending one

curl -X POST https://app.mailstein.com/api/v1/emails \
  -H "Authorization: Bearer $MAILSTEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "someone@example.com",
    "templateId": "cmsm9pt1b0017vseua7veqnqi",
    "variables": { "firstName": "Sam", "companyName": "Acme" }
  }'

subject and html are not needed when you pass a templateId — they come from the template. Pass a subject anyway and it overrides the template's.

Variables

Written {{firstName}} in the subject or the body, and substituted from variables at send time.

A variable with no value substitutes to an empty string, which is how an email ends up reading "Hi ," in someone's inbox. Give every variable a fallback in the editor, and prefer "Hi there" over a name you might not have.

Creating one over the API

curl -X POST https://app.mailstein.com/api/v1/templates \
  -H "Authorization: Bearer $MAILSTEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Welcome","subject":"Welcome to {{companyName}}","content":"{\"type\":\"doc\",\"content\":[...]}"}'

content is the editor's document format. The HTML is rendered from it and returned on the response — you cannot set the HTML directly, on purpose: a template whose stored HTML disagrees with its stored content previews as one thing and arrives as another, and there is no way to tell afterwards which one was right.

If you want to send arbitrary HTML, do not use a template. Pass html to POST /v1/emails instead.

From the CLI

npx -y mailstein-cli emails send \
  --from hello@yourdomain.com \
  --to someone@example.com \
  --template cmsm9pt1b0017vseua7veqnqi \
  --var firstName=Sam --var companyName=Acme

--var is repeatable, and --to is too.

Templates and broadcasts

A broadcast carries its own body rather than referencing a template. Reusing a template across many broadcasts is not currently possible; duplicate the template and edit the copy.