Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kit.com/llms.txt

Use this file to discover all available pages before exploring further.

Dynamic content block plugins share the same base configuration as standard content block plugins—name, description, icon, request URL, and settings JSON—with a few additional fields that power the personalization and preview experience. The sample data that drives the editor preview (and that defines the field names creators can reference in Liquid) is configured on the linked automation event plugin, not on the content block plugin itself. See Sample data lives on the event plugin below.
content block insertion menu
content block configuration
All UI components available for standard content blocks—text inputs, color pickers, search inputs, and the rest of the component library—are available for dynamic content blocks as well.

​
Additional configuration fields

​
dynamic

Set to true to mark this plugin as a dynamic content block. This tells Kit to treat the HTML returned by your endpoint as a Liquid template rather than final, static HTML.

​
identifier

A short, unique string that identifies this content block plugin element within your app (used in the Apps Dashboard and for uniqueness across plugin elements). Rules:
  • Lowercase letters, numbers, and underscores only
  • Must be unique within your app
When the block is linked to an automation event plugin (related_plugin_id), Liquid paths use the linked event node’s identifier, not this content block’s identifier: 
automation.{app_identifier}.{event_node_identifier}.{field_name}
For example, if your app identifier is yourapp and the related event node’s identifier is abandoned_checkout, template variables are scoped under automation.yourapp.abandoned_checkout.*. The content block and event node identifiers are often named similarly by convention, but they are configured separately—only the event node’s identifier appears in that middle segment. The automation event plugin that provides subscriber-specific data for this block. In the Kit App Store builder, this is selected from a dropdown listing your app’s automation event plugins. This links your dynamic content block to the workflow step that captures and stores the data.
Your dynamic content block will only render correctly when used in an automation that includes the linked event plugin. The event plugin is responsible for populating the automation context data that your Liquid variables reference.

​
Sample data lives on the event plugin

When a dynamic content block is linked to an automation event plugin, both the list of fields creators can reference in Liquid and the sample data used for the editor preview are configured on the event plugin, not on the content block plugin. Open your event plugin in Apps → your app → Plugins → [event plugin]. In the Context card, paste a JSON object into Sample data. The top-level keys become the fields creators can reference in Liquid; the nested values are used to render the preview in the email editor. 
{
  "products": [
    {
      "name": "Vintage Wool Sweater",
      "price": "$89.00",
      "quantity": 1,
      "image_url": "https://example.com/images/sweater.jpg",
      "description": "A cozy classic for the cooler months"
    },
    {
      "name": "Canvas Tote Bag",
      "price": "$34.00",
      "quantity": 2,
      "image_url": "https://example.com/images/tote.jpg",
      "description": "Sturdy and stylish everyday carry"
    }
  ],
  "checkout_url": "https://example.com/cart/checkout",
  "subtotal": "$157.00",
  "total": "$157.00",
  "discount_codes": []
}
Make your sample data visually representative. Creators judge how their email will look based on the preview, so use realistic product names, images, and amounts rather than placeholder text.
On the dynamic content block plugin form, the same sample data is shown read-only, with a Configure sample data button that links back to the event plugin. If you need to add a field, edit it on the event plugin and it will become available to every dynamic content block linked to that event.
The sample data you configure here is the same data your event plugin’s fetch_events response should provide at runtime under the per-event context key. See automation node plugin configuration for the runtime side.

​
Request format

When a creator adds your block to an email or adjusts its settings, Kit makes a POST request to your Request URL with the following body: 
{
  "settings": {
    "button_text": "Complete your order",
    "background_color": "#ffffff",
    "title_color": "#000000"
  },
  "styles": {
    "p": { "color": "#333333", "font-family": "Georgia, serif", "font-size": "16px" },
    "h1": { "font-size": "2em", "font-weight": "bold" },
    "h2": { "font-size": "1.5em", "font-weight": "bold" },
    "a": { "color": "#0066cc" },
    "ul": {},
    "ol": {}
  },
  "dynamic": true,
  "context_variable": "abandoned_checkout"
}
When there is no linked automation event plugin, context_variable is omitted.
  • settings — The creator’s current sidebar setting values, same as a standard content block.
  • styles — The surrounding email’s typography styles, keyed by HTML tag (p, h1–h6, a, ul, ol, blockquote). Each value is an object of CSS property/value pairs (e.g. color, font-family, font-size, line-height). Use these to match your block’s output to the email’s design. Tags with no overrides are included as empty objects.
  • dynamic — Always true for dynamic content block requests.
  • context_variable — Present when the block is linked to an automation event plugin. Value is the identifier string of that linked event node (the same value that appears as the middle segment in Liquid: automation.{app_identifier}.{event_node_identifier}.*). Kit does not send merged workflow context or subscriber payloads on this POST—only settings, styles, dynamic, and optionally context_variable. Use context_variable if you need to branch server-side logic between event types; fetch live data from your own systems using settings and your app’s auth model.

​
Response format

Your endpoint should respond with a JSON object. Kit’s response schema requires an html key; other top-level keys are not validated out, but only html is required for success. The html value should be a Liquid template that references automation data using automation.{app_identifier}.{event_node_identifier}.* when linked to an event node: 
{
  "html": "{% if automation.yourapp.abandoned_checkout %}...{% endif %}"
}
On error, return a non-2xx HTTP status. You may include an errors array in the body for debugging or logging: 
{
  "errors": ["No products found"]
}
See liquid templates for guidance on writing the HTML template, including available variables, loops, and email compatibility best practices.

​
Authentication

Dynamic content block plugins use the same OAuth flow as standard plugins. See OAuth authorization for setup details.