Omnisend Email Universal Layouts API

openapi: 3.2.0
info:
  contact: {}
  description: API for managing email content, templates and universal layouts
  title: Email Universal Layouts 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 Universal Layouts
paths:
  /email-universal-layouts:
    get:
      description: 'With this endpoint you can get a paginated list of universal layouts.


        **Sorting:**

        Items are returned in descending order by creation time (newest first).

        This is based on the internal document ID which contains a timestamp.


        **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 250 items (default 100)

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


        **Filtering:**

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


        **Scopes:**

        `email-templates.read`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Number of items per page (1-250, default 100)
        in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 250
      - 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: Filter layouts 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 universal layouts with pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUniversalLayoutsResponse'
        '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 universal layouts
      tags:
      - Email Universal Layouts
    post:
      description: 'With this endpoint you can create a new universal layout.


        **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/UniversalLayout'
        description: Universal layout to create
        required: true
      responses:
        '201':
          description: Created Universal Layout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniversalLayout'
        '400':
          description: Invalid request body, missing brand ID, invalid layout 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 universal layout
      tags:
      - Email Universal Layouts
  /email-universal-layouts/{id}:
    delete:
      description: 'With this endpoint you can delete a universal layout by ID.


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Universal Layout ID (24 character hexadecimal)
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '204':
          description: Universal layout deleted successfully
        '400':
          description: Invalid layout 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 universal layout
      tags:
      - Email Universal Layouts
    get:
      description: 'With this endpoint you can get a universal layout by ID.


        **Scopes:**

        `email-templates.read`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Universal Layout ID (24 character hexadecimal)
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: Universal Layout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniversalLayout'
        '400':
          description: Invalid layout 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: Universal layout 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 universal layout
      tags:
      - Email Universal Layouts
    put:
      description: 'With this endpoint you can update (fully replace) a universal layout by ID.


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Universal Layout 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/UniversalLayout'
        description: Universal layout to update
        required: true
      responses:
        '200':
          description: Updated Universal Layout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniversalLayout'
        '400':
          description: Invalid layout ID, request body, missing brand ID, invalid layout 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: Universal layout 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 universal layout
      tags:
      - Email Universal Layouts
