API reference

Templates

Store templates with a part per channel, in English and French, and publish versions to send by id or alias.

get/v1/templates

List templates

Permissionemail_templates:rNode.js SDKhonkio.templates.list()

Every template, newest first, with which parts each language has. GET /v1/templates/{idOrAlias} returns a template's content.

Requires email_templates:r.

Responses

200A page of templates, newest first, without their parts' content.

Field	Type	Description
`data[]`required	object[]
`id`required	string
`object`required	string	One of: template
`name`required	string
`alias`required	string	Can be null
`default_language`required	string	One of: en \| fr
`parts`required	object	Which parts each language has: the default language always, the other one when it has a part.
`en`	object	Which parts one language has.
`email`required	boolean	Whether this language has an email part.
`sms`required	boolean	Whether this language has an SMS part.
`fr`	object	Which parts one language has.
`email`required	boolean	Whether this language has an email part.
`sms`required	boolean	Whether this language has an SMS part.
`published_version`required	integer	The version live sends use. Null until the first publish. Can be null
`has_unpublished_changes`required	boolean	True when the draft differs from the published version in any part or language.
`created_at`required	string	Format: date-time
`updated_at`required	string	Format: date-time
`has_more`required	boolean
`next_cursor`required	string	Pass it as cursor for the next page. Null on the last page. Can be null

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data, error } = await honkio.templates.list({ limit: 20 })
if (error) throw new Error(error.message)
for (const t of data.data) console.log(t.alias, t.published_version)

curl https://api.honkio.ca/v1/templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/templates

Create a template

Permissionemail_templates:wNode.js SDKhonkio.templates.create()

Saves a draft with a part for each channel you send it on, in English, French or both. A live send uses a template once it is published; a send with a test key renders the draft, published or not. An account holds up to 200 templates, counting those made through /v1/email-templates.

Requires email_templates:w.

Request body

A new template. It saves as a draft: publish it before sending with it from a live key.

Field	Type	Description
`name`required	string	A label for you, up to 200 characters. At least 1 characters At most 200 characters
`alias`	string	Send with it instead of the id: 1 to 63 lowercase letters, digits, - or _, starting with a letter or digit. Null removes it. Default: null Can be null
`default_language`	string	The language a send uses when it names none, and the one whose parts fill in for a part the other language lacks. en unless you set fr. One of: en \| fr Default: en
`from_address`	string	The default email sender. A send can set its own. Can be null
`reply_to`	string \| string[]	The default email reply address: a string or an array. A send can set its own.
`variables[]`	object[]	Every variable the template uses, in any part or language, each optionally with a fallback. A send that leaves one with neither a value nor a fallback is refused. Default: []
`key`required	string	The variable's name: up to 64 characters. At least 1 characters At most 64 characters
`fallback`	string	Used when a send gives no value: up to 1000 characters. At most 1000 characters
`parts`required	object	The template's parts by language: en, fr or both. The default language needs at least one part, and the other language can only have parts the default language has. A send in a language uses that language's part for the channel, else the default language's.
`en`	object	The English parts.
`email`	object	The email part: a subject and an html body, a text body or both. Can be null
`subject`required	string	Up to 998 characters on one line. Variables go in double braces, such as {{ first_name }}. At least 1 characters At most 998 characters
`html`	string	The HTML body, up to 2 MB. Variable values are always HTML escaped. Can be null
`text`	string	The plain text body, up to 2 MB. Can be null
`sms`	object	The SMS part. Can be null
`text`required	string	Plain text, up to 1600 characters before variables are filled in. At least 1 characters At most 1600 characters
`fr`	object	The French parts.
`email`	object	The email part: a subject and an html body, a text body or both. Can be null
`subject`required	string	Up to 998 characters on one line. Variables go in double braces, such as {{ first_name }}. At least 1 characters At most 998 characters
`html`	string	The HTML body, up to 2 MB. Variable values are always HTML escaped. Can be null
`text`	string	The plain text body, up to 2 MB. Can be null
`sms`	object	The SMS part. Can be null
`text`required	string	Plain text, up to 1600 characters before variables are filled in. At least 1 characters At most 1600 characters

Responses

201The template, a draft.

