---
title: "Create an email template (draft)"
method: POST
path: "/templates"
tags: ["Templates"]
---

# Create an email template (draft)

`POST /templates`

## Request

- Base URL: `https://api.supersendtx.com`
- URL: `https://api.supersendtx.com/templates`
- Auth: HTTP bearer

## Request body

- CreateTemplateRequest
  - `name` string, required
  - `subject` string: Optional default subject line. Omit for layout-only templates used with per-send subjects.
  - `format` 'html' | 'blocks'
  - `preheader` string
  - `html` string
  - `text` string
  - `design` object: Required when format is blocks (defaults to empty document, in the account's Brand colors when those are known). Supports `settings.globalCss` for author-supplied CSS compiled at render time.
  - `alias` string
  - `variables` string[]
  - `unsubscribe_enabled` boolean
  - `category` 'transactional' | 'product' | 'newsletter'

## Response `201`

Template created

- TemplateResponse
  - `template` Template, required
    - `id` string, uuid, required
    - `name` string, required
    - `alias` string, nullable, required: Optional unique alias per account (must not start with `stx_` or `rnl_`)
    - `status` 'draft' | 'published', required
    - `format` 'html' | 'blocks', required: html is legacy raw HTML; blocks is the visual builder document
    - `subject` string, required
    - `preheader` string, nullable: Inbox preview text injected as a hidden preheader
    - `html` string, nullable, required
    - `text` string, nullable, required
    - `design` object, nullable: TemplateDocument JSON when format is blocks. `settings.globalCss` accepts author-supplied CSS; bare-tag rules (body, p, h1, h2, h3, a, img, hr) are inlined on render and everything else is emitted into a style block.
    - `variables` string[], nullable, required: Variable names used in subject/html/text (auto-extracted for blocks)
    - `published_version_id` string, uuid, nullable: Immutable version snapshot used for sends
    - `published_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `unsubscribe_enabled` boolean, required: When true, sends using this published template inherit managed unsubscribe unless overridden with `unsubscribe` on `POST /emails`.
    - `category` 'transactional' | 'product' | 'newsletter', required: Email category for preference management. `transactional` is default and ignores category opt-outs. `product` and `newsletter` support category-scoped unsubscribe.
    - `warnings` TemplateLintWarning[]: Non-blocking deliverability hints for template HTML (e.g. SVG image URLs)
      - `code` 'svg_image' | 'relative_image_url' | 'data_uri_image' | 'missing_alt' | 'non_https_image' | 'empty_href' | 'raw_html_block' | 'low_contrast' | 'html_too_large', required
      - `message` string, required
      - `detail` string, nullable

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `409`: Name or alias conflict

---

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