> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: f58896b8-7730-46c0-9c00-7cab69cd6b02
---
# Subscriptions preferences v3
> Use the subscriptions preferences API to manage email subscription details for your contacts.
export const RequiredIndicator = () => {
return
required
;
};
export const PostmanCard = ({title, collectionId}) => {
return
} />
;
};
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
Subscription types represent the legal basis to communicate with your contacts through email. Contacts can [manage their email preferences](https://knowledge.hubspot.com/marketing-email/insert-subscription-links-into-marketing-emails) 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](https://knowledge.hubspot.com/inbox/collect-consent-for-whatsapp-conversations) 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.
```json theme={null}
{
"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.
```json theme={null}
{
"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](/api-reference/legacy/communication-preferences/guide).
Only use the subscribe endpoint to honor requests from contacts who have given you explicit permission. Please [review applicable laws and regulations](https://knowledge.hubspot.com/marketing-email/set-up-email-subscription-types) before subscribing a contact.
```json theme={null}
{
"emailAddress": "jdoe@example.com",
"subscriptionId": "8458482",
"legalBasis": "CONSENT_WITH_NOTICE",
"legalBasisExplanation": "Contact provided explicit consent via sign-up form."
}
```
| Parameter | Type | Description |
| -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `emailAddress` | `string` | The email address of the contact to subscribe. |
| `subscriptionId` | `string` | The ID of the subscription type. Retrieve available IDs by making a `GET` request to `/communication-preferences/v3/definitions`. |
| `legalBasis` | `string` | The 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`. |
| `legalBasisExplanation` | `string` | A plain-text explanation for the legal basis provided. |
The response will include the resulting subscription status.
```json theme={null}
{
"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`.
```json theme={null}
{
"emailAddress": "jdoe@example.com",
"subscriptionId": "8458482"
}
```
| Parameter | Type | Description |
| -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `emailAddress` | `string` | The email address of the contact to unsubscribe. |
| `subscriptionId` | `string` | The ID of the subscription type. Retrieve available IDs by making a `GET` request to `/communication-preferences/v3/definitions`. |
| `legalBasis` | `string` | The 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`. |
| `legalBasisExplanation` | `string` | A plain-text explanation for the legal basis provided. |
The response will include the resulting subscription status.
```json theme={null}
{
"id": "8458482",
"name": "Marketing Information",
"description": "Receive updates and promotional content.",
"status": "NOT_SUBSCRIBED",
"sourceOfStatus": "SUBSCRIPTION_STATUS"
}
```