Templates

Parts

A template is made of parts, one for each channel you send on. Variables are written {{ code }} and work the same in every part. Declare every variable the template uses, each with an optional fallback: a send that leaves one without a value or a fallback is refused and lists the missing keys. A template needs at least one part.

SMS part: one plain text, up to 1,600 characters before the variables are filled in. The dashboard editor shows the segment count of the filled-in text as you type.

Email part: a subject, and an html body, a text body or both. Variable values are always HTML escaped in html.

Push part: a body, and an optional title. Both are plain text.

Languages and fallback

Each part can be written in English (en), in French (fr) or in both. The template has a default language: en, unless you set it to fr. A part in the other language needs the same part in the default language, or the API answers 422 VALIDATION_ERROR and names the path, such as parts.fr.sms.

A send names its language in the language field, or leaves it out for the default language. The choice is made part by part: if the language has the part for the channel being sent, that part is used; if not, the default language's part is used. A French send of a template with no French SMS part sends the English SMS text, and never fails over a missing translation. Only when no language has the part for the channel does the send answer 422 TEMPLATE_CHANNEL_MISSING.

Create, publish and roll back

Edits save to a draft. Publishing makes the draft the next numbered version, with every part in both languages, and live sends then use it. Rolling back publishes an old version again as a new one. A send with a test key renders the draft, published or not. Publishing, rolling back and deleting need a live key. You can also edit templates on the Templates page of the dashboard, which previews each part.

# Create a draft: an SMS part in English and in French
curl -X POST https://api.honkio.ca/v1/templates -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sign-in code", "alias": "signin-code",
        "variables": [{ "key": "code" }],
        "parts": {
          "en": { "sms": { "text": "Your code is {{ code }}" } },
          "fr": { "sms": { "text": "Votre code est {{ code }}" } }
        } }'

# Publish it as version 1
curl -X POST https://api.honkio.ca/v1/templates/signin-code/publish -H "Authorization: Bearer mk_live_YOUR_KEY"

Sending with a template

Name the template by id or alias in template, give its values in variables and, if you want one, a language. A request carries a template or its own content, not both.

SMS: POST /v1/messages takes template, variables and language in place of body. The rendered text is what is stored and sent, and consent, opt-outs, sending limits and pricing apply exactly as for any other message. A group send, POST /v1/contact-groups/{id}/messages, takes them too and renders the text once, with the same values, for every member.

# Send the French text by SMS
curl -X POST https://api.honkio.ca/v1/messages -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14165551234", "template": "signin-code",
        "variables": { "code": "482913" }, "language": "fr" }'

Push: POST /v1/push takes template, variables and language in place of title and body, and renders the template's push part.

# The template's push part, as a push notification
curl -X POST https://api.honkio.ca/v1/push -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "app_id": "APP_ID", "to": { "user_id": "user_1042" }, "template": "signin-code",
        "variables": { "code": "482913" }, "language": "fr" }'

Email: POST /v1/emails takes the template as before, with its id and variables, and now a language field. The batch endpoint takes language too.

# The template's email part, in French
curl -X POST https://api.honkio.ca/v1/emails -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "noreply@mail.acme.ca", "to": "ada@example.com",
        "template": { "id": "signin-code", "variables": { "code": "482913" } },
        "language": "fr" }'

Limits

An account holds up to 200 templates, counting those made through /v1/email-templates, which shares the same templates and lists only those that have an email part. Creating one past 200 answers 422 TEMPLATE_LIMIT_REACHED: delete one first.

Templates are included at no extra charge.