Omnisend Email Templates API

openapi: 3.2.0
info:
  contact: {}
  description: API for managing email content, templates and universal layouts
  title: Email Templates API
  version: '5.0'
  x-api-evangelist:
    harvested: '2026-08-13'
    method: searched
    source: https://dash.readme.com/api/v1/api-registry/9c1ckrq8msfxryye
    source-note: Published by Omnisend on its own docs host api-docs.omnisend.com (ReadMe project @omnisend, branch v2026-03-15); registry document referenced by the reference page as oasPublicUrl.
servers:
- url: https://api.omnisend.com/api
tags:
- name: Email Templates
paths:
  /email-templates:
    get:
      description: 'With this endpoint you can get a paginated list of email templates.


        **Sorting:**

        Use `sort` and `direction` to control the order of results.

        Supported sort fields: `createdAt` (default), `name`.

        Supported directions: `asc`, `desc` (default).


        **Filtering:**

        Use `nameContains` to filter templates by name (case-insensitive partial match, max 200 characters)


        **Pagination:**

        This endpoint uses cursor-based pagination for efficient traversal of large datasets.

        - Use the `paging.cursors.after` value from the response to get the next page

        - Use the `paging.cursors.before` value from the response to get the previous page

        - The `paging.hasMore` field indicates if more results are available

        - Do not use both `after` and `before` parameters simultaneously

        - Maximum page size is 100 items (default 50)

        - If `limit` is less than 1 or greater than 100, returns 400 Bad Request


        **Scopes:**

        `email-templates.read`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Number of items per page (1-100, default 50)
        in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - description: Cursor for next page (base64-encoded, from previous response)
        in: query
        name: after
        schema:
          type: string
      - description: Cursor for previous page (base64-encoded, from previous response)
        in: query
        name: before
        schema:
          type: string
      - description: Sort field (createdAt, name; default createdAt)
        in: query
        name: sort
        schema:
          type: string
          enum:
          - createdAt
          - name
      - description: Sort direction (asc, desc; default desc)
        in: query
        name: direction
        schema:
          type: string
          enum:
          - asc
          - desc
      - description: Filter templates by name (case-insensitive partial match, max 200 characters)
        in: query
        name: nameContains
        schema:
          type: string
          maxLength: 200
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: List of email templates with pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateListResponse'
        '400':
          description: Invalid query parameters or missing brand ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
      - Bearer:
        - email-templates.read
      - ApiKeyAuth: []
      summary: Get email templates
      tags:
      - Email Templates
    post:
      description: 'With this endpoint you can create a new email template.


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Template'
        description: Template to create
        required: true
      responses:
        '201':
          description: Created Template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '400':
          description: Invalid request body, missing brand ID, invalid template structure, or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '413':
          description: Request body too large - exceeds 1 MB limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
      - Bearer:
        - email-templates.write
      - ApiKeyAuth: []
      summary: Create email template
      tags:
      - Email Templates
  /email-templates/{id}:
    delete:
      description: 'With this endpoint you can delete email template by ID.


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Email Template ID (24 character hexadecimal)
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '204':
          description: No Content
        '400':
          description: Invalid template ID or missing brand ID
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Authentication is missing or invalid
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Insufficient permissions for this operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '410':
          description: API version has been retired
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '500':
          description: Unexpected error occurred
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
      - Bearer:
        - email-templates.write
      - ApiKeyAuth: []
      summary: Delete email template
      tags:
      - Email Templates
    get:
      description: 'With this endpoint you can get email template by ID.


        **Scopes:**

        `email-templates.read`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Email Template ID (24 character hexadecimal)
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: Template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '400':
          description: Invalid template ID or missing brand ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
      - Bearer:
        - email-templates.read
      - ApiKeyAuth: []
      summary: Get email template
      tags:
      - Email Templates
    put:
      description: 'With this endpoint you can update (fully replace) an email template by ID.


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Email Template ID (24 character hexadecimal)
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Template'
        description: Template to update
        required: true
      responses:
        '200':
          description: Updated Template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '400':
          description: Invalid template ID, request body, missing brand ID, invalid template structure, or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '413':
          description: Request body too large - exceeds 1 MB limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
      - Bearer:
        - email-templates.write
      - ApiKeyAuth: []
      summary: Update email template
      tags:
      - Email Templates
  /email-templates/{id}/render:
    post:
      description: 'With this endpoint you can render an email template by ID and get the full HTML body for preview purposes.


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 40 requests per minute.'
      parameters:
      - description: Email Template ID (24 character hexadecimal)
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: Rendered HTML body
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
        '400':
          description: Invalid template ID or missing brand ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
      - Bearer:
        - email-templates.write
      - ApiKeyAuth: []
      summary: Render email template
      tags:
      - Email Templates
  /email-templates/import:
    post:
      description: 'With this endpoint you can import email template from raw HTML content.

        The HTML will be parsed, styles extracted, and structured into a template.


        **Request body size limit:** 1 MB


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportTemplateRequest'
        description: Template name and HTML content to import
        required: true
      responses:
        '201':
          description: Imported Template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '400':
          description: Invalid request body or missing brand ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '413':
          description: Request body too large - exceeds 1 MB limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
      - Bearer:
        - email-templates.write
      - ApiKeyAuth: []
      summary: Import email template from HTML
      tags:
      - Email Templates
