Templates

Create a template

POST https://demo.notifuse.com/api/templates.create

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

Authorizations

Authorization string header required

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Body application/json

workspace_id string required

The ID of the workspace

  • Example: ws_1234567890
id string required

Unique identifier for the template (alphanumeric, underscores, and hyphens only)

  • Maximum length: 32
  • Example: welcome_email
name string required

Name of the template

  • Maximum length: 255
  • Example: Welcome Email
channel string required

Communication channel

  • Available options: email, web
  • Example: email
email object
Show child attributes
editor_mode string

Which editor the email is written in. visual stores the drag-and-drop block tree in visual_editor_tree; code stores raw MJML in mjml_source. The mode is set when the template is created and cannot be changed afterwards: an update in the other mode is refused with a 400. To switch, create a new template in the other mode.

  • Default: visual
  • Available options: visual, code
mjml_source string

Raw MJML source (supports Liquid templating). Required when editor_mode is code, ignored otherwise.

  • Example: <mjml><mj-body><mj-section><mj-column><mj-text>Hello {{ contact.first_name }}</mj-text></mj-column></mj-section></mj-body></mjml>
sender_id string

ID of the sender configuration to use

  • Example: sender_123
reply_to string<email>

Reply-To email address

  • Example: support@example.com
subject string required

Email subject line (supports Liquid templating)

  • Example: Welcome, {{user_name}}!
subject_preview string | null

Preview text shown in email clients

  • Example: Get started with your account
compiled_preview string required

Compiled HTML preview of the email

visual_editor_tree object

MJML visual editor tree structure. Required when editor_mode is visual (the default), ignored in code mode. A block under mj-body of type mj-wrapper, mj-section, mj-text, mj-image, mj-button, mj-divider, mj-spacer, mj-social or mj-raw can carry a display_condition (see DisplayCondition): the block is then sent only to recipients for whom it holds. A condition anywhere else, on a block that holds an mj-liquid, or an invalid one, is refused with a 400.

text string | null

