About Marketing Consent
When a visitor signs up for non-transactional content, such as a newsletter, they are consenting to receive marketing messages. This agreement is called a marketing consent. A marketing consent holds the visitor's sign-up details such as email address or phone number, the status of the consent, and more.
The Marketing Consent API allows your app to manage a site's marketing consents. With the Marketing Consent API, your app can:
- Create and update a visitor's marketing consent.
- Get a visitor's marketing consent by ID or communication details.
- Query visitor marketing consents.
- Cancel a visitor's marketing consent.
- Delete a visitor's marketing consent entirely.
Your app can also listen for events when a visitor's marketing consent is created, updated, and deleted.
Terminology
-
Visitor: A visitor is any person who visits a site, including contacts, non-contacts, members, and non-members.
-
Communication channel: Each marketing consent has a communication channel of either
email
orphone
. A visitor can sign up multiple times using different email addresses and phone numbers, however, they can only create a single marketing consent per email and per phone number. -
State: Different states of a marketing consent.
UNKNOWN_STATE
: State of the marketing consent is unknown.NEVER_CONFIRMED
: The visitor never confirmed to receive marketing messages.REVOKED
: The marketing consent has been removed, for example, when a visitor unsubscribes from a newsletter.PENDING
: The marketing consent is pending confirmation. Relevant only for{"optInLevel": "DOUBLE_CONFIRMATION"}
.CONFIRMED
: The site visitor has confirmed their marketing consent.
-
Opt in level: A marketing consent has an
optInLevel
of either single or double confirmation. Some countries require double confirmation for all marketing consents. With single confirmation, when a site visitor signs up, their marketing consentstate
isCONFIRMED
. With double confirmation, when a site visitor signs up, their marketing consentstate
isPENDING
until the visitor confirms their consent, for example, by clicking a link to verify their email address. When the visitor confirms their consent, thestate
isCONFIRMED
. -
Communication eligibility: The Get Marketing Consent By Identfier endpoint returns the
communicationEligibility.granted
boolean which determines whether the recipient of the marketing consent is eligible to receive marketing messages. Note that this only serves as a signal for your app to decide whether or not it should send marketing messages to the recipient's email address or phone number.For example:
- If a visitor cancels their marketing consent, they are no longer eligible to receive communication, and
CommunicationEligibility.granted
isfalse
. This applies to marketing consents made by both phone and email. - If a marketing consent's
state
isNEVER_CONFIRMED
, the visitor has never confirmed to receive communication, andCommunicationEligibility.granted
isfalse
.Note: This applies only to marketing consents made by phone. If a visitor made a marketing consent by email and the
state
isNEVER_CONFIRMED
, the visitor can still receive communication, andCommunicationEligibility.granted
istrue
.
- If a visitor cancels their marketing consent, they are no longer eligible to receive communication, and
Marketing Consent: Sample Use Cases & Flows
This article shares some possible use cases your app could support, as well as an example flow that could support each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your app's implementation.
Confirm a marketing consent with double confirmation
A visitor signs up on your app to receive non-transactional content. If the visitor is from a country where the opt in level is double confirmation, follow this flow to create the marketing consent and update the visitor's marketing consent state.
To confirm the marketing consent:
-
Use Upsert Marketing Consent to create a marketing consent with a double confirmation opt in level.
-
Notice the returned
state
property of the response isPENDING
until the visitor confirms the sign up. -
When the visitor confirms the sign up on your app, use Update Marketing Consent to update a marketing consent's state from
PENDING
toCONFIRMED
.
Marketing Consent: Supported Filters and Sorting
The table below shows field support for filters and sorting for the base set of marketing consent properties.
Field | Supported Filters | Sortable |
---|---|---|
id | $eq , $ne , $in , $exists | |
createdDate | $eq , $ne , $gt , $lt , $gte , $lte | Sortable |
updatedDate | $eq , $ne , $gt , $lt , $gte , $lte | Sortable |
details.email | $eq , $ne , $in , $exists , $startsWith | |
details.phone | $eq , $ne , $in , $exists , $startsWith | |
state | $eq , $ne , $in |
- UNKNOWN_STATE: State of the marketing consent is unknown.
- NEVER_CONFIRMED: The visitor never confirmed to receive marketing consents.
- REVOKED: The marketing consent has been removed, for example, when a visitor unsubscribes from a newsletter.
- PENDING: The marketing consent is pending confirmation. Relevant only for {"optInLevel": "DOUBLE_CONFIRMATION"}.
- CONFIRMED: The site visitor has confirmed their marketing consent.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a marketing consent.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes a marketing consent.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a marketing consent by its details.
Note: Due to the ongoing development of our new documentation portal, the query parameter is not displaying as expected. Use the details
object located in the marketing consent object in the request. You can also see the code example for reference.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a confirmed marketing consent.
Creates a marketing consent with a state
of CONFIRMED
, regardless of what state you set it to. To create a marketing consent with a different state, use Upsert Marketing Consent, or Bulk Upsert Marketing Consent.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a marketing consent's properties.
Only fields provided in mask.paths
are updated. You can update the following fields:
state
lastConfirmationActivity
extendedFields
Each time the marketing consent is updated, revision
increments by 1.
Note: For existing marketing consents with {"type": "EMAIL"}
, you can't update the state
to UNKNOWN_STATE
. Trying to do so maintains the current state. However, you can create a new marketing consent and set the state
to UNKNOWN_STATE
. Note that you can't create more than a single consent per email or phone number.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Removes a marketing consent by its communication details.
Removing a marketing consent cancels the consent, and updates the state
to REVOKED
. The marketing consent still exists, but the recipient of the marketing consent is no longer eligible to receive commmunication. To delete a marketing consent entirely, use Delete Marketing Consent.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of marketing consents, given the provided paging, filtering, and sorting. Up to 100 marketing consents can be returned per request.
The default sort
is id
in ASC
order. For a detailed list of supported operations, see filtering and sorting for marketing consent properties. To learn how to query marketing consents, see API Query Language.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates or updates a marketing consent.
Note that marketingConsent.lastConfirmationActivity
is required unless the state
is REVOKED
or NEVER_CONFIRMED
.
Note: For existing marketing consents with {"type": "EMAIL"}
, you can't update the state
to UNKNOWN_STATE
. Trying to do so maintains the current state. However, you can create a new marketing consent and set the state
to UNKNOWN_STATE
. Note that you can't create more than a single consent per email or phone number.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates or updates multiple marketing consents.
Note that info.lastConfirmationActivity
is required unless the state
is REVOKED
or NEVER_CONFIRMED
.
Note: For existing marketing consents with {"type": "EMAIL"}
, you can't update the state
to UNKNOWN_STATE
. Trying to do so maintains the current state. However, you can create a new marketing consent and set the state
to UNKNOWN_STATE
. Note that you can't create more than a single consent per email or phone number.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a marketing consent is created.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a marketing consent is updated.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a marketing consent is deleted.