components:
  schemas:
    GeneralSettings:
      description: General settings for the template
      properties:
        body:
          allOf:
          - $ref: '#/components/schemas/Body'
          description: Body settings
        buttonPresets:
          description: Button presets
          items:
            $ref: '#/components/schemas/ButtonPreset'
          type: array
        content:
          allOf:
          - $ref: '#/components/schemas/Content'
          description: Content settings
        gmail:
          allOf:
          - $ref: '#/components/schemas/Gmail'
          description: Gmail settings
        logo:
          allOf:
          - $ref: '#/components/schemas/Logo'
          description: Logo settings
        textPresets:
          description: Text presets
          items:
            $ref: '#/components/schemas/TextPreset'
          type: array
      type: object
    OrderSummaryHiddenFields:
      description: Visibility toggles for order summary fields
      properties:
        isDateHidden:
          description: Whether the date is hidden
          example: false
          type: boolean
        isOrderIDHidden:
          description: Whether the order ID is hidden
          example: false
          type: boolean
        isTitleHidden:
          description: Whether the title is hidden
          example: false
          type: boolean
      type: object
    Column:
      description: Column is a single column of the row
      properties:
        blocks:
          description: Column blocks - used to group content into logical blocks
          items:
            $ref: '#/components/schemas/Block'
          type: array
        id:
          description: Column unique identifier - must be unique within the template
          example: 69770b2f7f774c6fb6f57194
          maxLength: 24
          minLength: 24
          type: string
        styleProperties:
          allOf:
          - $ref: '#/components/schemas/StyleProperties'
          description: Column style properties - used to configure the column styling
        width:
          description: Column width - used to set the width of the column
          example: 552px
          type: string
      type: object
    TextStyle:
      description: Text preset style properties
      properties:
        color:
          description: Text preset color
          example: '#BFDCFE'
          type: string
        fontFamily:
          description: Text preset font family
          example: Abril Fatface, Georgia, Times New Roman, Times, serif
          type: string
        fontSize:
          description: Text preset font size
          example: 36px
          type: string
        letterSpacing:
          description: Text preset letter spacing - spacing between letters
          example: 0px
          type: string
        lineHeight:
          description: Text preset line height
          example: 125%
          type: string
      type: object
    OrderTotalDiscount:
      description: Discount applied to the order total
      properties:
        amount:
          description: Discount amount
          example: $5.00
          type: string
        code:
          description: Discount code
          example: SAVE10
          type: string
        type:
          description: Discount type
          example: percentage
          type: string
      type: object
    ButtonPreset:
      description: Button preset for consistent design
      properties:
        id:
          description: Button preset unique identifier
          example: primary_button
          type: string
        name:
          description: Button preset name
          example: Primary button
          type: string
        styles:
          allOf:
          - $ref: '#/components/schemas/ButtonStyle'
          description: Button preset styles
      type: object
    BlockComponent:
      description: 'BlockComponent is a block nested inside a parent block, carrying one part of what that parent renders. Some parent blocks assign a ''role'' to each of their parts, and then the parent''s ''type'' decides which roles it needs: a ''discount'' block requires text/discount_code and accepts button/discount_button and text/discount_expiration_date; its WooCommerce equivalents take the same roles, except that ''dynamicDiscount'' requires the button and ''staticDiscount'' does not accept one. A ''menu'' block holds its items as text/menu_text. The product_* roles belong to a ''product'' block, whose price/product_prices component nests text/product_current_price and text/product_old_price components of its own. Blocks that do not assign roles nest their components without one.'
      properties:
        button:
          allOf:
          - $ref: '#/components/schemas/Button'
          description: Button content of the component - used by roles 'discount_button' and 'product_button'.
        components:
          description: Components nested inside this component. Only role 'product_prices' uses them.
          items:
            $ref: '#/components/schemas/BlockComponent'
          type: array
        html:
          description: 'Deprecated: use Text instead. Read-only, will be removed in future versions.'
          example: <p>Hello</p>
          readOnly: true
          type: string
        id:
          description: Component unique identifier - must be unique within the template
          example: 6699a0000000000000000000
          maxLength: 24
          minLength: 24
          type: string
        image:
          allOf:
          - $ref: '#/components/schemas/Image'
          description: Image content of the component - used by role 'product_image'.
        role:
          description: 'Role the component plays inside its parent block - set only where the parent block assigns

            roles to its parts, and omitted otherwise.'
          enum:
          - discount_code
          - discount_button
          - discount_expiration_date
          - menu_text
          - product_image
          - product_title
          - product_description
          - product_prices
          - product_price
          - product_button
          - product_current_price
          - product_old_price
          example: discount_code
          type: string
        stylePresetID:
          description: Style preset ID - ID of the style preset. ID must be present in template General Settings.
          example: paragraph
          type: string
        styleProperties:
          allOf:
          - $ref: '#/components/schemas/StyleProperties'
          description: Style properties - style properties of the component
        text:
          description: 'Text content of the component - supports HTML formatting and personalization tags.

            For role ''discount_code'' this is the code the recipient sees; on a platform that issues its own codes

            it is replaced at send time, so it carries the placeholder XXXX-XXXX-XXXX.'
          example: <p>XXXX-XXXX-XXXX</p>
          type: string
        type:
          description: Component type. Only these block types can be nested as a component.
          enum:
          - text
          - button
          - image
          - price
          example: text
          type: string
      type: object
    TemplateListItem:
      description: Email template list item
      properties:
        createdAt:
          description: Template created at (read-only)
          example: '2021-01-01T01:02:03Z'
          readOnly: true
          type: string
        id:
          description: Template unique identifier (read-only)
          example: 68beca12d2e99b0c8d19fd5e
          readOnly: true
          type: string
        name:
          description: Template name
          example: Welcome Email 1
          maxLength: 255
          minLength: 1
          type: string
        updatedAt:
          description: Template updated at (read-only)
          example: '2021-01-01T01:02:03Z'
          readOnly: true
          type: string
      type: object
    Video:
      description: Video block for displaying a video in the email
      properties:
        altText:
          description: Video alt text - alternative text for the video for accessibility
          example: Video description
          type: string
        id:
          description: Video ID - Omnisend video ID - can be retrieved from the Video API
          example: 68f0ad8a72105230579523cd
          maxLength: 24
          minLength: 24
          type: string
        image:
          allOf:
          - $ref: '#/components/schemas/Image'
          description: Video image - image of the video thumbnail
        link:
          description: Video link - where the video will redirect on click
          example: https://www.youtube.com/watch?v=example
          type: string
      type: object
    Visibility:
      description: Visibility settings for the template
      properties:
        isDesktopVisible:
          description: Whether the template is visible on desktop devices
          example: true
          type: boolean
        isMobileVisible:
          description: Whether the template is visible on mobile devices
          example: true
          type: boolean
      type: object
    CursorsResponse:
      description: Cursor pointers for paginating forward and backward through results
      properties:
        after:
          description: Opaque cursor for fetching the next page of results
          example: eyJpZCI6ImNhbXAtNDU2In0
          type:
          - string
          - 'null'
        before:
          description: Opaque cursor for fetching the previous page of results
          example: eyJpZCI6ImNhbXAtMTIzIn0
          type:
          - string
          - 'null'
      type: object
    StyleProperties:
      description: Style properties for the section
      properties:
        alignment:
          description: Alignment - used to align the content horizontally
          example: center
          type: string
        backgroundColor:
          description: Background color - used to set the background color of the content
          example: '#FFFFFF'
          type: string
        backgroundImageID:
          description: Background image ID - ID of the background image asset. Must be present in Image API
          example: 68f0af8f72105230579523cf
          maxLength: 24
          minLength: 24
          type: string
        backgroundPosition:
          description: Background position - used to position the background image
          example: unset
          type: string
        backgroundRepeat:
          description: Background repeat - used to repeat the background image
          example: no-repeat
          type: string
        backgroundSize:
          description: Background size - used to size the background image
          example: cover
          type: string
        border:
          description: Border - used to add a border to the content
          example: '2px solid #BFDCFE'
          type: string
        borderRadius:
          description: Border radius
          example: 0px
          type: string
        color:
          description: Text color
          example: '#BFDCFE'
          type: string
        dividerColor:
          description: Divider color
          example: '#E0E0E0'
          type: string
        fontFamily:
          description: Font family
          example: Arial, sans-serif
          type: string
        fontSize:
          description: Font size
          example: 16px
          type: string
        fontStyle:
          description: Font style
          example: normal
          type: string
        fontWeight:
          description: Font weight
          example: bold
          type: string
        innerPadding:
          description: Inner padding
          example: 16px
          type: string
        innerPaddingBottom:
          description: Inner padding bottom
          example: 16px
          type: string
        innerPaddingLeft:
          description: Inner padding left
          example: 16px
          type: string
        innerPaddingRight:
          description: Inner padding right
          example: 16px
          type: string
        innerPaddingTop:
          description: Inner padding top
          example: 16px
          type: string
        isBackgroundPaddingsExcluded:
          description: Whether to exclude background paddings - used to exclude paddings from the background image
          example: false
          type: boolean
        letterSpacing:
          description: Letter spacing - spacing between letters
          example: 0px
          type: string
        lineHeight:
          description: Line height
          example: '1.5'
          type: string
        linkColor:
          description: Link color
          example: '#383838'
          type: string
        padding:
          description: Padding
          example: 12px
          type: string
        paddingBottom:
          description: Padding bottom
          example: 12px
          type: string
        paddingLeft:
          description: Padding left
          example: 12px
          type: string
        paddingRight:
          description: Padding right
          example: 12px
          type: string
        paddingTop:
          description: Padding top
          example: 12px
          type: string
        priceColor:
          description: Price color - used to color the price text
          example: '#212121'
          type: string
        secondaryColor:
          description: Secondary color - used to color the secondary text
          example: '#757575'
          type: string
        textBackgroundColor:
          description: Text Background color - used to set the text background color
          example: '#BFDCFE'
          type: string
        textDecoration:
          description: Text decoration
          example: none
          type: string
        verticalAlign:
          description: Vertical alignment - used to align the content v

# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/omnisend/refs/heads/main/openapi/omnisend-email-templates-api-openapi.yml