Custom API Blocks

A Custom API Block lets you pull in live data from an external API and display it dynamically inside your email templates. This means you can show categorized data—like product lists, news items, or any other grouped content—and style it just the way you want right inside the Topol editor. This documentation provides a detailed guide on how to structure your API endpoints and style the data within your templates.

Why use Custom API Blocks?

This feature lets you build dynamic email sections that automatically update from your data source without manual editing. For example, you can create product catalogs, event lists, or news sections that pull fresh data every time you use the template.

API Endpoint Structure

To use a Custom API Block, your API needs to provide two things:

1. Feeds Endpoint:

This is a list of categories or groups. For example, if you're showing products, this could be product categories like "Shoes," "Hats," or "Accessories." The API will send back something like this:

Expected Response for the Feed Endpoint

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Feed 1"
    },
    {
      "id": 2,
      "name": "Feed 2"
    },
    {
      "id": 3,
      "name": "Feed 3"
    },
    {
      "id": 4,
      "name": "Feed 4"
    }
  ],
  "total_records": 4
}

2. Items Endpoint:

For each category, this endpoint returns the detailed items to show. For example, the actual products within a category. The data might look like this:

Expected Response for the Items Endpoint

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Block 1",
      "image": "https://storage.googleapis.com/topol-io-plugin-97de3577-4897-4379-9699-a51756301fab/plugin-assets/17326/user/warsaw.jpg",
      "href": "https://www.topol.io",
      "my-text-1": "My text 1 in block 1",
      "my-text-2": "My text 2 in block 1",
      "my-text-3": "My text 3 in block 1",
      "feed_id": 1
    },
    {
      "id": 2,
      "name": "Block 2",
      "image": "https://storage.googleapis.com/topol-io-plugin-97de3577-4897-4379-9699-a51756301fab/plugin-assets/17326/user/prague.jpg",
      "href": "https://www.topol.io",
      "my-text-1": "My text 1 in block 2",
      "my-text-2": "My text 2 in block 2",
      "my-text-3": "My text 3 in block 2",
      "feed_id": 1
    },
    {
      "id": 3,
      "name": "Block 3",
      "image": "https://storage.googleapis.com/topol-io-plugin-97de3577-4897-4379-9699-a51756301fab/plugin-assets/17326/user/bridge.jpg",
      "href": "https://www.topol.io",
      "my-text-1": "My text 1 in block 3",
      "my-text-2": "My text 2 in block 3",
      "my-text-3": "My text 3 in block 3",
      "feed_id": 1
    }
  ],
  "total_records": 3
}

How to Configure a Custom API Block

The configuration for a Custom API Block defines how the data is mapped and styled within your template. Below is a detailed example of the configuration.

Example of a Custom API Block

  apiBlocks: {
      testBlock: {
        itemsURL: "https://example.test/my-block",
        feedsURL:
          "https://example.test/my-block-feeds",
        name: "Test Block",
        pluralName: "Test Blocks",
        icon: "",
        blockStructure: {
          image: {
            defaultValue:
              "https://s3-eu-west-1.amazonaws.com/ecomail-assets/editor/pp1.png",
            label: "Image",
            width: 250,
            align: "center",
          },
          href: {
            defaultValue: "*|MY_HREF|*",
          },
          "my-text-1": {
            defaultValue: "*|MY_TEXT_1|*",
            label: "My Text 1",
            "font-size": "16px",
            color: "#123456",
            "font-family": "Helvetica, Arial, sans-serif",
            "font-weight": "bold",
          },
          "my-text-2": {
            defaultValue: "*|MY_TEXT_2|*",
            label: "My Text 2",
            "font-size": "14px",
            color: "#654321",
            "font-family": "Helvetica, Arial, sans-serif",
            "font-weight": "normal",
          },
          "my-text-3": {
            defaultValue: "*|MY_TEXT_3|*",
            label: "My Text 3",
            "font-size": "12px",
            color: "#000000",
            "font-family": "Helvetica, Arial, sans-serif",
            "font-weight": "normal",
            "font-style": "italic",
          },
          button: {
            defaultValue: "Click me",
            label: "Button",
            align: "center",
            "background-color": "#123456",
            color: "#ffffff",
            "font-size": "16px",
            "font-family": "Helvetica, Arial, sans-serif",
            "font-weight": "bold",
            "font-style": "italic",
            "text-transform": "uppercase",
            "text-decoration": "none",
            "border-radius": "3px",
            padding: "10px 20px 10px 20px",
          },
        },
      },
    },

Styling Attributes

The block configuration includes several customizable styling attributes for different elements within the Custom API Block.

Image

• defaultValue Default image URL.
• label Descriptive label for the image.
• width Image width (in pixels).
• align Alignment of the image (e.g., center, left, right).

Hyperlink (href)

• defaultValue Default URL or placeholder for the hyperlink.

Text Field

Each text field can be customized with various styling attributes:

• defaultValue Default text or placeholder.
• label Descriptive label for the text field.
• font-size Font size (e.g., 16px).
• color Text color (e.g., #123456).
• font-family Font family (e.g., Helvetica, Arial, sans-serif).
• font-weight Font weight (e.g., bold, normal).
• font-style Font style (e.g., italic).

Button

• defaultValue Default button text.
• label Descriptive label for the button.
• align Button alignment (e.g., center).
• background-color Background color of the button.
• color Text color.
• font-size Font size.
• font-family Font family.
• font-weight Font weight.
• font-style Font style.
• text-transform Text transformation (e.g., uppercase).
• text-decoration Text decoration (e.g., none).
• border-radius Border radius (in pixels).
• padding Padding around the button (e.g., 10px 20px 10px 20px).