Skip to content

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 an email.

Templates

List all templates

GET https://api.litmus.com/v3/personalize/templates

Request

AttributeTypeDescription
filter[contentType]stringfilter list of templates by contentType
bash
curl https://api.litmus.com/v3/personalize/templates
curl https://api.litmus.com/v3/personalize/templates?filter[contentType]=timers

Response

AttributeTypeDescription
dataarraylist of templates
<template_n>.typestringtemplates
<template_n>.idstringtemplate identifier to use in other requests
<template_n>.attributes.slugstringtemplate identifier (deprecated)
<template_n>.attributes.contentTypestringcontent type for the template
<template_n>.attributes.colorsarraylist of configurable color attributes the template supports
json
{
    "data": [
        {
            "type": "templates",
            "id": "default_timer",
            "attributes": {
                "slug": "default_timer",
                "contentType": "timers",
                "colors": [
                    "text",
                    "background",
                    "label_text",
                    "digits_text"
                ]
            },
            "links": {
                "self": "https://api.litmus.com/v3/personalize/templates/default_timer"
            }
        },
        {
            "type": "templates",
            "id": "text",
            "attributes": {
                "slug": "text",
                "contentType": "sentiment_trackers",
                "colors": [
                    "prompt",
                    "background",
                    "poll_option_text",
                    "option_background"
                ]
            },
            "links": {
                "self": "http://api.litmus.localhost:3000/v3/personalize/templates/text"
            }
        },
        # ... more templates
    ]
}

Get a template

GET https://api.litmus.com/v3/personalize/templates/:id

Request

bash
curl https://api.litmus.com/v3/personalize/templates/default_timer

Response

AttributeTypeDescription
typestringtemplates
idstringtemplate identifier to use in other requests
attributes.slugstringtemplate identifier (deprecated)
attributes.contentTypestringcontent type for the template
attributes.colorsarraylist of configurable color attributes the template supports
json
{
    "data": {
        "type": "templates",
        "id": "default_timer",
        "attributes": {
            "slug": "default_timer",
            "contentType": "timers",
            "colors": [
                "text",
                "background",
                "label_text",
                "digits_text"
            ]
        },
        "links": {
            "self": "https://api.litmus.com/v3/personalize/templates/default_timer"
        }
    }
}

Countdown timers

Preview

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

Request

AttributeTypeDescription
templateSlugstringtemplate identifier
countdown.timeISO 8601 timestamp (UTC)countdown target (should be future-dated)
expiration.messagestringdisplayed instead of the clock when the timer reaches zero
fallback.messagestringoptional message to display to Apple MPP-affected recipients
fontstringone of Montserrat, Open Sans, Roboto, Lato, Poppins, Noto Sans, Source Serif 4, Lora, PT Serif, Noto Serif, or Roboto Slab
colors.backgroundstringhex format color code for timer background
colors.textstringhex format color code for timer numbers and labels
json
{
    "data": {
        "attributes": {
            "templateSlug": "default_timer",
            "countdown": {
                "time": "2024-02-09T00:00:00Z",
            },
            "expiration": {
                "message": "The sale has ended."
            },
            "fallback": {
                "message": "Sale ends on November 20th!"
            },
            "font": "Roboto",
            "colors": {
                "background": "#33A8CC",
                "text": "#FFFFFF"
            }
        }
    }
}

Response

AttributeTypeDescription
idstringtimer identifier
typestringJSON API type declaration
attributes.*.image.hrefstringURL for timer image variation (expiration, fallback, timer)
attributes.*.image.typestringimage format for the associated url
json
{
    "data": {
        "id": "1",
        "type": "timers",
        "attributes": {
            "countdown": {
                "image": {
                    "href": "http://api.litmus.com/countdown_1",
                    "type": "image/png"
                }
            },
            "expiration": {
                "image": {
                    "href": "http://api.litmus.com/expiration_1",
                    "type": "image/png"
                }
            },
            "fallback": {
                "image": {
                    "href": "http://api.litmus.com/fallback_1",
                    "type": "image/png"
                }
            }
        }
    }
}

Publish

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

TIP

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

Request

