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 or phone. 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 consent state is CONFIRMED. With double confirmation, when a site visitor signs up, their marketing consent state is PENDING until the visitor confirms their consent, for example, by clicking a link to verify their email address. When the visitor confirms their consent, the state is CONFIRMED.

• 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, andCommunicationEligibility.granted is false. This applies to marketing consents made by both phone and email.
  • If a marketing consent's state is NEVER_CONFIRMED, the visitor has never confirmed to receive communication, and CommunicationEligibility.granted is false.

    Note: This applies only to marketing consents made by phone. If a visitor made a marketing consent by email and the state is NEVER_CONFIRMED, the visitor can still receive communication, and CommunicationEligibility.granted is true.

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:

1. Use Upsert Marketing Consent to create a marketing consent with a double confirmation opt in level.

2. Notice the returned state property of the response is PENDING until the visitor confirms the sign up.

3. When the visitor confirms the sign up on your app, use Update Marketing Consent to update a marketing consent's state from PENDING to CONFIRMED.

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