Field	Type	Description
`id`required	string
`object`required	string	One of: template
`name`required	string
`alias`required	string	Can be null
`default_language`required	string	The language a send uses when it names none, and the one whose parts fill in for a part the other language lacks. One of: en \| fr
`variables[]`required	object[]
`key`required	string
`fallback`	string	Used when a send gives no value. Absent when the variable has none.
`from_address`required	string	The default email sender. Can be null
`reply_to`required	string[]
`parts`required	object	The draft's parts by language: the default language always, the other one when it has a part.
`en`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`fr`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`published_version`required	integer	The version live sends use. Null until the first publish. Can be null
`has_unpublished_changes`required	boolean	True when the draft differs from the published version in any part or language.
`created_at`required	string	Format: date-time
`updated_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
409EMAIL_TEMPLATE_ALIAS_TAKEN: another template on this account already uses this alias.The standard error body.
422VALIDATION_ERROR (details names the field, such as parts.en.sms.text), EMAIL_TEMPLATE_UNDECLARED_VARIABLE (details.keys) or TEMPLATE_LIMIT_REACHED (200 templates per account, email templates included).The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data: template, error } = await honkio.templates.create({
  name: 'Appointment reminder',
  alias: 'appointment-reminder',
  variables: [{ key: 'time' }],
  parts: {
    en: { sms: { text: 'Reminder: your appointment is at {{ time }}.' } },
    fr: { sms: { text: 'Rappel : votre rendez-vous est à {{ time }}.' } },
  },
})
if (error) throw new Error(error.message)
console.log(template.id)

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": "sign-in-code",
    "variables": [
      {
        "key": "code"
      }
    ],
    "parts": {
      "en": {
        "sms": {
          "text": "Your Acme code is {{ code }}"
        }
      },
      "fr": {
        "sms": {
          "text": "Votre code Acme est {{ code }}"
        }
      }
    }
  }'

get/v1/templates/{idOrAlias}

Get a template by id or alias

Permissionemail_templates:rNode.js SDKhonkio.templates.get()

Requires email_templates:r.

Parameters

Parameter	Type	Description
`idOrAlias`requiredpath	string	At least 1 characters At most 200 characters

Responses

200The template.

Field	Type	Description
`id`required	string
`object`required	string	One of: template
`name`required	string
`alias`required	string	Can be null
`default_language`required	string	The language a send uses when it names none, and the one whose parts fill in for a part the other language lacks. One of: en \| fr
`variables[]`required	object[]
`key`required	string
`fallback`	string	Used when a send gives no value. Absent when the variable has none.
`from_address`required	string	The default email sender. Can be null
`reply_to`required	string[]
`parts`required	object	The draft's parts by language: the default language always, the other one when it has a part.
`en`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`fr`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`published_version`required	integer	The version live sends use. Null until the first publish. Can be null
`has_unpublished_changes`required	boolean	True when the draft differs from the published version in any part or language.
`created_at`required	string	Format: date-time
`updated_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/templates/ID_OR_ALIAS \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

patch/v1/templates/{idOrAlias}

Edit a template draft

Permissionemail_templates:mNode.js SDKhonkio.templates.update()

Changes the draft. Live sends keep the published version until you publish again; a send with a test key renders the draft. The alias is not part of the draft: a change to it applies to sends at once, so on a template with a published version a test key cannot change it (LIVE_KEY_REQUIRED).

Requires email_templates:m.

Parameters

Parameter	Type	Description
`idOrAlias`requiredpath	string	At least 1 characters At most 200 characters

Request body

The fields to change in the draft. Live sends keep using the published version until you publish again.

