> ## 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.

# Update a template

Updates an existing template. Creates a new version of the template. The email's `editor_mode` must stay the one the template was created with; to switch between the visual editor and MJML code, create a new template. A deleted template cannot be updated.

## OpenAPI

````yaml /openapi.json post /api/templates.update
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.update:
    post:
      summary: Update a template
      description: Updates an existing template. Creates a new version of the
        template. The email's `editor_mode` must stay the one the template was
        created with; to switch between the visual editor and MJML code, create
        a new template. A deleted template cannot be updated.
      operationId: updateTemplate
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTemplateRequest"
      responses:
        "200":
          description: Template updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    $ref: "#/components/schemas/Template"
        "400":
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                editorModeChange:
                  summary: The update is in the other editor mode
                  value:
                    error: "cannot change editor mode: template was created in 'code' mode and its
                      mode can't be changed; create a new template in 'visual'
                      mode and copy the content with Import or Export MJML"
        "401":
          description: Unauthorized - invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Template not found, or deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Template not found
        "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"
              example:
                error: Failed to update template
components:
  schemas:
    EmailTemplate:
      type: object
      properties:
        editor_mode:
          type: string
          enum:
            - visual
            - code
          default: visual
          description: "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."
        mjml_source:
          type: string
          description: 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:
          type: string
          description: ID of the sender configuration to use
          example: sender_123
        reply_to:
          type: string
          format: email
          description: Reply-To email address
          example: support@example.com
        subject:
          type: string
          description: Email subject line (supports Liquid templating)
          example: Welcome, {{user_name}}!
        subject_preview:
          type: string
          nullable: true
          description: Preview text shown in email clients
          example: Get started with your account
        compiled_preview:
          type: string
          description: Compiled HTML preview of the email
        visual_editor_tree:
          type: object
          description: "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."
          example:
            type: mjml
            children: []
        text:
          type: string
          nullable: true
          maxLength: 65536
          description: "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."
          example: |
            Hi {{ contact.first_name }},

            Your order has shipped.
      required:
        - subject
        - compiled_preview
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    Template:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the template (alphanumeric, underscores, and
            hyphens only)
          example: welcome_email
          maxLength: 32
          pattern: ^[a-zA-Z0-9_-]+$
        name:
          type: string
          description: Name of the template
          example: Welcome Email
          maxLength: 255
        version:
          type: integer
          format: int64
          description: Version number of the template
          example: 1
        channel:
          type: string
          enum:
            - email
            - web
          description: Communication channel
          example: email
        email:
          $ref: "#/components/schemas/EmailTemplate"
        web:
          $ref: "#/components/schemas/WebTemplate"
        category:
          type: string
          enum:
            - marketing
            - transactional
            - welcome
            - opt_in
            - unsubscribe
            - bounce
            - blocklist
            - blog
            - other
          description: Template category
          example: transactional
          maxLength: 20
        template_macro_id:
          type: string
          nullable: true
          description: ID of the template macro (layout) to use
        integration_id:
          type: string
          nullable: true
          readOnly: true
          description: "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:
          type: object
          additionalProperties: true
          description: Test data for template preview
          example:
            user_name: John Doe
            action_url: https://example.com/action
        settings:
          type: object
          additionalProperties: true
          description: Channel-specific third-party settings
        translations:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TemplateTranslation"
          description: Per-language content variants, keyed by language code
          example:
            fr:
              email:
                subject: Bienvenue
        created_at:
          type: string
          format: date-time
          description: When the template was created
        updated_at:
          type: string
          format: date-time
          description: When the template was last updated
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: 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.
      required:
        - id
        - name
        - channel
        - category
    TemplateTranslation:
      type: object
      description: "Content for one language. Carries the field matching the
        template's channel: email for an email template, web for a web template.
        An email translation without `sender_id` or `reply_to` sends with those
        of the template's default content."
      properties:
        email:
          $ref: "#/components/schemas/EmailTemplate"
        web:
          $ref: "#/components/schemas/WebTemplate"
    UpdateTemplateRequest:
      type: object
      description: "Replaces the template's content, creating a new version. Fields
        the body omits are not cleared: translations are carried over from the
        stored template, and integration_id is server-owned and always
        preserved."
      required:
        - workspace_id
        - id
        - name
        - channel
        - category
      properties:
        workspace_id:
          type: string
          description: The ID of the workspace
          example: ws_1234567890
        id:
          type: string
          description: ID of the template to update
          example: welcome_email
          maxLength: 32
        name:
          type: string
          description: Name of the template
          example: Welcome Email
          maxLength: 255
        channel:
          type: string
          enum:
            - email
            - web
          description: Communication channel
          example: email
        email:
          $ref: "#/components/schemas/EmailTemplate"
        web:
          $ref: "#/components/schemas/WebTemplate"
        category:
          type: string
          enum:
            - marketing
            - transactional
            - welcome
            - opt_in
            - unsubscribe
            - bounce
            - blocklist
            - blog
            - other
          description: Template category
          example: transactional
        template_macro_id:
          type: string
          nullable: true
          description: ID of the template macro (layout) to use
        test_data:
          type: object
          additionalProperties: true
          description: Test data for template preview
        settings:
          type: object
          additionalProperties: true
          description: Channel-specific settings
        translations:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TemplateTranslation"
          description: Per-language content variants, keyed by language code. Every key
            must be one of the workspace's configured languages. Omit the
            property to keep the stored translations untouched; send an empty
            object to delete all of them.
    WebTemplate:
      type: object
      properties:
        content:
          type: object
          additionalProperties: true
          description: Tiptap JSON content (source of truth for web templates)
        html:
          type: string
          description: Pre-rendered HTML for display
        plain_text:
          type: string
          description: Extracted text for search indexing
      required:
        - content
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API token for authentication
````
