Create preference center
post
/preference_center/v1
Use this endpoint to create a preference center to allow users to manage their notification preferences for email campaigns.
Prerequisites
To use this endpoint, you’ll need an API key with the preference_center.update
permission.
Check out Creating a preference center via API for details on how to include this in your email campaigns.
Rate limit
This endpoint has a rate limit of 10 requests per minute, per workspace.
Request body
1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
1
2
3
4
5
6
7
8
9
10
{
"name": "string",
"preference_center_title": "string",
"preference_center_page_html": "string",
"confirmation_page_html": "string",
"state": (optional) Choose `active` or `draft`. Defaults to `active` if not specified,
"options": {
"meta-viewport-content": "string", (optional) Only the `content` value of the meta tag
}
}
Request parameters
Parameter | Required | Data Type | Description |
---|---|---|---|
name |
Required | String | The name of the preference center that meets the following requirements: - Only contains letters, numbers, hyphens, and underscores - Does not have spaces |
preference_center_title |
Optional | String | The title for the preference center and confirmation pages. If a title is not specified, the title of the pages will default to “Preference Center”. |
preference_center_page_html |
Required | String | The HTML for the preference center page. |
confirmation_page_html |
Required | String | The HTML for the confirmation page. |
state |
Optional | String | Choose active or draft . Defaults to active if not specified. |
options |
Optional | Object | Attributes: meta-viewport-content . When present, a viewport meta tag will be added to the page with content= <value of attribute> . |
note:
The preference center name can’t be edited after it’s created.
Liquid tags
Refer to the following Liquid tags that can be included in your HTML to generate a user’s subscription state on the preference center page.
User subscription state
Liquid | Description |
---|---|
{{subscribed_state.${email_global}}} |
Get the global email subscribed state for the user (such as “opted_in”, “subscribed”, or “unsubscribed”. |
{{subscribed_state.${<subscription_group_id>}}} |
Get the subscribed state of the specified subscription group for the user (such as “subscribed” or “unsubscribed”). |
Form inputs and action
Liquid | Description |
---|---|
{% form_field_name :email_global_state %} |
Indicates that a specific form input element corresponds to the user’s global email subscribed state. The user’s selection state should be “opted_in”, “subscribed”, or “unsubscribed” when the form is submitted with selection data for the global email subscribed state. If it’s a checkbox, the user will either be “opted_in” or “unsubscribed”. For a hidden input, the “subscribed” state will also be valid. |
{% form_field_name :subscription_group <subscription_group_id> %} |
Indicates that a specific form input element corresponds to a given subscription group. The user’s selection state should be either “subscribed” or “unsubscribed” when the form is submitted with selection data for a specific subscription group. |
{{preference_center_submit_url}} |
Generates URL for form submission. |
Example response
1
2
3
4
5
6
{
"preference_center_api_id": "preference_center_api_id_example",
"liquid_tag": "{{preference_center.${MyPreferenceCenter2022-09-22}}}",
"created_at": "2022-09-22T18:28:07+00:00",
"message": "success"
}