AttributesTypeDescription
templateSlugstringtemplate identifier
countdown.timeISO 8601 timestamp (UTC)countdown target (should be future-dated)
expiration.messagestringdisplayed when the timer reaches zero
fallback.messagestringoptional message to display to Apple MPP-affected recipients
fontstringone of Montserrat, Open Sans, Roboto, Lato, Poppins, Noto Sans, Source Serif 4, Lora, PT Serif, Noto Serif, or Roboto Slab
colors.backgroundstringhex format color code for timer background
colors.textstringhex format color code for timer numbers and labels
json
{
    "data": {
        "attributes": {
            "templateSlug": "default_timer",
            "countdown": {
                "time": "2024-02-09T00:00:00Z",
            },
            "expiration": {
                "message": "The sale has ended."
            },
            "fallback": {
                "message": "Sale ends on November 20th!"
            },
            "font": "Roboto",
            "colors": {
                "background": "#33A8CC",
                "text": "#FFFFFF"
            }
        }
    }

}

Response

AttributeTypeDescription
idstringtimer identifier
typestringJSON API type declaration
attributes.timer.image.hrefstringURL for timer image
attributes.timer.image.typestringimage format for the associated url, always image/gif
json
{
    "data": {
        "id": "1",
        "type": "timers",
        "attributes": {
            "timer": {
                "image": {
                    "href": "http://image.na.ca.litmus.com/t/timer_1.gif?exp=2024-02-09T02%3A00%3A00.0000000%2B00%3A00",
                    "type": "image/gif"
                }
            }
        }
    }
}

The attributes.timer.image.href URL returned when publishing supports overriding the following query string parameters using merge tags:

ParameterTypeDescription
expISO 8601 timestamp (UTC)countdown target (should be future-dated)

Progress bars

Preview

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

Request

AttributeTypeDescription
templateSlugstringtemplate identifier
minimumValueintegerlower bound of progress range
maximumValueintegerupper bound of progress range
colors.backgroundstringhex format color code for background
colors.progressFillstringhex format color code for progress bar fill
colors.progressBackgroundstringhex format color code for area beneath the fill
colors.progressValuestringhex format color code for progress number value
colors.minimumValuestringhex format color code for minimum number value
colors.maximumValuestringhex format color code for maximum number value
preview.progressValueintegersets the progress amount used for this preview (should be between minimum/maximum_value)
json
{
    "data": {
        "attributes": {
            "templateSlug": "linear_progress_bar",
            "minimumValue": 0,
            "maximumValue": 100,
            "colors": {
                "background": "#FFFFFF",
                "progressFill": "#40DC59",
                "progressBackground": "#EEEEEE",
                "progressValue": "#333333",
                "minimumValue": "#333333",
                "maximumValue": "#333333"
            },
            "preview": {
                "progressValue": 75
            }
        }
    }
}

Response

AttributeTypeDescription
idstringprogress bar identifier
typestringJSON API type declaration
attributes.image.hrefstringURL for progress bar preview image
attributes.image.typestringimage format for the associated url
json
{
    "data": {
        "id": "1",
        "type": "progress_bars",
        "attributes": {
            "image": {
                "href": "http://api.litmus.com/progress_bar_1",
                "type": "image/png"
            }
        }
    }
}

Publish

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

TIP

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

Request

AttributesTypeDescription
templateSlugstringtemplate identifier
minimumValueintegerlower bound of progress range
maximumValueintegerupper bound of progress range
colors.backgroundstringhex format color code for background
colors.progressFillstringhex format color code for progress bar fill
colors.progressBackgroundstringhex format color code for area beneath the fill
colors.progressValuestringhex format color code for progress number value
colors.minimumValuestringhex format color code for minimum number value
colors.maximumValuestringhex format color code for maximum number value
json
{
    "data": {
        "attributes": {
            "templateSlug": "linear_progress_bar",
            "minimumValue": 0,
            "maximumValue": 100,
            "colors": {
                "background": "#FFFFFF",
                "progressFill": "#40DC59",
                "progressBackground": "#EEEEEE",
                "progressValue": "#333333",
                "minimumValue": "#333333",
                "maximumValue": "#333333"
            }
        }
    }
}

Response