Field	Type	Description
`name`	string	A label for you, up to 200 characters. At least 1 characters At most 200 characters
`alias`	string	Send with it instead of the id: 1 to 63 lowercase letters, digits, - or _, starting with a letter or digit. Null removes it. Can be null
`default_language`	string	The language a send uses when it names none, and the one whose parts fill in for a part the other language lacks. en unless you set fr. One of: en \| fr
`from_address`	string	The default email sender. A send can set its own. Can be null
`reply_to`	string \| string[]	The default email reply address: a string or an array. A send can set its own.
`variables[]`	object[]	Every variable the template uses, in any part or language, each optionally with a fallback. A send that leaves one with neither a value nor a fallback is refused.
`key`required	string	The variable's name: up to 64 characters. At least 1 characters At most 64 characters
`fallback`	string	Used when a send gives no value: up to 1000 characters. At most 1000 characters
`parts`	object	The template's parts by language: en, fr or both. The default language needs at least one part, and the other language can only have parts the default language has. A send in a language uses that language's part for the channel, else the default language's. Each part you name replaces that part, null removes it, and parts you leave out are kept. A language set to null loses all its parts.
`en`	object	The English parts. Can be null
`email`	object	The email part: a subject and an html body, a text body or both. Can be null
`subject`required	string	Up to 998 characters on one line. Variables go in double braces, such as {{ first_name }}. At least 1 characters At most 998 characters
`html`	string	The HTML body, up to 2 MB. Variable values are always HTML escaped. Can be null
`text`	string	The plain text body, up to 2 MB. Can be null
`sms`	object	The SMS part. Can be null
`text`required	string	Plain text, up to 1600 characters before variables are filled in. At least 1 characters At most 1600 characters
`fr`	object	The French parts. Can be null
`email`	object	The email part: a subject and an html body, a text body or both. Can be null
`subject`required	string	Up to 998 characters on one line. Variables go in double braces, such as {{ first_name }}. At least 1 characters At most 998 characters
`html`	string	The HTML body, up to 2 MB. Variable values are always HTML escaped. Can be null
`text`	string	The plain text body, up to 2 MB. Can be null
`sms`	object	The SMS part. Can be null
`text`required	string	Plain text, up to 1600 characters before variables are filled in. At least 1 characters At most 1600 characters

Responses

200The template with its edited draft.

Field	Type	Description
`id`required	string
`object`required	string	One of: template
`name`required	string
`alias`required	string	Can be null
`default_language`required	string	The language a send uses when it names none, and the one whose parts fill in for a part the other language lacks. One of: en \| fr
`variables[]`required	object[]
`key`required	string
`fallback`	string	Used when a send gives no value. Absent when the variable has none.
`from_address`required	string	The default email sender. Can be null
`reply_to`required	string[]
`parts`required	object	The draft's parts by language: the default language always, the other one when it has a part.
`en`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`fr`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`published_version`required	integer	The version live sends use. Null until the first publish. Can be null
`has_unpublished_changes`required	boolean	True when the draft differs from the published version in any part or language.
`created_at`required	string	Format: date-time
`updated_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403LIVE_KEY_REQUIRED: a test key cannot change the alias of a template that has a published version, because live sends may use the alias. It can edit every other field of the draft. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
409EMAIL_TEMPLATE_ALIAS_TAKEN: another template on this account already uses this alias.The standard error body.
422VALIDATION_ERROR (details names the field) or EMAIL_TEMPLATE_UNDECLARED_VARIABLE (details.keys).The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { error } = await honkio.templates.update('appointment-reminder', {
  parts: { fr: { sms: { text: 'Rappel : rendez-vous à {{ time }}.' } } },
})
if (error) throw new Error(error.message)

curl -X PATCH https://api.honkio.ca/v1/templates/ID_OR_ALIAS \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": {
      "fr": {
        "sms": {
          "text": "Votre code Acme : {{ code }}"
        }
      }
    }
  }'

delete/v1/templates/{idOrAlias}

Delete a template and its versions

Permissionemail_templates:dNode.js SDKhonkio.templates.remove()

Sends that name the template then answer NOT_FOUND. Refused with EMAIL_TEMPLATE_IN_USE while a scheduled email uses it. Live keys only (LIVE_KEY_REQUIRED).

Requires email_templates:d.

Parameters

Parameter	Type	Description
`idOrAlias`requiredpath	string	At least 1 characters At most 200 characters

Responses

204Deleted, with its versions.
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403LIVE_KEY_REQUIRED: templates have no test mode, and this changes what live sends get. A test key can create a template, edit its draft and send test emails that render the draft. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
409EMAIL_TEMPLATE_IN_USE: a scheduled email uses this template.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X DELETE https://api.honkio.ca/v1/templates/ID_OR_ALIAS \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/templates/{idOrAlias}/publish

Publish the draft as a new version

Permissionemail_templates:mNode.js SDKhonkio.templates.publish()

The new version holds every part in every language. Live sends use it at once. Live keys only (LIVE_KEY_REQUIRED): a send with a test key renders the draft and needs no publish.

Requires email_templates:m.

Parameters

Parameter	Type	Description
`idOrAlias`requiredpath	string	At least 1 characters At most 200 characters

Responses

200The template, with the new version published. When nothing changed since the last publish, the template as it is, with no new version.

Field	Type	Description
`id`required	string
`object`required	string	One of: template
`name`required	string
`alias`required	string	Can be null
`default_language`required	string	The language a send uses when it names none, and the one whose parts fill in for a part the other language lacks. One of: en \| fr
`variables[]`required	object[]
`key`required	string
`fallback`	string	Used when a send gives no value. Absent when the variable has none.
`from_address`required	string	The default email sender. Can be null
`reply_to`required	string[]
`parts`required	object	The draft's parts by language: the default language always, the other one when it has a part.
`en`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`fr`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`published_version`required	integer	The version live sends use. Null until the first publish. Can be null
`has_unpublished_changes`required	boolean	True when the draft differs from the published version in any part or language.
`created_at`required	string	Format: date-time
`updated_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403LIVE_KEY_REQUIRED: templates have no test mode, and this changes what live sends get. A test key can create a template, edit its draft and send test emails that render the draft. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X POST https://api.honkio.ca/v1/templates/ID_OR_ALIAS/publish \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/templates/{idOrAlias}/rollback

