Universal Content API overview

🚧
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 definitionfield 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.

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: `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"`).

🚧These endpoints are in beta and are subject to change.

Before you begin

Use cases

Data model

📘

Create a universal content block

📘

Retrieving universal content blocks

Updating a universal content block

❗️

🚧

Deleting a universal content block

❗️

Supported styles

Supported display options

🚧
These endpoints are in beta and are subject to change.