Omnisend Email Content API

openapi: 3.2.0
info:
  contact: {}
  description: API for managing email content, templates and universal layouts
  title: Email Content 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 Content
paths:
  /email-content/{id}:
    get:
      description: 'With this endpoint you can get email content by ID.


        **Scopes:**

        `email-templates.read`


        **Rate Limiting:**

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

        The full content structure must be provided in the request body.


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Content 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/Content'
        description: Email content to update
        required: true
      responses:
        '200':
          description: Updated Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Content'
        '400':
          description: Invalid content ID, missing brand ID, invalid content 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: Content not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '409':
          description: Content is locked and cannot be modified
          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 content
      tags:
      - Email Content
  /email-content/{id}/render:
    post:
      description: 'With this endpoint you can render email content to HTML by ID.

        The content is rendered with an empty data context (no contact, no marketing activity).


        **Scopes:**

        `email-templates.write`


        **Rate Limiting:**

        This endpoint is rate limited to 40 requests per minute.'
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      - description: Content ID (24 character hexadecimal)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Rendered HTML body
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
        '400':
          description: Invalid content 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: Content 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'
        '422':
          description: Liquid syntax error in template
          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 content
      tags:
      - Email Content
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
    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
    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
    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
    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
    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 products section is used.

            Products are excluded from display if they are in the list of products that were abandoned by the contact.'
          items:
            type: string
          type: array
        filter:
          allOf:
          - $ref: '#/components/schemas/Filter'
          description: Filter for the section - used to conditionally display content based on contact or event properties
        isColumnStackDisabled:
          description: Whether to disable column stacking - used to display content in a single column
          example: true
          type: boolean
        isOutOfStockHidden:
          description: Whether to hide out of stock products from product sections
          example: false
          type: boolean
        isProductImagesFitted:
          description: Whether to fit product images to the container - used to display product images in a single line
          example: true
          type: boolean
        sideBySideProductLayout:
          description: Side by side product layout
          example: 2-column
          type: string
        universalLayoutID:
          description: 'Universal layout ID - ID of the universal layout.

            If present, section content is received from Universal Layout API and displayed as is.'
          example: 68beca12d2e99b0c8d19fd5e
          maxLength: 24
          minLength: 24
          type: string
      type: object
    FilterProperty:
      description: Filter property for conditional display of content
      properties:
        id:
          description: Filter property unique identifier
          example: property_id
          type: string
        isSystem:
          description: Indicates whether the property is a built-in system property (true) or a user-defined custom property (false).
          example: true
          type: boolean
        name:
          description: Filter property name
          example: Property Name
          type: string
        type:
          description: Filter property type
          example: string
          type: string
      type: object
    CustomFont:
      description: Custom font reference
      properties:
        id:
          description: ID of the custom font
          example: 69ca539b38e3c1f5dc035867
          maxLength: 24
          minLength: 24
          type: string
      type: object
    OrderAddressHiddenFields:
      description: Visibility toggles for individual address fields
      properties:
        isAddress1Hidden:
          description: Whether the address line 1 is hidden
          example: false
          type: boolean
        isAddress2Hidden:
          description: Whether the address line 2 is hidden
          example: false
          type: boolean
        isCityHidden:
          description: Whether the city is hidden
          example: false
          type: boolean
        isCompanyHidden:
          description: Whether the company is hidden
          example: false
          type: boolean
        isCountryHidden:
          description: Whether the country is hidden
          example: false
          type: boolean
        isNameSurnameHidden:
          description: Whether the name and surname are hidden
          example: false
          type: boolean
        isPhoneHidden:
          description: Whether the phone is hidden
          example: false
          type: boolean
        isStateHidden:
          description: Whether the state is hidden
          example: false
          type: boolean
        isZipCodeHidden:
          description: Whether the zip code is hidden
          example: false
          type: boolean
      type: object
    OrderProduct:
      description: Individual product within an order
      properties:
        currency:
          description: Price currency code
          example: USD
          type: string
        discountAmount:
          description: Discount amount applied
          example: $5.00
          type: string
        image:
          allOf:
          - $ref: '#/components/schemas/Im

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