AttributeTypeDescription
idstringtimer identifier
typestringJSON API type declaration
attributes.image.hrefstringURL for progress bar image
attributes.image.typestringimage format for the associated url
json
{
    "data": {
        "id": "1",
        "type": "progress_bars",
        "attribute": {
            "image": {
                "href": "http://image.na.ca.litmus.com/pb/progress_bar_1.png?min=0&max=100&cur=MERGE_YOUR_VALUE",
                "type": "image/png"
            }
        }
    }
}

The attributes.image.href URL returned when publishing supports overriding the following query string parameters using merge tags:

ParameterTypeDescription
minintegerlower bound of progress range
maxintegerupper bound of progress range
curintegersets the progress amount (should be between minimum/maximum_value)

Sentiment trackers

Preview

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

Request

AttributeTypeDescription
templateSlugstringtemplate identifier
colors.resultsValuestringhex format color code for result values
json
{
    "data": {
        "attributes": {
            "templateSlug": "emoji_sentiment_tracker",
            "colors": {
                "resultsValue": "#000000"
            }
        }
    }
}

Response

AttributeTypeDescription
idstringsentiment tracker identifier
typestringJSON API type declaration
attributes.<option_n>.image.hrefstringURL for sentiment tracker option
attributes.<option_n>.image.typestringimage format for sentiment tracker option
json
{
    "data": {
        "id": "1",
        "type": "sentiment_trackers",
        "attributes": {
            "option_1": {
                "image": {
                    "href": "http://api.litmus.com/sentiment_tracker_1_option_1",
                    "type": "image/png"
                }
            },
            "option_2": {
                "image": {
                    "href": "http://api.litmus.com/sentiment_tracker_1_option_2",
                    "type": "image/png"
                }
            },
            "option_3": {
                "image": {
                    "href": "http://api.litmus.com/sentiment_tracker_1_option_3",
                    "type": "image/png"
                }
            }
        }
    }
}

Publish

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

Request

AttributeTypeDescription
templateSlugstringtemplate identifier
urlintegerwhere we'll redirect users after voting
colors.resultsValuestringhex format color code for result values
json
{
    "data": {
        "attributes": {
            "templateSlug": "emoji_sentiment_tracker",
            "url": "https://litmus.com",
            "colors": {
                "resultsValue": "#000000"
            }
        }
    }
}

Response

AttributeTypeDescription
idstringsentiment tracker identifier
typestringJSON API type declaration
attributes.<option_n>.image.hrefstringURL for sentiment tracker option
attributes.<option_n>.image.typestringimage format for sentiment tracker option
attributes.<option_n>.vote.hrefstringvote URL for sentiment tracker option
attributes.<option_n>.vote.hrefstringvote URL format sentiment tracker option, always text/html
json
{
    "data": {
        "id": 1,
        "type": "sentiment_trackers",
        "attributes": {
            "option_1": {
                "image": {
                    "href": "http://api.litmus.com/sentiment_tracker_1_option_1",
                    "type": "image/png"
                },
                "vote": {
                    "href": "https://click.litmus.com/sentiment_tracker_1_option_1",
                    "type": "text/html"
                }
            },
            "option_2": {
                "image": {
                    "href": "http://api.litmus.com/sentiment_tracker_1_option_2",
                    "type": "image/png"
                },
                "vote": {
                    "href": "https://click.litmus.com/sentiment_tracker_1_option_2",
                    "type": "text/html"
                }
            },
            "option_3": {
                "image": {
                    "href": "http://api.litmus.com/sentiment_tracker_1_option_3",
                    "type": "image/png"
                },
                "vote": {
                    "href": "https://click.litmus.com/sentiment_tracker_1_option_3",
                    "type": "text/html"
                }
            }
        }
    }
}

Report

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

Request

AttributeTypeDescription
idstringsentiment tracker identifier

Response

AttributeTypeDescription
totalClicksintegertotal clicks
attributes.<option_n>.clickCountstringnumber of clicks for this option
attributes.<option_n>.clickPercentstringpercentage of clicks for this option
json
{
  "data": {
    "type": "sentiment_trackers_report",
    "id": "3",
    "attributes": {
      "totalClicks": 1234,
      "option_1": {
        "clickCount": 1000,
        "clickPercent": 81
      },
      "option_2": {
        "clickCount": 234,
        "clickPercent": 19
      }
    }
  }
}