---
title: "Create an email template"
method: POST
path: "/v1/email-templates"
tags: ["Email Templates"]
---

# Create an email template

`POST /v1/email-templates`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/email-templates`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

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.

Requires `email_templates:w`.

## Request body

- object: A new template. It saves as a draft: publish it before sending with it from a live key.
  - `name` string, required: A label for you, up to 200 characters.
  - `alias` string, nullable: Send with it instead of the id: 1 to 63 lowercase letters, digits, - or _, starting with a letter or digit. Null removes it.
  - `subject` string, required: Up to 998 characters. Variables go in double braces, such as {{ first_name }}.
  - `html` string, nullable: The HTML body. A template needs html, text or both. Variable values are always HTML escaped.
  - `text` string, nullable: The plain text body.
  - `from` string, nullable: The default sender. A send can set its own.
  - `reply_to` union: The default reply address: a string or an array. A send can set its own.
    - string, email
    - string[]
  - `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` string, required: The variable's name: up to 64 characters.
    - `fallback` string: Used when a send gives no value: up to 1000 characters.

## Other responses

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

---

[API](https://skmtc.dev/honkio/apis/honkio-api.md) · [All operations](https://skmtc.dev/honkio/apis/honkio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/honkio/apis/honkio-api/revisions/ce4ed3fe9691?raw)