These endpoints are in beta and are subject to change.
A beta revision header (
2024-07-15.pre
) is required to use these beta APIs. Klaviyo APIs in beta are not intended for use in production. See our versioning and deprecation policy for more information.
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
. -
data
-
content
The text or HTML content shown in the universal content block.
-
styles
A set of style options to apply to the block (see Supported styles).
-
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).
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-07-15.pre' \
--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/"
}
}
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.
When making a Get All Universal Content or Get Universal Content request, here's an example of how a universal content block should look in your 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/"
}
}
}
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 thecontent
as well as existingstyles
anddisplay_options
. Otherwise, the data for those fields will be cleared.
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-07-15.pre' \
--data '
{
"data": {
"type": "template-universal-content",
"id": "4fc3b48d7f404d3ebd579b0d1c9ffe5c"
"attributes": {
"definition": {
"content_type": "block",
"type": "text",
"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": "text",
"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 name | Description |
---|---|
block_background_color | Background color of the block (e.g., "#ffffff" ) |
block_border_color | Border color of the block (e.g., "#000000" ). |
block_border_style | Border style (e.g., "solid" ). Supports CSS border-style values. |
block_padding_left | Amount (in pixels) of left padding on the block. Defaults to 18. |
block_padding_right | Amount (in pixels) of right padding on the block. Defaults to 18. |
block_padding_bottom | Amount (in pixels) of bottom padding on the block. Defaults to 9. |
block_padding_top | Amount (in pixels) of top padding on the block. Defaults to 9. |
color | Foreground color of text and text decoration (e.g., "#000000" ). |
inner_padding_bottom | Bottom padding on the text area. This is additive with block-level padding. |
inner_padding_left | Left padding on the text area. This is additive with block-level padding. |
inner_padding_right | Right padding on the text area. This is additive with block-level padding. |
inner_padding_top | Top padding on the text area. This is additive with block-level padding. |
letter_spacing | Pixel-based letter-spacing CSS property (e.g., 8 ). |
line_height | Percentage-based line-height CSS property (e.g.,150 ). |
text_align | See text-align CSS property (e.g., "center" ). |
text_table_layout | See 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 name | Description |
---|---|
show_on | Determines which platforms display the block. Options include: all , desktop , mobile . |
visible_check | A check to determine whether a recipient will see the block (e.g., "person.Country == \"Canada\"" ). Maps to Show/Hide Logic in the UI. |
content_repeat | Options include:
|