Generate preference page URLs

Use the preference page URL API to generate URLs for a contact’s specific email preference pages, which allows them to manage their email preferences from within authenticated areas of your website.

Please note:

This API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to HubSpot’s Developer Terms & Developer Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API.
Each set of URLs is generated for a specific contact to edit their own preferences. Ensure each link is only shared securely with the owner of the associated email address.

To generate subscription preferences URLs, ensure that your app has authorized the scopes listed below:

communication_preferences.read_write OR
communication_preferences.read AND communication_preferences.write

Generate subscription preference page URLs

Please note:The API described in this article references business units, which is the former name for brands. This change does not impact the businessUnitId parameter.

To generate preference page URLs for a contact, make a POST request to /communication-preferences/v4/links/generate and provide the following query parameters:

channel (required): communication channel, required to be EMAIL.
businessUnitId: you can optionally include the ID of a specific brand, which results in the links that take contacts to pages customized for that brand. On these pages, only subscriptions within that brand will be displayed.

In the request body, you can also include the following properties:

subscriberIdString (required): email address of the contact for whom the subscription preferences page is being generated.
language: language for the preferences page. For translations to work as expected, you should select a language associated with a subscription type. If no language is specified, the system may default to your account’s default language or English.
subscriptionId: ID of a specific subscription type, which may result in that subscription type being highlighted on the preferences page. This parameter must be included to return an unsubscribeSingleUrl link.

The preference page URLs will be returned within the results field of the response. For example, if you wanted to generate a unique email preference page for bh@hubspot.com associated with a businessUnitId of 887987898, you’d make a POST to https://api.hubapi.com/communication-preferences/v4/links/generate?businessUnitId=887987898&channel=EMAIL, then include a request body that resembled the following:

{
  "subscriptionId": 123,
  "subscriberIdString": "bh@hubspot.com",
  "language": "es"
}

The resulting response will look like the following:

{
  "status": "SUCCESS",
  "results": {
    "subscriberIdString": "bh@hubspot.com",
    "managePreferencesUrl": "https://www.hubspot.com/hs/preferences-center/es/page?data=W2nXS...",
    "unsubscribeAllUrl": "https://www.hubspot.com/hs/preferences-center/es/direct?data=W2nXS...",
  }
}

Troubleshoot errors

If your request returns an error, review the error message and code, then follow the troubleshooting steps for that error.

Understand error messages

Most errors follow the following format:

{
  "status": "error",
  "message": "Human-readable error description",
  "correlationId": "unique-request-id",
  "errorCode": "ERROR_CODE_CONSTANT",
  "category": "ERROR_CATEGORY",
  "context": {
    "subscriberIdString": ["user@example.com"],
    "language": ["en"],
    "subscriptionId": ["123"]
  }
}

The information you will find in each property is listed below:

Property name	Description
`status`	Outcome of the request; for errors, this will always return “error”.
`message`	Description of what went wrong.
`correlationId`	Unique identifier for this request.
`errorCode`	Machine-readable code identifying the specific error type.
`category`	High-level error classification, such as `VALIDATION_ERROR`.
`context`	Object containing request parameters that may have caused the error.
`subscriberIdString`	Email address (subscriber identifier) from the request
`language`	Language parameter from the request, if provided.
`subscriptionId`	Subscription ID from the request, if provided.
`businessUnitId`	Business unit ID from the request, if provided.

Troubleshoot common errors

Learn more about the errors that can occur when generating a subscription preferences page URL.

Language not configured

Error code: LANGUAGE_NOT_CONFIGURED
Description: the provided language parameter is invalid.
Troubleshooting steps: assign one of the languages listed in the error property “message” to a subscription type, then wait several minutes to try again.

Subscription type not found

Error code: SUBSCRIPTION_TYPE_NOT_FOUND
Description: the provided subscriptionId parameter is invalid.
Troubleshooting steps: get all subscription types, then confirm that one of them uses the subscriptionId included in the request.

Subscription type & brand mismatch

Error code: SUBSCRIPTION_TYPE_BUSINESS_UNIT_MISMATCH
Description: the provided subscriptionId belongs to a different brand than specified in businessUnitId.
Troubleshooting steps: to resolve this error, try the following:
- Use a subscription type that belongs to the specified brand.
- Omit the businessUnitId parameter.
- Get all subscription types and confirm which subscription types are used for each brand.

Contact not found

Error code: CONTACT_NOT_FOUND
Description: the provided email address is not associated with a contact record in the HubSpot account.
Troubleshooting steps: to resolve this error, try the following:
- Verify the email address belongs to a contact in the HubSpot account.
- Create a contact associated with this email address, then try again.

Invalid channel

Description: the channel parameter contains a value other than EMAIL.
Troubleshooting steps: use channel=EMAIL as the query parameter.

Account & Settings

App Management

Authentication

Automation

CMS

Communication preferences

Conversations

CRM

Events

Files

Marketing

Reporting

Scheduler

Webhooks

Generate preference page URLs

Generate subscription preference page URLs

Troubleshoot errors

Understand error messages

Troubleshoot common errors

Language not configured

Subscription type not found

Subscription type & brand mismatch

Contact not found

Invalid channel

​Generate subscription preference page URLs

​Troubleshoot errors

​Understand error messages

​Troubleshoot common errors

​Language not configured

​Subscription type not found

​Subscription type & brand mismatch

​Contact not found

​Invalid channel

Generate subscription preference page URLs

Troubleshoot errors

Understand error messages

Troubleshoot common errors

Language not configured

Subscription type not found

Subscription type & brand mismatch

Contact not found

Invalid channel