HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
API Reference
ChangelogHelp CenterCommunityContact Us

Universal Content API overview

Before you begin

Check out our general API overview to make sure you’re ready to get started with specific endpoints.

Marketers can utilize universal content to create reusable blocks of content that repeatedly appear in email marketing. Once saved as universal content, blocks can be added to any email from Klaviyo's email template editor. Any changes saved to a universal content block will propagate to all email templates using that block. Use our Universal Content API to streamline the process of creating universal content that can be added to Klaviyo email templates.

Use cases

  • Seamlessly create universal content blocks from HTML blocks present throughout your app and help documentation (e.g., product blocks and images) for repeated use in email templates.
  • Retrieve universal content blocks by content type.
  • Update existing universal content blocks across email templates.
  • Delete universal content blocks.

Data model

A universal content block has the following structure:

  • id

    The ID of the universal content block.

  • attributes

    • name

      The name of the universal content block.

    • definition

      • content_type

        The type of universal content block, e.g., block.

      • type

        The type of universal content within the block, e.g., text or html.

      • data

        • content

          The text or HTML content shown in the universal content block.

        • styles

          A set of style options to apply to the text block (see Supported styles).

          📘

          When working with HTML blocks, do not include the styles field.

        • display_options

          An object of fields that map to display options that can be set in the template editor (See Supported display options).

    • created

      The timestamp of when the universal content block was created.

    • updated

      The timestamp of when the universal content block was last updated.

    • screenshot_status

      The status of a screenshot for generating the universal content block's thumbnail.

    • screenshot_url

      A URL of the universal content block's screenshot.

📘

Use our Universal Content Postman collection to quickly get started testing and building with the Universal Content API.

Create a universal content block

Use the Create Universal Content endpoint to add a universal content block to the customer's account. Text blocks have some default padding applied; if you are creating a text block with HTML contents, you will likely want to set the block's padding to 0 (See supported styles).

Text block example

curl --request POST \
     --url https://a.klaviyo.com/api/template-universal-content/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-10-15' \
     --data '
{
    "data": {
        "type": "template-universal-content",
        "attributes": {
            "name": "Block Name",
            "definition": {
                "content_type": "block",
                "type": "text",
                "data": {
                    "content": "INSERT_TEXT_OR_HTML_CONTENT_HERE",
                    "styles": {
                        "block_padding_bottom": 0,
                        "block_padding_top": 0,
                        "block_padding_right": 0,
                        "block_padding_left": 0
                    },
                    "display_options": {}
                }
            }
        }
    }
}
'

{
    "data": {
        "type": "template-universal-content",
        "id": "e8f468726ec341bba0739d6ac5146e6f",
        "attributes": {
            "name": "Block Name",
            "definition": {
                "content_type": "block",
                "type": "text",
                "data": {
                    "content": "INSERT_TEXT_OR_HTML_CONTENT_HERE",
                    "display_options": {},
                    "styles": {
                        "block_padding_bottom": 0,
                        "block_padding_left": 0,
                        "block_padding_right": 0,
                        "block_padding_top": 0
                    }
                }
            },
            "created": "2024-09-04T18:58:42.652634+00:00",
            "updated": "2024-09-04T18:58:42.652661+00:00",
            "screenshot_status": "never_generated",
            "screenshot_url": "https://klaviyo-template-thumbnails.s3.amazonaws.com/saved_content/e8f468726ec341bba0739d6ac5146e6f?AWSAccessKeyId=AKIAVLN5ZGG3QIBVU7GL&Signature=WkE3pbHVP%2Bxpv1dVuRXs5cfaqYk%3D&Expires=1725649122"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/template-universal-content/e8f468726ec341bba0739d6ac5146e6f/"
        }
    },
    "links": {
        "self": "https://a.klaviyo.com/api/template-universal-content/"
    }
}

HTML block example

curl --request POST \
     --url https://a.klaviyo.com/api/template-universal-content/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-10-15' \
     --data '
{
    "data": {
        "type": "template-universal-content",
        "attributes": {
            "name": "Block Name",
            "definition": {
                "content_type": "block",
                "type": "html",
                "data": {
                    "content": "INSERT_HTML_CONTENT_HERE",
                    "styles": {},
                    "display_options": {}
                }
            }
        }
    }
}
'

