Skip to content

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

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"
}
HOW HELPFUL WAS THIS PAGE?
New Stuff!