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

# Get Merge Tags

> Retrieve the merge tags (variables) for a template version. By default, returns merge tags for the active version. Use the `version` parameter to get merge tags for a specific version.

Returns the merge tags found in a template's content. Use this to discover which `substitution_data` keys a template expects when [sending an email](/api-reference/emails/send-email).

By default, merge tags are extracted from the active version. Use the `version` query parameter to inspect a specific version instead.


## OpenAPI

````yaml GET /templates/{slug}/merge-tags
openapi: 3.1.0
info:
  title: Lettr API
  version: 1.0.0
  description: >-
    Lettr Email API - Send transactional emails with tracking, attachments, and
    personalization.
  contact:
    name: Lettr Support
    url: https://lettr.com
  license:
    name: Proprietary
    url: https://lettr.com/terms
servers:
  - url: https://app.lettr.com/api
    description: Production
security: []
tags:
  - name: Emails
    description: Email sending operations
  - name: Templates
    description: Email template management operations
  - name: Domains
    description: Domain management operations
  - name: Webhooks
    description: Webhook management operations
  - name: Audience
    description: 'Audience management: lists, contacts, topics, properties, and segments'
  - name: Campaigns
    description: >-
      Campaign operations: listing, stats, engagement events, and
      dispatch/scheduling
paths:
  /templates/{slug}/merge-tags:
    get:
      tags:
        - Templates
      summary: Get Template Merge Tags
      description: >-
        Retrieve the merge tags (variables) for a template version. By default,
        returns merge tags for the active version. Use the `version` parameter
        to get merge tags for a specific version.
      operationId: getTemplateMergeTags
      parameters:
        - name: slug
          in: path
          required: true
          description: The template slug (URL-friendly identifier)
          schema:
            type: string
            example: welcome-email
        - name: project_id
          in: query
          description: >-
            Project ID to retrieve the template from. If not provided, uses the
            team's default project.
          schema:
            type: integer
            minimum: 1
        - name: version
          in: query
          description: Template version number. If not provided, uses the active version.
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Merge tags retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMergeTagsResponse'
              example:
                message: Merge tags retrieved successfully.
                data:
                  project_id: 13
                  template_slug: welcome-email
                  version: 2
                  merge_tags:
                    - key: first_name
                      required: true
                    - key: company_name
                      required: false
                    - key: order_items
                      required: false
                      children:
                        - key: item_name
                          type: text
                        - key: item_quantity
                          type: number
                        - key: item_price
                          type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Template, version, or project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                template_not_found:
                  summary: Template not found
                  value:
                    message: Template with slug 'welcome-email' was not found.
                    error_code: not_found
                project_not_found:
                  summary: Project not found
                  value:
                    message: >-
                      Project with ID '123' was not found or you don't have
                      access to it.
                    error_code: not_found
                no_default_project:
                  summary: No default project configured
                  value:
                    message: No default project is configured for this team.
                    error_code: not_found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                message: Validation failed.
                error_code: validation_error
                errors:
                  version:
                    - The version parameter must be an integer.
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Failed to retrieve merge tags. Please try again later.
                error_code: send_error
      security:
        - bearerAuth: []