{
    "data": {
        "type": "template-universal-content",
        "id": "e8f468726ec341bba0739d6ac5146e6f",
        "attributes": {
            "name": "Block Name",
            "definition": {
                "content_type": "block",
                "type": "html",
                "data": {
                    "content": "INSERT_HTML_CONTENT_HERE",
                    "display_options": {},
                    "styles": {}
                }
            },
            "created": "2024-09-04T18:58:42.652634+00:00",
            "updated": "2024-09-04T18:58:42.652661+00:00",
            "screenshot_status": "never_generated",
            "screenshot_url": "https://klaviyo-template-thumbnails.s3.amazonaws.com/saved_content/e8f468726ec341bba0739d6ac5146e6f?AWSAccessKeyId=AKIAVLN5ZGG3QIBVU7GL&Signature=WkE3pbHVP%2Bxpv1dVuRXs5cfaqYk%3D&Expires=1725649122"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/template-universal-content/e8f468726ec341bba0739d6ac5146e6f/"
        }
    },
    "links": {
        "self": "https://a.klaviyo.com/api/template-universal-content/"
    }
}

📘

Note that the screenshot in the screenshot_url is generated asynchronously, so it might take a few minutes before it exists.

Retrieving universal content blocks

The Get All Universal Content endpoint is useful for retrieving information such as block content and styling for all universal content blocks.

Use the Get Universal Content endpoint to fetch this information for a specified universal content block ID.

Below are examples of how a universal content text block and HTML block might look in your query response:

{
    "data": {
        "type": "template-universal-content",
        "id": "4fc3b48d7f404d3ebd579b0d1c9ffe5c",
        "attributes": {
            "name": "NAME",
            "definition": {
                "content_type": "block",
                "type": "text",
                "data": {
                    "content": "TEXT_OR_HTML_CONTENT_HERE",
                    "styles": {
                        "block_padding_left": 0,
                        "block_padding_right": 0,
                        "block_padding_top": 0,
                        "block_padding_bottom": 0
                    },
                    "display_options": {}
                }
            },
            "created": "2024-05-23T14:26:36.530847+00:00",
            "updated": "2024-05-23T14:26:39.010728+00:00",
            "screenshot_status": "completed",
            "screenshot_url": "https://klaviyo-template-thumbnails.s3.amazonaws.com/saved_content/4fc3b48d7f404d3ebd579b0d1c9ffe5c"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/template-universal-content/4fc3b48d7f404d3ebd579b0d1c9ffe5c/"
        }
    }
}

{
    "data": {
        "type": "template-universal-content",
        "id": "4fc3b48d7f404d3ebd579b0d1c9ffe5c",
        "attributes": {
            "name": "NAME",
            "definition": {
                "content_type": "block",
                "type": "html",
                "data": {
                    "content": "TEXT_OR_HTML_CONTENT_HERE",
                    "styles": {},
                    "display_options": {}
                }
            },
            "created": "2024-05-23T14:26:36.530847+00:00",
            "updated": "2024-05-23T14:26:39.010728+00:00",
            "screenshot_status": "completed",
            "screenshot_url": "https://klaviyo-template-thumbnails.s3.amazonaws.com/saved_content/4fc3b48d7f404d3ebd579b0d1c9ffe5c"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/template-universal-content/4fc3b48d7f404d3ebd579b0d1c9ffe5c/"
        }
    }
}

Updating a universal content block

❗️

User confirmation is strongly recommended before updating existing universal content.

Updating a universal content block with Update Universal Content will visually update all templates using the universal content (see example below).

🚧

All JSON supplied in the definition field will fully replace what's currently stored. For example, if you only need to update the content, you must include the content as well as existing styles and display_options. Otherwise, the data for those fields will be cleared.

Text block

curl --request PATCH \
     --url https://a.klaviyo.com/api/template-universal-content/4fc3b48d7f404d3ebd579b0d1c9ffe5c/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-10-15' \
     --data '
{
  "data": {
    "type": "template-universal-content",
    "id": "4fc3b48d7f404d3ebd579b0d1c9ffe5c"
    "attributes": {
      "definition": {
        "content_type": "block",
        "type": "text",
        "data": {
          "content": "UPDATED_TEXT_FOR_THE_BLOCK_HERE",
          "styles": {},
          "display_options": {}
        }
      }
    }
  }
}
'

