> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Compile template

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.

## OpenAPI

````yaml /openapi.json post /api/templates.compile
openapi: 3.0.3
info:
  title: Notifuse API
  description: API for Notifuse - a transactional email and newsletter management platform
  version: 1.0.0
  contact:
    name: Notifuse Support
    url: https://www.notifuse.com/support
    email: hello@notifuse.com
  license:
    name: BUSL-1.1
    url: https://github.com/Notifuse/notifuse/blob/main/LICENSE
servers:
  - url: https://{notifuseDomain}
    description: Customer-specific Notifuse API server
    variables:
      notifuseDomain:
        description: Your unique Notifuse domain
        default: demo.notifuse.com
security: []
paths:
  /api/templates.compile:
    post:
      summary: Compile template
      description: >
        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.
      operationId: compileTemplate
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompileTemplateRequest"
      responses:
        "200":
          description: Template compiled successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompileTemplateResponse"
        "400":
          description: Bad request - compilation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "Compilation failed: Invalid MJML syntax"
        "401":
          description: Unauthorized - invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          description: >
            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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "Request body too large: a template request is limited to 1048576 bytes"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  schemas:
    CompileTemplateRequest:
      type: object
      description: Provide `visual_editor_tree` for a visual-mode template, or
        `mjml_source` for a code-mode one; neither is needed with
        `subject_only`.
      required:
        - workspace_id
        - message_id
      properties:
        workspace_id:
          type: string
          description: The ID of the workspace
          example: ws_1234567890
        message_id:
          type: string
          description: Unique message ID for tracking
          example: msg_abc123
        visual_editor_tree:
          type: object
          description: MJML visual editor tree structure (must have type 'mjml')
          additionalProperties: true
        mjml_source:
          type: string
          description: Raw MJML source of a code-mode template. When set, it is compiled
            instead of `visual_editor_tree`.
        subject:
          type: string
          description: >
            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:
          type: string
          description: >
            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:
          type: string
          description: >
            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:
          type: boolean
          default: false
          description: "When true, Liquid is not rendered: the body, `subject`,
            `subject_preview` and `text` are returned with their Liquid tags as
            written."
        subject_only:
          type: boolean
          default: false
          description: "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`."
        test_data:
          type: object
          description: Data to use for Liquid templating
          additionalProperties: true
          example:
            user_name: John Doe
            action_url: https://example.com/action
        tracking_settings:
          $ref: "#/components/schemas/TrackingSettings"
        channel:
          type: string
          enum:
            - email
            - web
          description: "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."
    CompileTemplateResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether compilation was successful
        mjml:
          type: string
          description: Generated MJML markup
        html:
          type: string
          description: Compiled HTML output
        subject:
          type: string
          description: |
            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:
          type: string
          description: >
            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:
          type: string
          description: >
            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:
          type: string
          enum:
            - auto
            - custom
          description: Where `text` comes from. Present when `text` is.
        text_error:
          type: string
          description: |
            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:
          type: object
          description: MJML compilation error details, if any
          properties:
            message:
              type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    TrackingSettings:
      type: object
      properties:
        enable_tracking:
          type: boolean
          description: Whether to enable click/open tracking
        tracking_mode:
          type: string
          enum:
            - inherit
            - no_tracking
            - disabled
          description: >
            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.
        endpoint:
          type: string
          description: API endpoint for tracking redirects
        utm_source:
          type: string
          description: UTM source parameter
        utm_medium:
          type: string
          description: UTM medium parameter
        utm_campaign:
          type: string
          description: UTM campaign parameter
        utm_content:
          type: string
          description: UTM content parameter
        utm_term:
          type: string
          description: UTM term parameter
        workspace_id:
          type: string
          description: Workspace ID for tracking
        message_id:
          type: string
          description: Message ID for tracking
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API token for authentication
````
