Skip to main content
Subscription types represent the legal basis to communicate with your contacts through email. Contacts can manage their email preferences so that they’re only opted into the emails they want to receive.
Please note: the subscription preferences API does not currently support retrieving or updating WhatsApp subscription information for a contact.

​
Get subscription types

If you’re building an external preferences center, integration, or form that displays subscription options, use this endpoint to retrieve all subscription types in your account. Make a GET request to /communication-preferences/v3/definitions. The response will include an array of subscription definitions in the subscriptionDefinitions field. You’ll need the id value from each definition when subscribing or unsubscribing a contact. 
{
  "subscriptionDefinitions": [
    {
      "id": "8458482",
      "name": "Marketing Information",
      "description": "Receive updates and promotional content.",
      "isActive": true,
      "isDefault": true,
      "isInternal": false,
      "communicationMethod": "Email",
      "purpose": "Marketing",
      "createdAt": "2022-02-09T21:06:59.247Z",
      "updatedAt": "2022-02-09T21:06:59.247Z"
    }
  ]
}

​
Get contact subscription status

To look up the current subscription statuses for a specific email address, make a GET request to /communication-preferences/v3/status/email/{emailAddress}, where {emailAddress} is the contact’s email address. This is useful for populating an external preferences center or keeping an integration in sync with a contact’s current opt-in state. The response will include the recipient email address and a subscriptionStatuses array containing the contact’s status for each subscription type. 
{
  "recipient": "jdoe@example.com",
  "subscriptionStatuses": [
    {
      "id": "8458482",
      "name": "Marketing Information",
      "description": "Receive updates and promotional content.",
      "status": "SUBSCRIBED",
      "sourceOfStatus": "SUBSCRIPTION_STATUS",
      "legalBasis": "CONSENT_WITH_NOTICE",
      "legalBasisExplanation": "Contact provided consent via sign-up form."
    },
    {
      "id": "8458483",
      "name": "Product Updates",
      "description": "News about new features and releases.",
      "status": "NOT_SUBSCRIBED",
      "sourceOfStatus": "SUBSCRIPTION_STATUS"
    }
  ]
}
The status field in each object indicates whether the contact is currently opted in (SUBSCRIBED) or opted out (NOT_SUBSCRIBED) for that subscription type. The sourceOfStatus field indicates what determined the status: SUBSCRIPTION_STATUS (individual subscription preference), PORTAL_WIDE_STATUS (contact opted out of all email), or BRAND_WIDE_STATUS (contact opted out of all email from a specific brand).

​
Subscribe a contact

Use this endpoint to opt a contact into a subscription type from an external integration or form. Make a POST request to /communication-preferences/v3/subscribe.
Please note: this endpoint will not allow you to resubscribe contacts who have previously opted out. For that functionality, you should instead use the v4 subscription API.
Only use the subscribe endpoint to honor requests from contacts who have given you explicit permission. Please review applicable laws and regulations before subscribing a contact. 
{
  "emailAddress": "jdoe@example.com",
  "subscriptionId": "8458482",
  "legalBasis": "CONSENT_WITH_NOTICE",
  "legalBasisExplanation": "Contact provided explicit consent via sign-up form."
}
ParameterTypeDescription
emailAddress stringThe email address of the contact to subscribe.
subscriptionId stringThe ID of the subscription type. Retrieve available IDs by making a GET request to /communication-preferences/v3/definitions.
legalBasisstringThe legal basis for subscribing the contact. Accepted values: CONSENT_WITH_NOTICE, LEGITIMATE_INTEREST_CLIENT, LEGITIMATE_INTEREST_OTHER, LEGITIMATE_INTEREST_PQL, NON_GDPR, PERFORMANCE_OF_CONTRACT, PROCESS_AND_STORE.
legalBasisExplanationstringA plain-text explanation for the legal basis provided.
The response will include the resulting subscription status. 
{
  "id": "8458482",
  "name": "Marketing Information",
  "description": "Receive updates and promotional content.",
  "status": "SUBSCRIBED",
  "sourceOfStatus": "SUBSCRIPTION_STATUS",
  "legalBasis": "CONSENT_WITH_NOTICE",
  "legalBasisExplanation": "Contact provided explicit consent via sign-up form."
}

​
Unsubscribe a contact

Use this endpoint to opt a contact out of a subscription type from an external integration or form. Make a POST request to /communication-preferences/v3/unsubscribe. 
{
  "emailAddress": "jdoe@example.com",
  "subscriptionId": "8458482"
}
ParameterTypeDescription
emailAddress stringThe email address of the contact to unsubscribe.
subscriptionId stringThe ID of the subscription type. Retrieve available IDs by making a GET request to /communication-preferences/v3/definitions.
legalBasisstringThe legal basis for unsubscribing the contact. Accepted values: CONSENT_WITH_NOTICE, LEGITIMATE_INTEREST_CLIENT, LEGITIMATE_INTEREST_OTHER, LEGITIMATE_INTEREST_PQL, NON_GDPR, PERFORMANCE_OF_CONTRACT, PROCESS_AND_STORE.
legalBasisExplanationstringA plain-text explanation for the legal basis provided.
The response will include the resulting subscription status. 
{
  "id": "8458482",
  "name": "Marketing Information",
  "description": "Receive updates and promotional content.",
  "status": "NOT_SUBSCRIBED",
  "sourceOfStatus": "SUBSCRIPTION_STATUS"
}
Last modified on June 9, 2026