{
    "data": {
        "type": "template-universal-content",
        "id": "4fc3b48d7f404d3ebd579b0d1c9ffe5c",
        "attributes": {
            "name": "NAME",
            "definition": {
                "content_type": "block",
                "type": "text",
                "data": {
                    "content": "UPDATED_TEXT_FOR_THE_BLOCK_HERE",
                    "styles": {},
                    "display_options": {}
                }
            },
            "created": "2024-05-23T14:26:36.530847+00:00",
            "updated": "2024-05-23T14:26:39.010728+00:00",
            "screenshot_status": "completed",
            "screenshot_url": "https://klaviyo-template-thumbnails.s3.amazonaws.com/saved_content/4fc3b48d7f404d3ebd579b0d1c9ffe5c"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/template-universal-content/4fc3b48d7f404d3ebd579b0d1c9ffe5c/"
        }
    }
}

HTML block

curl --request PATCH \
     --url https://a.klaviyo.com/api/template-universal-content/4fc3b48d7f404d3ebd579b0d1c9ffe5c/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-10-15' \
     --data '
{
  "data": {
    "type": "template-universal-content",
    "id": "4fc3b48d7f404d3ebd579b0d1c9ffe5c"
    "attributes": {
      "definition": {
        "content_type": "block",
        "type": "html",
        "data": {
          "content": "UPDATED_HTML_FOR_THE_BLOCK_HERE",
          "styles": {},
          "display_options": {}
        }
      }
    }
  }
}
'

{
    "data": {
        "type": "template-universal-content",
        "id": "4fc3b48d7f404d3ebd579b0d1c9ffe5c",
        "attributes": {
            "name": "NAME",
            "definition": {
                "content_type": "block",
                "type": "html",
                "data": {
                    "content": "UPDATED_HTML_FOR_THE_BLOCK_HERE",
                    "styles": {},
                    "display_options": {}
                }
            },
            "created": "2024-05-23T14:26:36.530847+00:00",
            "updated": "2024-05-23T14:26:39.010728+00:00",
            "screenshot_status": "completed",
            "screenshot_url": "https://klaviyo-template-thumbnails.s3.amazonaws.com/saved_content/4fc3b48d7f404d3ebd579b0d1c9ffe5c"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/template-universal-content/4fc3b48d7f404d3ebd579b0d1c9ffe5c/"
        }
    }
}

Deleting a universal content block

❗️

User confirmation is strongly recommended before deleting universal content.

Use the Delete Universal Content endpoint to delete a universal content block, given a universal content block ID. Once the block has been deleted, any templates using the universal content block will no longer all be attached to a universal content block instance. The templates will visually appear unchanged after the deletion of the content block, i.e., deleted blocks will be turned into a regular, non-universal block.

Supported styles

View the table below for the available style options for text blocks.

Style nameDescription
block_background_colorBackground color of the block (e.g., "#ffffff")
block_border_colorBorder color of the block (e.g., "#000000").
block_border_styleBorder style (e.g., "solid"). Supports CSS border-style values.
block_padding_leftAmount (in pixels) of left padding on the block. Defaults to 18.
block_padding_rightAmount (in pixels) of right padding on the block. Defaults to 18.
block_padding_bottomAmount (in pixels) of bottom padding on the block. Defaults to 9.
block_padding_topAmount (in pixels) of top padding on the block. Defaults to 9.
colorForeground color of text and text decoration (e.g., "#000000").
inner_padding_bottomBottom padding on the text area. This is additive with block-level padding.
inner_padding_leftLeft padding on the text area. This is additive with block-level padding.
inner_padding_rightRight padding on the text area. This is additive with block-level padding.
inner_padding_topTop padding on the text area. This is additive with block-level padding.
letter_spacingPixel-based letter-spacing CSS property (e.g., 8).
line_heightPercentage-based line-height CSS property (e.g.,150).
text_alignSee text-align CSS property (e.g., "center").
text_table_layoutSee table-layout CSS property (e.g., "auto").

Supported display options

The display_options object contains fields that map to the options set for Display in the template editor.

Display option nameDescription
show_onDetermines which platforms display the block. Options include: all, desktop, mobile.
visible_checkA check to determine whether a recipient will see the block (e.g., "person.Country == \"Canada\""). Maps to Show/Hide Logic in the UI.
content_repeatOptions include:

  • repeat_for, the key to repeat, typically a path to an event or profile property (e.g., "event.items").
  • item_alias, the alias of the repeated item to use in the block's contents (e.g., "item").

Power smarter
digital relationships
By entering your information and clicking “Sign up,” you consent to receive marketing emails (such as newsletters, blog posts, webinars, event invitations and new product updates) from Klaviyo from time to time. You can unsubscribe at any time by clicking on the “Unsubscribe” link at the bottom of our emails. For more information on how we process your personal information and what rights you have in this respect, please see our Privacy Policy.
Terms and Privacy Trademarks Security