Email Templates

Intro

Endpoint: https://api.omnisend.com/api/email-templates

Use this API to create, retrieve, delete, and import email templates. Each template defines the structure of an email using a hierarchical layout of sections, rows, columns, and blocks.

Template structure

A template follows a strict hierarchy:

Template
  └── Sections[]
        └── Rows[]
              └── Columns[]
                    └── Blocks[]

Sections are the top-level content containers. Each section can have its own styling, visibility settings, and optional features like product recommenders or conditional filters.
Rows group columns horizontally within a section.
Columns define the layout width and contain blocks.
Blocks are the actual content elements (text, images, buttons, etc.).

Every section, row, column, and block requires a unique id within the template.

Section types

Each section's type field determines its functionality. A template can mix multiple section types.

Type	Description
`""`	Plain layout section (or omit the `type` field)
`products_listing`	Manually selected products — one `product` block per picked product
`product_recommender`	Personalized product recommendations — requires a `productRecommender` object on the section, up to 12 product blocks
`product_cart_recovery`	Abandoned-cart recovery (used in cart-abandonment automations) — recipient's cart items are injected at send time, up to 12 product blocks
`product_back_in_stock`	Back-in-stock automation — restocked products are injected at send time, up to 12 product blocks
`universal_layout`	Wraps a saved universal layout — set `universalLayoutID` in its `settings`; the layout's content is resolved at read time
`dynamic_list`	Repeats its content over a list (e.g. ordered products) — configured via `dynamicList` in its `settings`
`preheader`	"View in browser" preheader (campaign templates only)
`badge`	Omnisend badge (read-only, free-plan only)

Note: Product sections only accept product blocks. For dynamic sections (product_recommender, product_cart_recovery, product_back_in_stock), each block is a slot that the platform fills with a personalized product per recipient at send time.

Block types

Type	Description
`text`	Rich text content with HTML formatting and personalization tags
`button`	Clickable button with link, text, and styling
`image`	Image with optional link, alt text, and resize settings
`video`	Video thumbnail with link
`logo`	Brand logo with link
`menu`	Menu of links — items provided via `components` as text blocks with role `menu_text`
`social`	Social media icon links
`htmlCode`	Custom HTML with separate style and body content
`lineSpace`	Horizontal line or spacer for layout separation
`preheader`	"View in browser" link text (campaign templates only)
`product`	Product card with title, image, price, and button
`discount`	Discount code block
`staticDiscount`	Static discount code (WooCommerce)
`dynamicDiscount`	Dynamic discount code (WooCommerce)
`orderSummary`	Order identification details
`orderProducts`	Ordered product list
`orderTotal`	Pricing breakdown
`orderAddresses`	Billing and shipping addresses

Note: The html block type is deprecated and read-only. Use htmlCode instead.

Style presets

Templates use button presets and text presets for consistent styling across blocks.

If you provide buttonPresets, you must include these three required presets:

| primary_button | secondary_button | tertiary_button |

If you provide textPresets, you must include these five required presets:

Additional custom presets can be added alongside the required ones.

Universal layout references

A template section can reference a universal layout via universalLayoutID in its settings. When set, the section acts as a lightweight pointer — the layout's content is resolved at read time.

When creating or updating a template, sections with a universalLayoutID are stored as references only; their rows content is ignored.

Product recommender configuration

Sections with type: "product_recommender" require a productRecommender object on the section. It configures the strategy used to generate recommendations at send time and the filters that narrow the candidate set.

Field	Description
`type`	Recommender strategy (see strategies table below)
`fallbackType`	Strategy used when `type` returns no results. Allowed values: `newest`, `popular`, `mostViewed`
`isOutOfStockIncluded`	Whether to include out-of-stock products (default: `false`)
`includeCategories`	Category IDs to include in recommendations
`excludeCategories`	Category IDs to exclude from recommendations
`excludeProducts`	Product IDs to exclude from recommendations
`purchaseExclusionDays`	Skip products purchased in the last N days
`recencyMonths`	Time window in months for recency-based strategies
`priceFrom`	Minimum product price

The type field selects from these strategies:

`type`	Description	Plan
`newest`	Most recently added products	All plans
`popular`	Best-selling products	All plans
`mostViewed`	Most-viewed products across all recipients	All plans
`personalized`	Items similar to the recipient's past purchases	Pro plan
`recentlyViewed`	Products the recipient recently viewed	Pro plan

Note: personalized and recentlyViewed require the Personalized product recommender feature (Pro plan). The API accepts both types regardless of plan; for brands without the feature, the recommender silently substitutes the section's fallbackType at send time. If fallbackType is itself a personalized strategy, it falls back to newest. No error is returned.

General settings

generalSettings controls the global appearance of the email.

Field	Description
`content`	Email canvas: width, background color, font family, font size, text color
`body`	Outer body background color and optional background image
`buttonPresets`	Reusable button styles referenced by blocks via `stylePresetID`
`textPresets`	Reusable text styles referenced by blocks via `stylePresetID`
`logo`	Shared logo settings (link, resize width)
`gmail`	Gmail annotation settings for the promotions tab

