Personalize API Early Access

TIP

Access to our APIs is evaluated on a case-by-case basis. To find out if your use case is one that we support feel free to get in touch with the details of your project. partners@litmus.com

Litmus Personalize provides the ability to create dynamic content that can be embedded into an email. We offer several variations of these, which are referred to as "content types", and each type is configured and used slightly different; the type-specific documentation below covers the relevant details.

Using the Personalize API, you'll primarily be performing 2 functions on any content type: previewing and publishing. Previewing is intended to be used during the authoring process while adjusting parameters, and returns images to help visualize those adjustments. Publishing finalizes a piece of content and provides an artifact that can be permanently embedded into a user's email.

Countdown timers

Preview

POST https://api.litmus.com/v3/personalize/timers/preview

Request

Attribute	Type	Description
`template_slug`	string	template identifier
`expiration.time`	ISO 8601 timestamp (UTC)	countdown target (should be future-dated)
`expiration.message`	string	displayed instead of the clock when the timer reaches zero
`font`	string	one of `Montserrat`, `Open Sans`, `Roboto`, `Lato`, `Poppins`, `Noto Sans`, `Source Serif 4`, `Lora`, `PT Serif`, `Noto Serif`, or `Roboto Slab`
`colors.background`	string	hex format color code for timer background
`colors.text`	string	hex format color code for timer numbers and labels
`mpp_message`	string	optional message to display to Apple MPP-affected recipients

json

{
    "data": {
        "attributes": {
            "template_slug": "default_timer",
            "expiration": {
                "time": "2024-02-09T00:00:00Z",
                "message": "The sale has ended."
            },
            "font": "Roboto",
            "colors": {
                "background": "#33A8CC",
                "text": "#FFFFFF"
            },
            "mpp_message": "Sale ends on November 20th!"
        }
    }
}

Response

Attribute	Type	Description
`id`	integer	timer identifier
`type`	string	JSON API type declaration
`links.*.href`	string	URL for timer image variation (expiration, fallback, timer)
`links.*.type`	string	image format for the associated url

json

{
    "data": {
        "id": 1,
        "type": "timers",
        "links": {
            "expiration_image": {
                "href": "http://api.litmus.com/expiration_1",
                "type": "image/png"
            },
            "fallback_image": {
                "href": "http://api.litmus.com/fallback_1",
                "type": "image/png"
            },
            "timer_image": {
                "href": "http://api.litmus.com/timer_1",
                "type": "image/png"
            }
        }
    }
}

Publish

POST https://api.litmus.com/v3/personalize/timers

TIP

The request body for publishing is the same used for previewing.

Request

Attributes	Type	Description
`template_slug`	string	template identifier
`expiration.time`	ISO 8601 timestamp (UTC)	countdown target (should be future-dated)
`expiration.message`	string	displayed when the timer reaches zero
`font`	string	one of `Montserrat`, `Open Sans`, `Roboto`, `Lato`, `Poppins`, `Noto Sans`, `Source Serif 4`, `Lora`, `PT Serif`, `Noto Serif`, or `Roboto Slab`
`colors.background`	string	hex format color code for timer background
`colors.text`	string	hex format color code for timer numbers and labels
`mpp_message`	string	optional message to display to Apple MPP-affected recipients

json

{
    "data": {
        "attributes": {
            "template_slug": "default_timer",
            "expiration": {
                "time": "2024-02-09T00:00:00Z",
                "message": "The sale has ended."
            },
            "font": "Roboto",
            "colors": {
                "background": "#33A8CC",
                "text": "#FFFFFF"
            },
            "mpp_message": "Sale ends on November 20th!"
        }
    }
}

Response

Attribute	Type	Description
`id`	integer	timer identifier
`type`	string	JSON API type declaration
`links.related.href`	string	URL for timer image
`links.related.type`	string	image format for the associated url, always `image/gif`

json

{
    "data": {
        "id": 1,
        "type": "timers",
        "links": {
            "related": {
                "href": "http://image.na.ca.litmus.com/t/timer_1.gif?exp=2024-02-09T02%3A00%3A00.0000000%2B00%3A00",
                "type": "image/gif"
            }
        }
    }
}