components:
  schemas:
    GetMergeTagsResponse:
      type: object
      description: Response containing merge tags for a template version
      required:
        - message
        - data
      properties:
        message:
          type: string
          description: Human-readable response message
          example: Merge tags retrieved successfully.
        data:
          $ref: '#/components/schemas/MergeTagsListView'
    ErrorResponse:
      type: object
      required:
        - message
        - error_code
      description: Error response for non-validation errors (400, 409, 500, 502).
      properties:
        message:
          type: string
          description: Human-readable error message
          example: The sender domain could not be determined from the email address.
        error_code:
          $ref: '#/components/schemas/ErrorCode'
    ValidationErrorResponse:
      type: object
      required:
        - message
        - error_code
        - errors
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Validation failed.
        error_code:
          type: string
          description: Error code (always `validation_error` for 422 responses)
          const: validation_error
          example: validation_error
        errors:
          type: object
          description: Field-specific validation errors
          additionalProperties:
            type: array
            items:
              type: string
          example:
            from:
              - The sender email address is required.
            to:
              - At least one recipient email address is required.
    MergeTagsListView:
      type: object
      description: Merge tags for a template version
      required:
        - project_id
        - template_slug
        - version
        - merge_tags
      properties:
        project_id:
          type: integer
          description: Numeric ID of the project the template belongs to.
          example: 13
        template_slug:
          type: string
          description: The template slug
          example: welcome-email
        version:
          type: integer
          description: The template version number
          example: 2
        merge_tags:
          type: array
          description: List of merge tags in this template version
          items:
            $ref: '#/components/schemas/MergeTagView'
    UnauthorizedResponse:
      type: object
      required:
        - message
      description: Error response for authentication failures (401).
      properties:
        message:
          type: string
          description: Human-readable error message
          example: API key is required.
    ErrorCode:
      type: string
      description: >-
        Error codes returned by the API.


        | Code | HTTP Status | Description |

        |------|-------------|-------------|

        | `validation_error` | 422 | Request validation failed. Check the
        `errors` object for field-specific messages. |

        | `invalid_domain` | 400 | The sender domain could not be determined
        from the email address. |

        | `unconfigured_domain` | 400 | The sender domain is not configured or
        approved for sending. |

        | `send_error` | 400, 500 | General error during email send preparation
        or domain registration. |

        | `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g.,
        sandbox key without associated user, upstream error). |

        | `transmission_failed` | 502 | Email transmission to the upstream
        provider failed. |

        | `resource_already_exists` | 409 | The resource (e.g., domain) already
        exists. |

        | `not_found` | 404 | The specified resource was not found. |

        | `template_not_found` | 404 | The specified template, project, or
        template version was not found. |

        | `insufficient_scope` | 403 | The API key does not have the required
        scope for this endpoint. |

        | `schedule_cancellation_failed` | 409, 500 | Could not cancel the
        scheduled transmission (already sent or upstream error). |

        | `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your
        plan to continue sending. |

        | `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again
        tomorrow. |

        | `campaign_not_sendable` | 422 | The campaign cannot be sent in its
        current state (not a draft, or missing subject/sender/content). |

        | `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it
        cannot be unscheduled. |
      enum:
        - validation_error
        - invalid_domain
        - unconfigured_domain
        - send_error
        - retrieval_error
        - transmission_failed
        - resource_already_exists
        - not_found
        - template_not_found
        - insufficient_scope
        - schedule_cancellation_failed
        - quota_exceeded
        - daily_quota_exceeded
        - campaign_not_sendable
        - campaign_not_scheduled
      example: invalid_domain
    MergeTagView:
      type: object
      description: >-
        A single merge tag. Loop merge tags (for iterating over arrays) include
        a 'children' property with nested field definitions.
      required:
        - key
        - required
      properties:
        key:
          type: string
          description: The merge tag key/name used in templates
          example: first_name
        required:
          type: boolean
          description: Whether this merge tag is required when sending emails
          example: true
        type:
          type: string
          description: The data type of the merge tag (only present for loop children)
          enum:
            - text
            - number
            - image
            - button
          example: text
        children:
          type: array
          description: >-
            Child merge tags for loop blocks. Each child represents a field
            available within the loop iteration.
          items:
            $ref: '#/components/schemas/MergeTagChild'
    MergeTagChild:
      type: object
      description: A child merge tag within a loop block
      required:
        - key
      properties:
        key:
          type: string
          description: The child merge tag key/name
          example: item_name
        type:
          type: string
          description: The data type of the child merge tag
          enum:
            - text
            - number
            - image
            - button
          example: text
  responses:
    UnauthorizedError:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'
          examples:
            missing_key:
              summary: Missing API key
              value:
                message: API key is required.
            invalid_key:
              summary: Invalid API key
              value:
                message: Invalid API key.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````