Templates

Compile template

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

Compiles an MJML template with provided data, returning the rendered HTML. When subject and/or subject_preview are provided, they are rendered through the same Liquid engine used at send time and returned alongside the HTML so callers do not need to run a separate Liquid pass to preview the subject line. Useful for previewing templates before saving.

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
message_id string required

Unique message ID for tracking

  • Example: msg_abc123
visual_editor_tree object

MJML visual editor tree structure (must have type 'mjml')

mjml_source string

Raw MJML source of a code-mode template. When set, it is compiled instead of visual_editor_tree.

subject string

Optional email subject. When provided, it is rendered through the same Liquid engine the send path uses (with test_data) and the rendered result is returned as subject in the response. Liquid processing is skipped when preserve_liquid is true, channel is web, or test_data is empty.

  • Example: Hi {{ contact.first_name }}
subject_preview string

Optional inbox preview text (the snippet shown after the subject in most clients). Rendered through Liquid like subject and returned as subject_preview in the response.

  • Example: Welcome {{ contact.first_name }}
text string

Optional source of a custom plain-text version, as stored in a template's email.text. It is rendered with test_data (kept as written when preserve_liquid is true) and returned as text with text_source set to custom. Omit it to get the automatic version. A text over 64 KiB (65,536 bytes once line endings are \n) answers 400, as saving it in a template does.

  • Example: Hi {{ contact.first_name }}
preserve_liquid boolean

When true, Liquid is not rendered: the body, subject, subject_preview and text are returned with their Liquid tags as written.

  • Default: false
subject_only boolean

When true, only subject and subject_preview are rendered and returned: the body is neither required nor compiled, and the response carries no mjml, html or text.

  • Default: false
test_data object

Data to use for Liquid templating

tracking_settings object
Show child attributes
enable_tracking boolean

Whether to enable click/open tracking

tracking_mode string

Per-notification tracking preference. Absent or "inherit" follows the workspace tracking settings and each recipient's tracking consent (the workspace settings always act as a kill-switch and cannot be overridden). "no_tracking" leaves out the open pixel and the click-tracking redirect but keeps the UTM parameters. "disabled" suppresses all rewriting for this notification — no click-tracking redirect, no open pixel, and no UTM parameters — used for auth emails (e.g. Supabase magic links) whose single-use URLs must never be modified. Update semantics: an ABSENT tracking_mode field keeps the stored value (so partial edits cannot wipe an opt-out; an empty string is treated as absent); an explicit "inherit" resets the notification to follow the workspace flag; an explicit "disabled" opts it out. Note that the other tracking_settings fields (utm_*) are replaced wholesale on update — only tracking_mode has keep-when-absent semantics.

  • Available options: inherit, no_tracking, disabled
endpoint string

API endpoint for tracking redirects

utm_source string

UTM source parameter

utm_medium string

UTM medium parameter

utm_campaign string

UTM campaign parameter

utm_content string

UTM content parameter

utm_term string

UTM term parameter

workspace_id string

Workspace ID for tracking

message_id string

Message ID for tracking

channel string

Which channel this template targets. It selects the content object the template must carry: an email template supplies email and omits web, and a web template does the reverse.

  • Available options: email, web

Response

200 Template compiled successfully object
success boolean

Whether compilation was successful

mjml string

Generated MJML markup

html string

Compiled HTML output

subject string

Rendered email subject. Present only when the request included a non-empty subject. Returned on both success and error paths so the caller can display the rendered subject alongside any compilation error.

  • Example: Hi Pierre
subject_preview string

Rendered inbox preview text. Present only when the request included a non-empty subject_preview. Returned on both success and error paths.

  • Example: Welcome Pierre
text string

Plain-text version sent with the email: the custom text rendered when the request has a text that renders, otherwise the automatic version, generated from the compiled HTML with the same links. Present only when an email compilation succeeds. An empty string means the email holds no text to read and is sent as HTML only.

  • Example: Hi Pierre Shop now (https://example.com/shop)
text_source string

Where text comes from. Present when text is.

  • Available options: auto, custom
text_error string

Why the custom text of the request could not be used (a Liquid error, a rendered text over 256 KiB, or a custom text that renders blank for this data); text is then the automatic version, as a send would be. With preserve_liquid, also flags an automatic text whose Liquid tags would not parse, or a visual template that places Liquid between the blocks of a section or a column, where it may not land where it applies in the text.

error object

MJML compilation error details, if any

Show child attributes
message string
400 Bad request - compilation 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