The links.related.href URL returned when publishing supports overriding the following parameters using merge tags:

Parameter	Type	Description
`exp`	ISO 8601 timestamp (UTC)	countdown target (should be future-dated)

Progress bars

Preview

POST https://api.litmus.com/v3/personalize/progress-bars/preview

Request

Attribute	Type	Description
`template_slug`	string	template identifier
`minimum_value`	integer	lower bound of progress range
`maximum_value`	integer	upper bound of progress range
`colors.background`	string	hex format color code for background
`colors.progress_fill`	string	hex format color code for progress bar fill
`colors.progress_background`	string	hex format color code for area beneath the fill
`colors.progress_value`	string	hex format color code for progress number value
`colors.minimum_value`	string	hex format color code for minimum number value
`colors.maximum_value`	string	hex format color code for maximum number value
`preview_data.progress_value`	integer	sets the progress amount used for this preview (should be between `minimum/maximum_value`)

json

{
    "data": {
        "attributes": {
            "template_slug": "linear_progress_bar",
            "minimum_value": 0,
            "maximum_value": 100,
            "colors": {
                "background": "#FFFFFF",
                "progress_fill": "#40DC59",
                "progress_background": "#EEEEEE",
                "progress_value": "#333333",
                "minimum_value": "#333333",
                "maximum_value": "#333333"
            },
            "preview_data": {
                "progress_value": 75
            }
        }
    }
}

Response

Attribute	Type	Description
`id`	integer	progress bar identifier
`type`	string	JSON API type declaration
`links.related.href`	string	URL for progress bar preview image
`links.related.type`	string	image format for the associated url

json

{
    "data": {
        "id": 1,
        "type": "progress_bars",
        "links": {
            "related": {
                "href": "http://api.litmus.com/progress_bar_1",
                "type": "image/png"
            }
        }
    }
}

Publish

POST https://api.litmus.com/v3/personalize/progress-bars

TIP

The request body for publishing is the same used for previewing, with the exception of preview_data.

Request

Attributes	Type	Description
`template_slug`	string	template identifier
`minimum_value`	integer	lower bound of progress range
`maximum_value`	integer	upper bound of progress range
`colors.background`	string	hex format color code for background
`colors.progress_fill`	string	hex format color code for progress bar fill
`colors.progress_background`	string	hex format color code for area beneath the fill
`colors.progress_value`	string	hex format color code for progress number value
`colors.minimum_value`	string	hex format color code for minimum number value
`colors.maximum_value`	string	hex format color code for maximum number value

json

{
    "data": {
        "attributes": {
            "template_slug": "linear_progress_bar",
            "minimum_value": 0,
            "maximum_value": 100,
            "colors": {
                "background": "#FFFFFF",
                "progress_fill": "#40DC59",
                "progress_background": "#EEEEEE",
                "progress_value": "#333333",
                "minimum_value": "#333333",
                "maximum_value": "#333333"
            }
        }
    }
}

Response

Attribute	Type	Description
`id`	integer	timer identifier
`type`	string	JSON API type declaration
`links.related.href`	string	URL for progress bar image
`links.related.type`	string	image format for the associated url

json

{
    "data": {
        "id": 1,
        "type": "progress_bars",
        "links": {
            "related": {
                "href": "http://image.na.ca.litmus.com/pb/progress_bar_1.png?min=0&max=100&cur=MERGE_YOUR_VALUE",
                "type": "image/png"
            }
        }
    }
}

The links.related.href URL returned when publishing supports overriding the following parameters using merge tags:

Parameter	Type	Description
`min`	integer	lower bound of progress range
`max`	integer	upper bound of progress range
`cur`	integer	sets the progress amount (should be between `minimum/maximum_value`)

Sentiment trackers

Preview

POST https://api.litmus.com/v3/personalize/sentiment-trackers/preview

Request

Attribute	Type	Description
`template_slug`	string	template identifier
`colors.results_value`	string	hex format color code for result values

