Templates and variables

A template is a saved subject, HTML body and plain-text body with {{variables}} in them. You write it once in the dashboard and send it with POST /mail/send, passing only the recipient and the values. Templates belong to your account, so every site in the account can use them.

Create a template#

1. Open Templates in the dashboard (/app/templates).
2. Click + New template, or pick one from the Starter gallery and click Use this to copy it into your templates.
3. Fill in Name, Subject, HTML body and Plain-text body, then click Save.

The editor shows a preview of the saved HTML, the variables it found, and a Send via API box with a ready request for this template. Starter templates are read-only; a copy of one is named <name> (copy) and you can change it freely. Duplicate and Delete are on each template card.

Slug and ID#

You can refer to a template in two ways:

• Slug — shown on the template card as id: <slug> and in the Send via API box. It is made from the name when the template is created, for example order-shipped, and may get a short random ending if that slug is taken. Renaming the template later does not change the slug.
• ID — the UUID in the editor’s address, /app/templates/<id>.

Variables#

Write a variable as {{name}}. Spaces inside the braces are allowed ({{ name }}). Names can use letters, digits, _, . and -. Variables work in the subject, the HTML body and the plain-text body.

Subject:  Order {{order_id}} has shipped

HTML:     <p>Hi {{name}},</p>
          <p>Order {{order_id}} is on its way. Track it here:
             <a href="{{tracking_url}}">{{tracking_url}}</a></p>

Text:     Hi {{name}},

          Order {{order_id}} is on its way. Track it here: {{tracking_url}}

• data is a flat object. Keys are up to 64 characters; values are strings, numbers or booleans.
• A dot is part of the name, not a path: {{order.id}} reads the key "order.id". Nested objects in data are rejected with 400 invalid_payload.
• A variable with no value in data becomes an empty string.
• In the HTML body, values are HTML-escaped: <b> in a value shows as text, not bold. Put markup in the template, not in data. In the subject and the plain-text body, values are inserted as they are.

Send a template#

Replace order-shipped with your template’s slug or ID.

curl -X POST https://securessmtp.com/api/v1/mail/send \
  -H "x-securessmtp-api-key: $SECURESSMTP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "[email protected]",
  "template": "order-shipped",
  "data": {
    "name": "Ada",
    "order_id": 1001,
    "tracking_url": "https://example.com/track/1001"
  }
}'

How the request and the template combine

• The template’s HTML and text always replace html and text from the request.
• If the request has a non-empty subject, it is used as is. Otherwise the template’s subject is used, with its variables filled in.
• Everything else works as usual: to, cc, bcc, from, reply_to, headers, attachments and sender_mode. See Sending email.
• If the template has an empty plain-text body, we build the text part from the HTML. Filling in the plain-text body yourself is better for deliverability.

Errors#