Email Universal Layouts

Intro

Endpoint: https://api.omnisend.com/api/email-universal-layouts

Use this API to create, retrieve, update, and delete reusable email layouts. Define a layout once — such as a header or footer — and reference it from any template; changes propagate automatically to all templates that use it.

Layout structure

A universal layout contains a single content field which is a section. That section follows a strict hierarchy:

UniversalLayout
  └── Content (Section)
        └── Rows[]
              └── Columns[]
                    └── Blocks[]

• Content is a single section that defines the layout's structure and styling.
• Rows group columns horizontally within the section.
• Columns define the layout width and contain blocks.
• Blocks are the actual content elements (text, images, buttons, etc.).

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

Block types

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

Referencing layouts from templates

Templates reference a universal layout by setting settings.universalLayoutID on a section with type universal_layout. When the template is read, the layout's content is resolved and returned inline.

Warning: Deleting a universal layout automatically expands its content inline into all templates that reference it. The templates retain the layout's content at the time of deletion but will no longer receive future updates.

Listing and filtering

The list endpoint returns layouts sorted by creation time (newest first) with cursor-based pagination.

Note: Do not use after and before simultaneously.

Updating layouts

The PUT endpoint performs a full replace — the entire layout content must be provided, not just the changed fields.

Example: Create a universal layout

POST /api/email-universal-layouts creates a new reusable layout. All IDs must be unique 24-character hex strings within the layout.

curl --request POST \
     --url https://api.omnisend.com/api/email-universal-layouts \
     --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": "Standard Header",
  "content": {
    "id": "69770b2f7f774c6fb6f57192",
    "styleProperties": {},
    "rows": [
      {
        "id": "69770b2f7f774c6fb6f57193",
        "columns": [
          {
            "id": "69770b2f7f774c6fb6f57194",
            "blocks": [
              {
                "id": "69770b2f7f774c6fb6f57195",
                "type": "logo",
                "logo": {
                  "link": "[[account.website]]",
                  "resizeWidth": 120
                }
              },
              {
                "id": "69770b2f7f774c6fb6f57196",
                "type": "text",
                "text": "<p style=\"text-align: center;\">Free shipping on orders over $50</p>"
              }
            ]
          }
        ]
      }
    ]
  }
}'

See also

• Errors & responses
• Pagination