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

# Create a template

`POST /email/templates`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/email/templates`
- Auth: HTTP bearer

Create a reusable email template from `html` (and optional `subject`). `{{variables}}` in the HTML fill per-recipient at send time. The body is stored in code mode so you can open it in the dashboard. Once created, send with it via [Send or schedule an email](#post-email), and iterate with [Update a template](#patch-email-templates-id). Requires the `templates:write` capability.

## Request body

- TemplateCreate: Create a template. The body is EXACTLY ONE of `html` (designed or raw HTML) or `text` (a Simple, Gmail-style plain email) — the spec can't express this exclusivity, so `required` lists only `name`; a request with neither or both is rejected with 422.
  - `name` string, required
  - `subject` string
  - `html` string: The email body as HTML (makes the template kind `designed`; compose with @unitpost/email `render()` or any HTML; `{{variables}}` fill at send). Pass exactly one of `html` or `text`.
  - `text` string: Simple email body instead of `html` (makes the template kind `simple`) — plain text exactly as you'd type it into Gmail: lines, a blank line between paragraphs (the only spacing), '- ' or '1. ' list items, inline <b>, <i>, <u>, <s>, <a href="…">, <br>, and <span style="color:#hex; background-color:#hex; font-size:13px|18px|24px; font-family:Georgia"> for colour, highlight, size and font; <div style="text-align:center">…</div> around one line to centre it; <img src="/img/{id}" alt="…" width="400"> alone on a line for an image; {{variables}}. Not supported (removed): headings, layout/sections/buttons, block HTML tags (p, div, table, ul), other CSS, and Markdown (stays literal). Sent as a bare mail-client fragment with no layout; marketing templates get a one-line unsubscribe footer at send time. Max 20,000 characters. Pass exactly one of `html` or `text`.
  - `category` 'transactional' | 'marketing'

## Response `201`

Created.

- Template
  - `object` 'template', required
  - `id` string, required
  - `name` string, required
  - `subject` string, nullable, required
  - `status` 'draft' | 'published', required
  - `kind` 'simple' | 'designed', required: Which kind of email this is. `simple`: a plain, personal email (the dashboard's Simple editor) — update its body with `text`. `designed`: a designed or raw-HTML email (the Design / Code editor) — update its body with `html`. Sending the other field converts the template to that kind, so keep the kind unless the user asked to switch.
  - `html` string, nullable
  - `warnings` string[]: Create or update with `text` only: markup or styling the Simple format doesn't support that was removed or couldn't be used (an unsupported tag, CSS property or font, an image that can't be sent), in plain words. Absent when nothing was.
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `401`: Missing or invalid API key.
- `422`: Validation error.

---

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