Custom plain-text version of the email, sent next to the HTML. Liquid is rendered with the same data as the body (write {% raw %} around a literal {{). Its links are sent as written: neither tracked nor given UTM parameters. Omit it, or send only whitespace, for the automatic version generated from the HTML at every send. Each translation has its own; a translation without one gets the automatic version of its own HTML. Saving a text with a Liquid syntax error, an include or render tag, or over 64 KiB (65,536 bytes once line endings are \n; maxLength counts characters) answers 400. If it cannot be rendered at send time, the email gets the automatic version.

  • Maximum length: 65536
  • Example: Hi {{ contact.first_name }}, Your order has shipped.
web object
Show child attributes
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 string required

Template category

  • Available options: marketing, transactional, welcome, opt_in, unsubscribe, bounce, blocklist, blog, other
  • Example: transactional
template_macro_id string | null

ID of the template macro (layout) to use

test_data object

Test data for template preview

settings object

Channel-specific settings

translations map<string, object>

Per-language content variants, keyed by language code. Every key must be one of the workspace's configured languages.

Show child attributes
email object
Show child attributes
editor_mode string

Which editor the email is written in. visual stores the drag-and-drop block tree in visual_editor_tree; code stores raw MJML in mjml_source. The mode is set when the template is created and cannot be changed afterwards: an update in the other mode is refused with a 400. To switch, create a new template in the other mode.

  • Default: visual
  • Available options: visual, code
mjml_source string

Raw MJML source (supports Liquid templating). Required when editor_mode is code, ignored otherwise.

  • Example: <mjml><mj-body><mj-section><mj-column><mj-text>Hello {{ contact.first_name }}</mj-text></mj-column></mj-section></mj-body></mjml>
sender_id string

ID of the sender configuration to use

  • Example: sender_123
reply_to string<email>

Reply-To email address

  • Example: support@example.com
subject string required

Email subject line (supports Liquid templating)

  • Example: Welcome, {{user_name}}!
subject_preview string | null

Preview text shown in email clients

  • Example: Get started with your account
compiled_preview string required

Compiled HTML preview of the email

visual_editor_tree object

MJML visual editor tree structure. Required when editor_mode is visual (the default), ignored in code mode. A block under mj-body of type mj-wrapper, mj-section, mj-text, mj-image, mj-button, mj-divider, mj-spacer, mj-social or mj-raw can carry a display_condition (see DisplayCondition): the block is then sent only to recipients for whom it holds. A condition anywhere else, on a block that holds an mj-liquid, or an invalid one, is refused with a 400.

text string | null

Custom plain-text version of the email, sent next to the HTML. Liquid is rendered with the same data as the body (write {% raw %} around a literal {{). Its links are sent as written: neither tracked nor given UTM parameters. Omit it, or send only whitespace, for the automatic version generated from the HTML at every send. Each translation has its own; a translation without one gets the automatic version of its own HTML. Saving a text with a Liquid syntax error, an include or render tag, or over 64 KiB (65,536 bytes once line endings are \n; maxLength counts characters) answers 400. If it cannot be rendered at send time, the email gets the automatic version.

  • Maximum length: 65536
  • Example: Hi {{ contact.first_name }}, Your order has shipped.
web object
Show child attributes
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

Response

201 Template created successfully object
template object
Show child attributes
id string required

Unique identifier for the template (alphanumeric, underscores, and hyphens only)

  • Maximum length: 32
  • Example: welcome_email
name string required

Name of the template

  • Maximum length: 255
  • Example: Welcome Email
version integer<int64>

Version number of the template

  • Example: 1
channel string required

Communication channel

  • Available options: email, web
  • Example: email
email object
Show child attributes
editor_mode string

Which editor the email is written in. visual stores the drag-and-drop block tree in visual_editor_tree; code stores raw MJML in mjml_source. The mode is set when the template is created and cannot be changed afterwards: an update in the other mode is refused with a 400. To switch, create a new template in the other mode.

  • Default: visual
  • Available options: visual, code
mjml_source string

Raw MJML source (supports Liquid templating). Required when editor_mode is code, ignored otherwise.

  • Example: <mjml><mj-body><mj-section><mj-column><mj-text>Hello {{ contact.first_name }}</mj-text></mj-column></mj-section></mj-body></mjml>
sender_id string

ID of the sender configuration to use

  • Example: sender_123
reply_to string<email>

Reply-To email address

  • Example: support@example.com
subject string required

Email subject line (supports Liquid templating)

  • Example: Welcome, {{user_name}}!
subject_preview string | null

Preview text shown in email clients

  • Example: Get started with your account
compiled_preview string required

Compiled HTML preview of the email

visual_editor_tree object

MJML visual editor tree structure. Required when editor_mode is visual (the default), ignored in code mode. A block under mj-body of type mj-wrapper, mj-section, mj-text, mj-image, mj-button, mj-divider, mj-spacer, mj-social or mj-raw can carry a display_condition (see DisplayCondition): the block is then sent only to recipients for whom it holds. A condition anywhere else, on a block that holds an mj-liquid, or an invalid one, is refused with a 400.

text string | null

Custom plain-text version of the email, sent next to the HTML. Liquid is rendered with the same data as the body (write {% raw %} around a literal {{). Its links are sent as written: neither tracked nor given UTM parameters. Omit it, or send only whitespace, for the automatic version generated from the HTML at every send. Each translation has its own; a translation without one gets the automatic version of its own HTML. Saving a text with a Liquid syntax error, an include or render tag, or over 64 KiB (65,536 bytes once line endings are \n; maxLength counts characters) answers 400. If it cannot be rendered at send time, the email gets the automatic version.

  • Maximum length: 65536
  • Example: Hi {{ contact.first_name }}, Your order has shipped.
web object
Show child attributes
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 string required

Template category

  • Available options: marketing, transactional, welcome, opt_in, unsubscribe, bounce, blocklist, blog, other
  • Maximum length: 20
  • Example: transactional
template_macro_id string | null

ID of the template macro (layout) to use

integration_id string | null read-only

ID of the integration managing this template (e.g., Supabase). Server-owned: it is set when the integration creates the template and cannot be set or changed through the API.

test_data object

Test data for template preview

settings object

Channel-specific third-party settings

translations map<string, object>

Per-language content variants, keyed by language code

Show child attributes
email object
Show child attributes
editor_mode string

Which editor the email is written in. visual stores the drag-and-drop block tree in visual_editor_tree; code stores raw MJML in mjml_source. The mode is set when the template is created and cannot be changed afterwards: an update in the other mode is refused with a 400. To switch, create a new template in the other mode.

  • Default: visual
  • Available options: visual, code
mjml_source string

Raw MJML source (supports Liquid templating). Required when editor_mode is code, ignored otherwise.

  • Example: <mjml><mj-body><mj-section><mj-column><mj-text>Hello {{ contact.first_name }}</mj-text></mj-column></mj-section></mj-body></mjml>
sender_id string

ID of the sender configuration to use

  • Example: sender_123
reply_to string<email>

Reply-To email address

  • Example: support@example.com
subject string required

Email subject line (supports Liquid templating)

  • Example: Welcome, {{user_name}}!
subject_preview string | null

Preview text shown in email clients

  • Example: Get started with your account
compiled_preview string required

Compiled HTML preview of the email

visual_editor_tree object

MJML visual editor tree structure. Required when editor_mode is visual (the default), ignored in code mode. A block under mj-body of type mj-wrapper, mj-section, mj-text, mj-image, mj-button, mj-divider, mj-spacer, mj-social or mj-raw can carry a display_condition (see DisplayCondition): the block is then sent only to recipients for whom it holds. A condition anywhere else, on a block that holds an mj-liquid, or an invalid one, is refused with a 400.

text string | null

Custom plain-text version of the email, sent next to the HTML. Liquid is rendered with the same data as the body (write {% raw %} around a literal {{). Its links are sent as written: neither tracked nor given UTM parameters. Omit it, or send only whitespace, for the automatic version generated from the HTML at every send. Each translation has its own; a translation without one gets the automatic version of its own HTML. Saving a text with a Liquid syntax error, an include or render tag, or over 64 KiB (65,536 bytes once line endings are \n; maxLength counts characters) answers 400. If it cannot be rendered at send time, the email gets the automatic version.

  • Maximum length: 65536
  • Example: Hi {{ contact.first_name }}, Your order has shipped.
web object
Show child attributes
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

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> | null

When the template was deleted, null while it is active. Deleted templates no longer appear in templates.list, but templates.get still returns them, because messages already sent are rendered from them.

400 Bad request - validation failed object
error string required

Error message

401 Unauthorized - invalid or missing authentication token object
error string required

Error message

413 The request body is larger than 1 MiB (1,048,576 bytes), the limit of a template request. A template of the gallery weighs about 20 KB per language. object
error string required

Error message

500 Internal server error object
error string required

Error message