API reference

Email templates

Store email templates and publish versions to send by id or alias.

get/v1/email-templates

List email templates

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

Requires email_templates:r.

Responses

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.
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.emailTemplates.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/email-templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/email-templates

Create an email template

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

Saves a draft. A live send uses a template once it is published; a send with a test key renders the draft, published or not, so a test key can build and try a template without publishing it. An account holds up to 200 templates, counting those made through /v1/templates (EMAIL_TEMPLATE_LIMIT_REACHED past that).

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
`subject`required	string	Up to 998 characters on one line. Surrounding whitespace is trimmed, and a line break or other control character becomes a space. Variables go in double braces, such as {{ first_name }}. At least 1 characters At most 998 characters
`html`	string	The HTML body. A template needs html, text or both. Variable values are always HTML escaped. Can be null
`text`	string	The plain text body. Can be null
`from`	string	The default sender. A send can set its own. Can be null
`reply_to`	string \| string[]	The default reply address: a string or an array. A send can set its own.
`variables[]`	object[]	Every variable the template uses, 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

Responses

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.
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.emailTemplates.create({
  name: 'Shipping update',
  alias: 'shipping-update',
  subject: 'Your order is on its way, {{ firstName }}',
  html: '<p>Hi {{ firstName }}, your order has shipped.</p>',
  variables: [{ key: 'firstName', fallback: 'there' }],
})
if (error) throw new Error(error.message)
console.log(template.id)

curl -X POST https://api.honkio.ca/v1/email-templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shipping update",
    "alias": "shipping-update",
    "subject": "Your order is on its way, {{ firstName }}",
    "html": "<p>Hi {{ firstName }}, your order has shipped.</p>",
    "variables": [
      {
        "key": "firstName",
        "fallback": "there"
      }
    ]
  }'

get/v1/email-templates/{idOrAlias}

Get an email template by id or alias

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

Requires email_templates:r.

Parameters

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

Responses

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.
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.emailTemplates.get('shipping-update')
if (error) throw new Error(error.message)
console.log(data.published_version, data.has_unpublished_changes)

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

patch/v1/email-templates/{idOrAlias}

Edit an email template draft

Permissionemail_templates:mNode.js SDKhonkio.emailTemplates.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
`subject`	string	Up to 998 characters on one line. Surrounding whitespace is trimmed, and a line break or other control character becomes a space. Variables go in double braces, such as {{ first_name }}. At least 1 characters At most 998 characters
`html`	string	The HTML body. A template needs html, text or both. Variable values are always HTML escaped. Can be null
`text`	string	The plain text body. Can be null
`from`	string	The default sender. A send can set its own. Can be null
`reply_to`	string \| string[]	The default reply address: a string or an array. A send can set its own.
`variables[]`	object[]	Every variable the template uses, 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

Responses

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.
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.emailTemplates.update('shipping-update', { subject: 'Shipped: your order, {{ firstName }}' })
if (error) throw new Error(error.message)

curl -X PATCH https://api.honkio.ca/v1/email-templates/ID_OR_ALIAS \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Shipped: your order, {{ firstName }}"
  }'

delete/v1/email-templates/{idOrAlias}

Delete an email template and its versions

Permissionemail_templates:dNode.js SDKhonkio.emailTemplates.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

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.
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.emailTemplates.remove('shipping-update')
if (error) throw new Error(error.message)

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

post/v1/email-templates/{idOrAlias}/publish

Publish the draft as a new version

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

Live sends use the new version 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

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.
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.emailTemplates.publish('shipping-update')
if (error) throw new Error(error.message)
console.log(data.published_version)

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

post/v1/email-templates/{idOrAlias}/rollback

Publish an earlier version again as a new version

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

Replaces the draft 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/email-templates/{idOrAlias}/versions. Minimum: 1 Maximum: 9007199254740991

Responses

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.
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.emailTemplates.rollback('shipping-update', { version: 2 })
if (error) throw new Error(error.message)
console.log(data.published_version)

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

get/v1/email-templates/{idOrAlias}/versions

List published versions, newest first

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

Requires email_templates:r.

Parameters

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

Responses

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.
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.emailTemplates.versions('shipping-update')
if (error) throw new Error(error.message)
for (const v of data.data) console.log(v.version, v.current)

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