json

{
    "data": {
        "attributes": {
            "template_slug": "emoji_sentiment_tracker",
            "colors": {
                "results_value": "#000000"
            }
        }
    }
}

Response

Attribute	Type	Description
`id`	integer	sentiment tracker identifier
`type`	string	JSON API type declaration
`links.<option_n>.href`	string	URL for sentiment tracker option
`links.<option_n>.type`	string	image format for sentiment tracker option

json

{
    "data": {
        "id": 1,
        "type": "sentiment_trackers",
        "links": {
            "option_1": {
                "href": "http://api.litmus.com/sentiment_tracker_1_option_1",
                "type": "image/png"
            },
            "option_2": {
                "href": "http://api.litmus.com/sentiment_tracker_1_option_2",
                "type": "image/png"
            },
            "option_3": {
                "href": "http://api.litmus.com/sentiment_tracker_1_option_3",
                "type": "image/png"
            }
        }
    }
}

Publish

POST https://api.litmus.com/v3/personalize/sentiment-trackers

Request

Attribute	Type	Description
`template_slug`	string	template identifier
`url`	integer	where we'll redirect users after voting
`colors.results_value`	string	hex format color code for result values

json

{
    "data": {
        "attributes": {
            "template_slug": "emoji_sentiment_tracker",
            "url": "https://litmus.com",
            "colors": {
                "results_value": "#000000"
            }
        }
    }
}

Response

Attribute	Type	Description
`id`	integer	sentiment tracker identifier
`type`	string	JSON API type declaration
`links.<option_n>.href`	string	URL for sentiment tracker option
`links.<option_n>.type`	string	image format for sentiment tracker option
`links.<option_n>.meta.click_href`	string	click-tracked URL for sentiment tracker option

json

{
    "data": {
        "id": 1,
        "type": "sentiment_trackers",
        "links": {
            "option_1": {
                "href": "http://api.litmus.com/sentiment_tracker_1_option_1",
                "type": "image/png",
                "meta": {
                    "click_href": "https://click.litmus.com/sentiment_tracker_1_option_1"
                }
            },
            "option_2": {
                "href": "http://api.litmus.com/sentiment_tracker_1_option_2",
                "type": "image/png",
                "meta": {
                    "click_href": "https://click.litmus.com/sentiment_tracker_1_option_2"
                }
            },
            "option_3": {
                "href": "http://api.litmus.com/sentiment_tracker_1_option_3",
                "type": "image/png",
                "meta": {
                    "click_href": "https://click.litmus.com/sentiment_tracker_1_option_3"
                }
            }
        }
    }
}

Report

GET https://api.litmus.com/v3/personalize/sentiment-trackers/:id/report

Request

Attribute	Type	Description
`id`	integer	sentiment tracker identifier

Response

Attribute	Type	Description
`total_clicks`	integer	total clicks
`options`	array	list of statistics for each option
`<option_n>.click_count`	integer	number of clicks for this option
`<option_n>.click_percent`	integer	percentage of clicks for this option

json

{
  "data": {
    "type": "sentiment_trackers_report",
    "id": 3,
    "attributes": {
      "total_clicks": 1234,
      "options": [
        {
          "option_1": {
            "click_count": 1000,
            "click_percent": 81
          }
        },
        {
          "option_2": {
            "click_count": 234,
            "click_percent": 19
          }
        }
      ]
    }
  }
}

Personalize API Early Access ​

Countdown timers ​

Preview ​

Request ​

Response ​

Publish ​

Request ​

Response ​

Progress bars ​

Preview ​

Request ​

Response ​

Publish ​

Request ​

Response ​

Sentiment trackers ​

Preview ​

Request ​

Response ​

Publish ​

Request ​

Response ​

Report ​

Request ​

Response ​

Personalize API Early Access

Countdown timers

Preview

Request

Response

Publish

Request

Response

Progress bars

Preview

Request

Response

Publish

Request

Response

Sentiment trackers

Preview

Request

Response

Publish

Request

Response

Report

Request

Response