---
title: "Create a template"
method: POST
path: "/api/templates.create"
---

# Create a template

`POST /api/templates.create`

Creates a new template. Each template must have a channel (email or web) with corresponding channel-specific content.

## Request body

- CreateTemplateRequest
  - `workspace_id` string, required — The ID of the workspace
  - `id` string, required — Unique identifier for the template (alphanumeric, underscores, and hyphens only)
  - `name` string, required — Name of the template
  - `channel` 'email' | 'web', required — Communication channel
  - `email` EmailTemplate
    - `sender_id` string — ID of the sender configuration to use
    - `reply_to` string, email — Reply-To email address
    - `subject` string, required — Email subject line (supports Liquid templating)
    - `subject_preview` string, nullable — Preview text shown in email clients
    - `compiled_preview` string, required — Compiled HTML preview of the email
    - `visual_editor_tree` object, required — MJML visual editor tree structure
    - `text` string, nullable — Plain text version of the email
  - `web` WebTemplate
    - `content` object, required — Tiptap JSON content (source of truth for web templates)
    - `html` string — Pre-rendered HTML for display
    - `plain_text` string — Extracted text for search indexing
  - `category` 'marketing' | 'transactional' | 'welcome' | 'opt_in' | 'unsubscribe' | 'bounce' | 'blocklist' | 'blog' | 'other', required — Template category
  - `template_macro_id` string, nullable — ID of the template macro (layout) to use
  - `test_data` object — Test data for template preview
  - `settings` object — Channel-specific settings

## Response `201`

Template created successfully

- object
  - `template` Template
    - `id` string, required — Unique identifier for the template (alphanumeric, underscores, and hyphens only)
    - `name` string, required — Name of the template
    - `version` integer — Version number of the template
    - `channel` 'email' | 'web', required — Communication channel
    - `email` EmailTemplate
      - `sender_id` string — ID of the sender configuration to use
      - `reply_to` string, email — Reply-To email address
      - `subject` string, required — Email subject line (supports Liquid templating)
      - `subject_preview` string, nullable — Preview text shown in email clients
      - `compiled_preview` string, required — Compiled HTML preview of the email
      - `visual_editor_tree` object, required — MJML visual editor tree structure
      - `text` string, nullable — Plain text version of the email
    - `web` WebTemplate
      - `content` object, required — Tiptap JSON content (source of truth for web templates)
      - `html` string — Pre-rendered HTML for display
      - `plain_text` string — Extracted text for search indexing
    - `category` 'marketing' | 'transactional' | 'welcome' | 'opt_in' | 'unsubscribe' | 'bounce' | 'blocklist' | 'blog' | 'other', required — Template category
    - `template_macro_id` string, nullable — ID of the template macro (layout) to use
    - `integration_id` string, nullable — ID of the integration managing this template (e.g., Supabase)
    - `test_data` object — Test data for template preview
    - `settings` object — Channel-specific third-party settings
    - `created_at` string, date-time — When the template was created
    - `updated_at` string, date-time — When the template was last updated
    - `deleted_at` string, date-time, nullable — When the template was deleted (null if active)

## Other responses

- `400` — Bad request - validation failed
- `401` — Unauthorized - invalid or missing authentication token
- `500` — Internal server error

## Changes

- **2025-12-01** `bca4a43d9d46` — 2 info
  - added the new optional request property `email/text`
  - added the optional property `template/email/text` to the response with the `201` status
- **2025-11-14** `940c5636d0b4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/pierre-b/apis/notifuse-api/changes/api/templates.create/post.md)

---

[API](https://skmtc.dev/pierre-b/apis/notifuse-api.md) · [All operations](https://skmtc.dev/pierre-b/apis/notifuse-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pierre-b/notifuse-api/revisions/d26605f2fc47/schema)