HTML import

Use POST /api/email-templates/import to create a template from raw HTML.

Constraint	Value
Max request body size	1 MB
Name	Required, 1–255 characters
HTML	Required

The import process extracts <style> tags from the HTML <head> and places them in the template's style block. The <body> content becomes the template's HTML code block. If no <body> tag is found, the full HTML is used as-is.

Constraints

Constraint	Value
Template name	1–255 characters
Content width	300px–2000px
Font size	3px–100px
IDs (path parameters)	24-character hexadecimal
List page size	1–100 items (default 50)
Name filter (`nameContains`)	Max 200 characters
Sort fields	`createdAt` (default), `name`
Sort direction	`asc`, `desc` (default)

Example: Create a template

POST /api/email-templates creates a new template with the provided structure and settings.

curl --request POST \
     --url https://api.omnisend.com/api/email-templates \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Omnisend-Version: 2026-03-15' \
     --data '{
  "name": "Welcome Email",
  "generalSettings": {
    "content": {
      "backgroundColor": "#FFFFFF",
      "width": "600px",
      "fontFamily": "Arial, sans-serif",
      "fontSize": "16px",
      "color": "#212121"
    },
    "body": {
      "backgroundColor": "#EDEEF0"
    },
    "buttonPresets": [
      {
        "id": "primary_button",
        "name": "Primary",
        "styles": {
          "backgroundColor": "#383838",
          "borderRadius": "4px",
          "fontFamily": "Arial, sans-serif",
          "fontSize": "16px",
          "color": "#FFFFFF",
          "paddingLeft": "24px",
          "paddingRight": "24px",
          "paddingTop": "12px",
          "paddingBottom": "12px"
        }
      },
      {
        "id": "secondary_button",
        "name": "Secondary",
        "styles": {
          "backgroundColor": "#FFFFFF",
          "border": "2px solid #383838",
          "borderRadius": "4px",
          "fontFamily": "Arial, sans-serif",
          "fontSize": "16px",
          "color": "#383838",
          "paddingLeft": "24px",
          "paddingRight": "24px",
          "paddingTop": "12px",
          "paddingBottom": "12px"
        }
      },
      {
        "id": "tertiary_button",
        "name": "Tertiary",
        "styles": {
          "backgroundColor": "transparent",
          "borderRadius": "0px",
          "fontFamily": "Arial, sans-serif",
          "fontSize": "16px",
          "textDecoration": "underline",
          "color": "#383838",
          "paddingLeft": "24px",
          "paddingRight": "24px",
          "paddingTop": "12px",
          "paddingBottom": "12px"
        }
      }
    ],
    "textPresets": [
      {
        "id": "heading_large",
        "name": "Heading Large",
        "styles": {
          "fontFamily": "Arial, sans-serif",
          "fontSize": "36px",
          "color": "#212121",
          "lineHeight": "125%"
        }
      },
      {
        "id": "heading_medium",
        "name": "Heading Medium",
        "styles": {
          "fontFamily": "Arial, sans-serif",
          "fontSize": "28px",
          "color": "#212121",
          "lineHeight": "130%"
        }
      },
      {
        "id": "heading_small",
        "name": "Heading Small",
        "styles": {
          "fontFamily": "Arial, sans-serif",
          "fontSize": "22px",
          "color": "#212121",
          "lineHeight": "135%"
        }
      },
      {
        "id": "paragraph",
        "name": "Paragraph",
        "styles": {
          "fontFamily": "Arial, sans-serif",
          "fontSize": "16px",
          "color": "#212121",
          "lineHeight": "150%"
        }
      },
      {
        "id": "footnote",
        "name": "Footnote",
        "styles": {
          "fontFamily": "Arial, sans-serif",
          "fontSize": "12px",
          "color": "#757575",
          "lineHeight": "150%"
        }
      }
    ]
  },
  "sections": [
    {
      "id": "aaa000000000000000000001",
      "rows": [
        {
          "id": "aaa000000000000000000002",
          "columns": [
            {
              "id": "aaa000000000000000000003",
              "width": "600px",
              "blocks": [
                {
                  "id": "aaa000000000000000000004",
                  "type": "text",
                  "text": "<p style=\"margin-top: 0px; margin-bottom: 0px;\">Welcome, [[contact.first_name]]!</p>",
                  "stylePresetID": "paragraph",
                  "styleProperties": {
                    "padding": "16px"
                  }
                }
              ]
            }
          ]
        }
      ],
      "styleProperties": {
        "backgroundColor": "#FFFFFF"
      }
    }
  ]
}'

Example: Import template from HTML

POST /api/email-templates/import creates a template from raw HTML. The <body> content becomes the template's HTML code block.

curl --request POST \
     --url https://api.omnisend.com/api/email-templates/import \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Omnisend-Version: 2026-03-15' \
     --data '{
  "name": "My Imported Template",
  "html": "<html><head><style>p { text-align: center; }</style></head><body><p>Hello world</p></body></html>"
}'