--- title: "Get universal layouts" method: GET path: "/email-universal-layouts" tags: ["Email Universal Layouts"] --- # Get universal layouts `GET /email-universal-layouts` ## Request - Base URL: `https://api.omnisend.com/api` - URL: `https://api.omnisend.com/api/email-universal-layouts` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://app.omnisend.com/oauth2/token` scopes: `email-templates.read` - API key in header `Authorization` 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. ## Query parameters - `limit` integer - `after` string - `before` string - `nameContains` string ## Headers - `Omnisend-Version` string, required ## Response `200` List of universal layouts with pagination - ListUniversalLayoutsResponse: Represents the response for listing universal layouts - `paging` PagingResponse: Cursor-based pagination metadata - `cursors` CursorsResponse: Cursor pointers for paginating forward and backward through results - `after` string, nullable: Opaque cursor for fetching the next page of results - `before` string, nullable: Opaque cursor for fetching the previous page of results - `hasMore` boolean: Whether there are more items available beyond the current page - `limit` integer: Maximum number of items returned per page - `universalLayouts` UniversalLayout[]: List of universal layouts - `content` Section: Section is a single section of the template - `id` string: Section unique identifier - must be unique within the template - `productRecommender` ProductRecommender: Product recommender settings for the product recommendations section - `excludeCategories` string[]: Categories to exclude from recommendations - `excludeProducts` string[]: Products to exclude from recommendations - `fallbackType` string: Product recommender fallback type - `includeCategories` string[]: Categories to include in recommendations - `isOutOfStockIncluded` boolean: Whether to include out-of-stock products in recommendations - `priceFrom` number: Minimum price filter for product recommendations - `purchaseExclusionDays` integer: Number of days to exclude recently purchased products - `recencyMonths` integer: Number of months to consider for recency-based recommendations - `type` string: Product recommender type - `rows` Row[], nullable: Section rows - used to group content into logical sections. Null for a section that references a universal layout, and must be null or empty when sent for one. Locked email content (a campaign that has started sending) is the exception: its universal layout sections keep the layout rows the email was sent with. - `columns` Column[]: Row columns - used to group content into logical columns - `blocks` Block[]: Column blocks - used to group content into logical blocks - `button` Button: Button block settings - … - `components` BlockComponent[]: Components - the parts a block renders that are not covered by its own content field. Some blocks tag each part with a 'role', and which roles they need is decided by their 'type': a 'discount' block holds the code, the redeem button and the expiry date, a 'menu' block holds its items, a 'product' block holds the product's image, title, description, prices and button. A countdown nests one un-roled image component whose source is generated by the server. Other blocks nest components without a role, and blocks that render everything from a dedicated content field have no components at all. See BlockComponent. - … - `countdown` Countdown: Countdown block settings. The timer is identified by timerID; src is generated and signed by Omnisend. - … - `discount` Discount: 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'. - … - `dynamicDiscount` Discount: 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'. - … - `html` string: Deprecated: use HTMLCode instead. Read-only, will be removed in future versions. - `htmlCode` HTMLCode: HTML code block with separate style and body content - … - `id` string: Block unique identifier - must be unique within the template - `image` Image: Image block for displaying images in the email - … - `lineSpace` LineSpace: Horizontal line or space block for layout separation - … - `logo` Logo: Logo block for displaying a logo in the email - … - `orderAddresses` OrderAddresses: Order addresses block displaying billing and shipping information - … - `orderProducts` OrderProducts: Order products block displaying ordered items - … - `orderSummary` OrderSummary: Order summary block displaying order identification details - … - `orderTotal` OrderTotal: Order total block displaying pricing breakdown - … - `preheader` Preheader: Preheader block to setup View in Browser link text formattings Text is formatted as ```TextLinkText``` - … - `product` Product: Product block for displaying product information - … - `role` 'product_image' | 'product_title' | 'product_description' | 'product_prices' | 'product_button' | 'discount_code' | 'discount_button' | 'discount_expiration_date' | 'product_current_price' | 'product_old_price' | 'menu_text': Block role - `secondaryStylePresetID` string: Secondary style preset ID - ID of the secondary style preset. Used for order blocks styling as smaller text style. - `social` Social: Social block for displaying social media icons and links - … - `staticDiscount` Discount: 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'. - … - `stylePresetID` string: Style preset ID - ID of the style preset. Used for Button or Text block styling. ID must be present in template General Settings. - `styleProperties` StyleProperties: Style properties for the section - … - `text` string: Text content of the block - supports HTML formatting and personalization tags - `type` 'html' | 'htmlCode' | 'text' | 'image' | 'video' | 'logo' | 'menu' | 'social' | 'button' | 'product' | 'discount' | 'staticDiscount' | 'dynamicDiscount' | 'orderSummary' | 'orderProducts' | 'orderTotal' | 'orderAddresses' | 'lineSpace' | 'preheader' | 'price' | 'countdown': Block type. Notes: - 'html' is read-only and cannot be set on create/update. - 'menu' is a container block with no dedicated content field — items must be provided via 'components' as text blocks with role 'menu_text', and styling is configured through 'stylePresetID' and 'styleProperties'. - 'discount' is the block for an offer. The offer is configured in the 'discount' object, and everything the recipient sees must be provided via 'components' as role-tagged blocks — a text block with role 'discount_code' (required, exactly one), plus an optional button with role 'discount_button' and an optional text block with role 'discount_expiration_date'. The store issues a code per recipient when the email is sent, so 'discount.code' carries the placeholder XXXX-XXXX-XXXX. Writing the offer as plain text instead leaves a code that was never created in the store, so the recipient cannot redeem it. - 'dynamicDiscount' is the WooCommerce equivalent of 'discount' — same object, same components and placeholder, except that the 'discount_button' component is required. A 'discount' block on a WooCommerce store is skipped when the email is sent, so it ships the placeholder to the recipient as the code. - 'staticDiscount' (WooCommerce) instead carries one fixed code that already exists in the store, and gets no code at send time. It does not accept a 'discount_button'. Use it only when the brand explicitly asked for a fixed code. - 'countdown' requires one un-roled image component. Its image source and countdown.src are generated from countdown.timerID and cannot be supplied by the client. - `video` Video: Video block for displaying a video in the email - … - `id` string: Column unique identifier - must be unique within the template - `styleProperties` StyleProperties: Style properties for the section - `alignment` string: Alignment - used to align the content horizontally - `backgroundColor` string: Background color - used to set the background color of the content - `backgroundImageID` string: Background image ID - ID of the background image asset. Must be present in Image API - `backgroundPosition` string: Background position - used to position the background image - `backgroundRepeat` string: Background repeat - used to repeat the background image - `backgroundSize` string: Background size - used to size the background image - `border` string: Border - used to add a border to the content - `borderRadius` string: Border radius - `color` string: Text color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size - `fontStyle` string: Font style - `fontWeight` string: Font weight - `innerPadding` string: Inner padding - `innerPaddingBottom` string: Inner padding bottom - `innerPaddingLeft` string: Inner padding left - `innerPaddingRight` string: Inner padding right - `innerPaddingTop` string: Inner padding top - `isBackgroundPaddingsExcluded` boolean: Whether to exclude background paddings - used to exclude paddings from the background image - `letterSpacing` string: Letter spacing - spacing between letters - `lineHeight` string: Line height - `linkColor` string: Link color - `padding` string: Padding - `paddingBottom` string: Padding bottom - `paddingLeft` string: Padding left - `paddingRight` string: Padding right - `paddingTop` string: Padding top - `priceColor` string: Price color - used to color the price text - `secondaryColor` string: Secondary color - used to color the secondary text - `textBackgroundColor` string: Text Background color - used to set the text background color - `textDecoration` string: Text decoration - `verticalAlign` string: Vertical alignment - used to align the content vertically - `width` string: Column width - used to set the width of the column - `id` string: Row unique identifier - must be unique within the template - `styleProperties` StyleProperties: Style properties for the section - `alignment` string: Alignment - used to align the content horizontally - `backgroundColor` string: Background color - used to set the background color of the content - `backgroundImageID` string: Background image ID - ID of the background image asset. Must be present in Image API - `backgroundPosition` string: Background position - used to position the background image - `backgroundRepeat` string: Background repeat - used to repeat the background image - `backgroundSize` string: Background size - used to size the background image - `border` string: Border - used to add a border to the content - `borderRadius` string: Border radius - `color` string: Text color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size - `fontStyle` string: Font style - `fontWeight` string: Font weight - `innerPadding` string: Inner padding - `innerPaddingBottom` string: Inner padding bottom - `innerPaddingLeft` string: Inner padding left - `innerPaddingRight` string: Inner padding right - `innerPaddingTop` string: Inner padding top - `isBackgroundPaddingsExcluded` boolean: Whether to exclude background paddings - used to exclude paddings from the background image - `letterSpacing` string: Letter spacing - spacing between letters - `lineHeight` string: Line height - `linkColor` string: Link color - `padding` string: Padding - `paddingBottom` string: Padding bottom - `paddingLeft` string: Padding left - `paddingRight` string: Padding right - `paddingTop` string: Padding top - `priceColor` string: Price color - used to color the price text - `secondaryColor` string: Secondary color - used to color the secondary text - `textBackgroundColor` string: Text Background color - used to set the text background color - `textDecoration` string: Text decoration - `verticalAlign` string: Vertical alignment - used to align the content vertically - `settings` Settings: Settings for the section - `backgroundType` string: Background type - determines whether the section background is a color or image - `customFonts` CustomFont[]: Custom fonts used in this section - `id` string: ID of the custom font - `dynamicList` DynamicList: Dynamic list settings for repeating content blocks - `columnCount` integer: Number of columns in the list layout - `layout` string: Layout type for the list items - `listPath` string: Data path for the list items source - `repetitionCount` integer: Maximum number of items to display - `excludeProducts` string[]: 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. - `filter` Filter: Filter for conditional display of content - `operator` string: Filter operator - logical operator to combine multiple filter rules - `rules` Rule[]: Filter rules - array of filter rules - `operator` string: Filter operator - comparison operator for the filter condition - `property` FilterProperty: Filter property for conditional display of content - … - `value` string: Filter value - value to compare against the property - `isColumnStackDisabled` boolean: Whether to disable column stacking - used to display content in a single column - `isOutOfStockHidden` boolean: Whether to hide out of stock products from product sections - `isProductImagesFitted` boolean: Whether to fit product images to the container - used to display product images in a single line - `sideBySideProductLayout` string: Side by side product layout - `universalLayoutID` string: Universal layout ID - ID of the universal layout the section references. If present, the section is a universal_layout reference whatever its type: it is returned with rows null, its content comes from the universal layout, and rows sent with it are rejected. Locked email content (a campaign that has started sending) instead returns the layout content the email was sent with. - `styleProperties` StyleProperties: Style properties for the section - `alignment` string: Alignment - used to align the content horizontally - `backgroundColor` string: Background color - used to set the background color of the content - `backgroundImageID` string: Background image ID - ID of the background image asset. Must be present in Image API - `backgroundPosition` string: Background position - used to position the background image - `backgroundRepeat` string: Background repeat - used to repeat the background image - `backgroundSize` string: Background size - used to size the background image - `border` string: Border - used to add a border to the content - `borderRadius` string: Border radius - `color` string: Text color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size - `fontStyle` string: Font style - `fontWeight` string: Font weight - `innerPadding` string: Inner padding - `innerPaddingBottom` string: Inner padding bottom - `innerPaddingLeft` string: Inner padding left - `innerPaddingRight` string: Inner padding right - `innerPaddingTop` string: Inner padding top - `isBackgroundPaddingsExcluded` boolean: Whether to exclude background paddings - used to exclude paddings from the background image - `letterSpacing` string: Letter spacing - spacing between letters - `lineHeight` string: Line height - `linkColor` string: Link color - `padding` string: Padding - `paddingBottom` string: Padding bottom - `paddingLeft` string: Padding left - `paddingRight` string: Padding right - `paddingTop` string: Padding top - `priceColor` string: Price color - used to color the price text - `secondaryColor` string: Secondary color - used to color the secondary text - `textBackgroundColor` string: Text Background color - used to set the text background color - `textDecoration` string: Text decoration - `verticalAlign` string: Vertical alignment - used to align the content vertically - `type` 'products_listing' | 'product_recommender' | 'product_cart_recovery' | 'product_back_in_stock' | 'badge' | 'preheader' | 'dynamic_list' | 'universal_layout' | '': Section type - determines the section functionality and available content options. products_listing: manually selected products. product_recommender: personalized recommendations (requires productRecommender). product_cart_recovery: abandoned cart items. product_back_in_stock: restocked items. preheader: inbox preview text. badge: free-plan branding badge. dynamic_list: repeats content over a list. universal_layout: references a saved universal layout through settings.universalLayoutID. The layout content is resolved when the email is rendered or sent, so the section is returned with rows null and rows sent with it are rejected; change the layout itself through the universal layouts endpoints. Empty string (or field omitted): plain layout section with no special functionality. - `visibility` Visibility: Visibility settings for the template - `isDesktopVisible` boolean: Whether the template is visible on desktop devices - `isMobileVisible` boolean: Whether the template is visible on mobile devices - `createdAt` string: Universal layout created at (read-only) - `id` string: Universal layout unique identifier (read-only) - `name` string: Universal layout name - `snapshotState` string: Universal layout snapshot state (read-only) - `snapshotUrl` string: Universal layout snapshot URL (read-only) - `updatedAt` string: Universal layout updated at (read-only) ## Other responses - `400`: Invalid query parameters or missing brand ID - `401`: Authentication is missing or invalid - `403`: Insufficient permissions for this operation - `410`: API version has been retired - `429`: Rate limit exceeded - `500`: Unexpected error occurred --- [API](https://skmtc.dev/omnisend/apis/email-content-api.md) - [All operations](https://skmtc.dev/omnisend/apis/email-content-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/email-content-api/revisions/4f249eb0de04?raw)