Email Content

Intro

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

Use this API to read and replace the content of an email. The content ID is the same as the template id returned when a template is created.

Content structure

Content follows a strict hierarchy:

Content
  └── 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 content.

Section types

Each section's type field determines its functionality. Content 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 content 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 content 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

Content uses 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 content 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 updating content, 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

Content locking

Content becomes locked when an associated campaign starts sending. Attempting to update locked content returns 409 Conflict.

Warning: Content used in a completed campaign send is permanently locked and cannot be modified through the API.

Constraints

Constraint	Value
`sections`	At least 1 required
Columns per row	Max 4
Column width	Max 100% or max 2000px
Unsubscribe link	Required — at least one text or HTML block must contain `[[unsubscribe_link]]`
IDs (path parameter)	24-character hexadecimal

Example: Update email content

PUT /api/email-content/{id} replaces the entire content structure. You must provide the full generalSettings and all desired sections — omitted sections are deleted.

curl --request PUT \
     --url https://api.omnisend.com/api/email-content/68beca12d2e99b0c8d19fd5e \
     --header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Omnisend-Version: 2026-03-15' \
     --data '{
  "generalSettings": {
    "content": {
      "backgroundColor": "#FFFFFF",
      "width": "600px",
      "fontFamily": "Arial, sans-serif",
      "fontSize": "16px",
      "color": "#212121"
    },
    "logo": {
      "id": "6985dd9a02eca41c40466abf",
      "source": "/image/newsletter/6985dd9a02eca41c40466abf",
      "altText": "logo",
      "width": 248,
      "height": 86
    },
    "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;\">Hello [[contact.first_name]]!</p>",
                  "styleProperties": {
                    "padding": "16px"
                  },
                  "stylePresetID": "paragraph"
                }
              ]
            }
          ]
        }
      ],
      "styleProperties": {
        "backgroundColor": "#FFFFFF"
      }
    },
    {
      "id": "699d6eaf7169b6c8fc33dcd4",
      "rows": [
        {
          "id": "699d6eaf7169b6c8fc33dcd5",
          "columns": [
            {
              "id": "699d6eaf7169b6c8fc33dcd6",
              "width": "552px",
              "blocks": [
                {
                  "id": "699d6eaf7169b6c8fc33dcd7",
                  "type": "text",
                  "text": "<p style=\"text-align: center; margin: 0px;\"><a href=\"[[preference_link]]\" data-translation-key=\"preference\" target=\"_blank\">Update preferences</a> or <a href=\"[[unsubscribe_link]]\" data-translation-key=\"unsubscribe\" target=\"_blank\">Unsubscribe</a></p>",
                  "styleProperties": {
                    "padding": "12px",
                    "color": "#000000",
                    "linkColor": "#55ADFF"
                  },
                  "stylePresetID": "footnote"
                }
              ]
            }
          ]
        }
      ],
      "styleProperties": {
        "paddingLeft": "24px",
        "paddingRight": "24px",
        "paddingTop": "12px",
        "paddingBottom": "12px",
        "backgroundColor": "#FFFFFF"
      }
    }
  ]
}'