Publish an earlier version again as a new version

Permissionemail_templates:mNode.js SDKhonkio.templates.rollback()

Replaces the draft, every part and language, with the earlier version and publishes it. Live keys only (LIVE_KEY_REQUIRED).

Requires email_templates:m.

Parameters

Parameter	Type	Description
`idOrAlias`requiredpath	string	At least 1 characters At most 200 characters

Request body

The version to publish again.

Field	Type	Description
`version`required	integer	A published version number, from GET /v1/templates/{idOrAlias}/versions. Minimum: 1 Maximum: 9007199254740991

Responses

200The template, with the earlier version published again as a new version.

Field	Type	Description
`id`required	string
`object`required	string	One of: template
`name`required	string
`alias`required	string	Can be null
`default_language`required	string	The language a send uses when it names none, and the one whose parts fill in for a part the other language lacks. One of: en \| fr
`variables[]`required	object[]
`key`required	string
`fallback`	string	Used when a send gives no value. Absent when the variable has none.
`from_address`required	string	The default email sender. Can be null
`reply_to`required	string[]
`parts`required	object	The draft's parts by language: the default language always, the other one when it has a part.
`en`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`fr`	object	One language's parts. A send in this language uses its part for the channel when it has one, else the default language's.
`email`required	object \| any	The email part, or null when this language has none.
`sms`required	object \| any	The SMS part, or null when this language has none.
`published_version`required	integer	The version live sends use. Null until the first publish. Can be null
`has_unpublished_changes`required	boolean	True when the draft differs from the published version in any part or language.
`created_at`required	string	Format: date-time
`updated_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403LIVE_KEY_REQUIRED: templates have no test mode, and this changes what live sends get. A test key can create a template, edit its draft and send test emails that render the draft. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such template, or no such version of it.The standard error body.
422VALIDATION_ERROR: the request failed validation; details names the fields.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl -X POST https://api.honkio.ca/v1/templates/ID_OR_ALIAS/rollback \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 2
  }'

get/v1/templates/{idOrAlias}/versions

List a template's published versions, newest first

Permissionemail_templates:rNode.js SDKhonkio.templates.versions()

Requires email_templates:r.

Parameters

Parameter	Type	Description
`idOrAlias`requiredpath	string	At least 1 characters At most 200 characters

Responses

200The published versions, newest first.
Field Type Description
data[]required object[]
versionrequired integer
published_atrequired string
Format: date-time
currentrequired boolean
True for the version live sends use.
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

curl https://api.honkio.ca/v1/templates/ID_OR_ALIAS/versions \
  -H "Authorization: Bearer mk_live_YOUR_KEY"