components:
  schemas:
    ListUniversalLayoutsResponse:
      description: Represents the response for listing universal layouts
      properties:
        paging:
          allOf:
          - $ref: '#/components/schemas/PagingResponse'
          description: Pagination information
        universalLayouts:
          description: List of universal layouts
          items:
            $ref: '#/components/schemas/UniversalLayout'
          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
    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
    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
    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
    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 vertically
          example: top
          type: string
      type: object
    Preheader:
      description: Preheader block to setup View in Browser link text formattings Text is formatted as ```Text<a href="https://view-inbrowser-link">LinkText</a>```
      properties:
        linkText:
          description: Preheader link text
          example: click here
          type: string
        text:
          description: Preheader text
          example: 'If you cannot see images, please '
          type: string
      type: object
    OrderTax:
      description: Tax line item applied to the order
      properties:
        price:
          description: Tax amount
          example: $4.80
          type: string
        rate:
          description: Tax rate
          example: 8%
          type: string
        title:
          description: Tax name
          example: Sales Tax
          type: string
      type: object
    Discount:
      description: Discount block settings. This object configures the offer only — the parts the recipient sees (code, redeem button, expiry) are separate role-tagged blocks in the parent block's 'components'. See the notes on the Block 'type' field for the roles each discount block type requires.  An offer needs 'discountType', the value that matches it ('valuePercentage' for a percentage, 'valueFixed' for an amount off), 'discountConditions', and 'endsIn' for how long it stays valid. 'staticDiscount' and 'dynamicDiscount' blocks require 'code', 'discountType', 'valuePercentage' and 'discountConditions'.
      properties:
        appliesToCustomCollectionID:
          description: ID of the custom collection that the discount applies to
          example: 0
          type: integer
        appliesToID:
          description: ID of the specific resource (product, collection) that the discount applies to
          example: 0
          type: integer
        appliesToResource:
          description: Type of resource the discount applies to
          example: all
          type: string
        appliesToSmartCollectionID:
          description: ID of the smart collection that the discount applies to
          example: 0
          type: integer
        code:
          description: 'Discount code customers use to apply the discount.

            In ''discount'' (Shopify, BigCommerce) and ''dynamicDiscount'' (WooCommerce) blocks the code is not taken from here:

            the store issues a unique code per recipient when the email is sent, and it replaces both this value and the text

            of the ''discount_code'' component. Use the placeholder XXXX-XXXX-XXXX in both places — a literal code written here

            is not created in the store, so it is either replaced at send time or, for a brand with automatic discount

            creation switched off, delivered as a code the recipient cannot redeem.

            In ''staticDiscount'' blocks (WooCommerce) this is instead the real, fixed code that already exists in the store.'
          example: XXXX-XXXX-XXXX
          type: string
        combinesWith:
          allOf:
          - $ref: '#/components/schemas/DiscountCombinesWith'
          description: Whether the discount can be combined with other discounts
        discountConditions:
          description: Conditions that must be met for the discount to apply
          example: all_orders
          type: string
        discountType:
          description: 'Type of discount: percentage off, fixed amount off, or shipping discount'
          example: percentage
          type: string
        endsIn:
          description: Number of days until the discount ends
          example: '14'
          type: string
        isAppliedOncePerCustomer:
          description: When generating a discount code in integrated platforms, the discount can only be used once per customer
          example: false
          type: boolean
        isDiscountApplied:
          description: Whether the discount should be automatically applied to the order
          example: true
          type: boolean
        isItemsOnSaleExcluded:
          description: Whether the discount should exclude items that are already on sale
          example: false
          type: boolean
        link:
          description: URL link for the discount
          example: https://omnisend-inga-qa7-new.myshopify.com
          type: string
        minimumOrderAmount:
          description: Minimum order amount required for the discount to apply
          example: '50'
          type: string
        offerText:
          description: Text displayed to customers when they apply the discount
          example: Get 15% off your order
          type: string
        title:
          description: Title of the discount
          example: Summer Sale
          type: string
        usageLimit:
          description: Maximum number of times the discount can be used
          example: '100'
          type: string
        validUntil:
          description: Date and time when the discount expires
          example: '2026-02-09T06:42:35.350Z'
          type: string
        validUntilFormat:
          description: Format of the expiration date
          example: MMM DD, YYYY
          type: string
        validUntilFormatted:
          description: Formatted expiration date
          example: Feb 09, 2026
          type: string
        valueFixed:
          description: Fixed value of the discount
          example: '10'
          type: string
        valuePercentage:
          description: Percentage value of the discount
          example: '15'
          type: string
      type: object
    Button:
      description: Button block settings
      properties:
        isFullWidth:
          description: Button is full width
          example: true
          type: boolean
        link:
          description: Button link
          example: https://www.omnisend.com
          type: string
        text:
          description: Button text
          example: Shop now
          type: string
        translationKey:
          description: Button translation key - used for internationalization support
          example: shop_now
          type: string
      type: object
    OrderAddressesHiddenFields:
      description: Visibility toggles for the order addresses section
      properties:
        billing:
          allOf:
          - $ref: '#/components/schemas/OrderAddressHiddenFields'
          description: Billing address hidden fields
        isTitleHidden:
          description: Whether the section title is hidden
          example: false
          type: boolean
        shipping:
          allOf:
          - $ref: '#/components/schemas/OrderAddressHiddenFields'
          description: Shipping address hidden fields
      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
    Settings:
      description: Settings for the section
      properties:
        backgroundType:
          description: Background type - determines whether the section background is a color or image
          example: image
          type: string
        customFonts:
          description: Custom fonts used in this section
          items:
            $ref: '#/components/schemas/CustomFont'
          type: array
        dynamicList:
          allOf:
          - $ref: '#/components/schemas/DynamicList'
          description: Dynamic list configuration for repeating content
        excludeProducts:
          description: 'Products to exclude from display when abandoned produc

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