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

post/v1/email-templates

Create an email template

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

Requires email_templates:w.

Request body

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

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. 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.templates.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.templates.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.templates.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.templates.update()

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. 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. 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.
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 { error } = await honkio.templates.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.templates.remove()

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.
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 { error } = await honkio.templates.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.templates.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.
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.templates.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.templates.rollback()

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.
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.templates.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.templates.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.templates.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"