Documentation
APICreate a Ticket
  • 📔Documentation Guide
  • 📨Data & Engagement Platform
    • Data Model
      • Customer Data
      • Product Catalogue
      • Events
        • Onsite Events
        • Outbound Events
        • Transactions
    • App User Management
      • User Roles
      • App Users
    • Data Management
      • Data Management with API
      • Data Management with Data Feeds
        • Users
          • Import Users
          • Update or Delete a User Trait via File Upload
          • List of Standard User Traits/Attributes
        • Products
        • Events
          • Import Orders
          • Import Events
          • List of Events and Properties
      • Data Export
    • Web Tracking
      • Web Tracking v1 (Legacy)
        • Setup
        • Set up business Units
        • Tracking User Behavior
          • Identify Method
          • Page Method
          • Track Method
          • Opt-Out from Tracking
        • Testing & Debugging
      • Web Tracking v2
        • Setup using Google Tag Manager
        • Setup without a Tag Manager
        • Configuration & Config Commands
        • Tracking User Behavior
          • Identify Method
          • Update Method
          • Page Method
          • Track Method
          • Opt-Out from Tracking
        • Testing & Debugging
      • Migrate Tracking SDK v1 -> v2
      • Mobile Web Tracking
    • User Segmentation
      • Creating a Segment
      • Conditions
      • Combining Segments
    • Messages
      • Frequency Capping
      • Templates
        • Template Builder
      • Integrations
        • Channels
          • SMS
            • Twilio
              • Set up a Twilio Account
              • Set up Twilio Integration
              • Create a Campaign Message
            • Link Mobility
              • Set Up Link Mobility Account
              • Set up Link Mobility Integration
              • Create a Campaign Message
          • SFTP
            • Set up SFTP Integration
            • Create a Campaign Message
          • Direct Mail
            • Optilyz
              • Set up Optilyz Integration
              • Create a Campaign Message
          • Webhooks
            • Single Webhook
              • Set up Webhook Integration
              • Create a Campaign Message
              • Response Data and Custom Events
            • Batch Webhook
              • Set up Batch Webhook Integration
              • Create a Campaign Message
            • Zenloop via CrossEngage Webhook
              • Set up Zenloop Integration (via CrossEngage Webhook)
              • Set up Zenloop Survey
              • Create a Campaign Message
              • Set up Zenloop Survey via ESP
              • Obtain Response Data
            • Google Analytics via Webhook
          • Segment Transfer
            • Facebook
              • Set up Facebook Developer Account
            • Optimizely
              • Set up Optimizely Account
            • Google Analytics
              • Set up Google Analytics Integration
              • Create a Campaign with Google Analytics
              • Using the Google Analytics Integration
            • Airship
              • Set up an Airship Account
              • Set up an Airship Integration
              • Create a Campaign Message with Airship
          • Onsite Display
            • Trbo
              • Set up Trbo Integration
              • Create a Campaign Message in CrossEngage
              • Configure Campaign Message in Trbo
              • Obtain Response Data
          • Email
            • Mailjet
              • Set up Mailjet Integration
              • Obtain Response Data via Webhook
              • Create a Campaign Message
              • Personalize Preview Texts in Mailjet
            • Mandrill (by MailChimp)
              • Set up Mandrill Integration
              • Obtain Response Data via Webhook
              • Create a Campaign Messege
            • Inxmail
              • Set up Inxmail Integration
              • Create a Campaign Message
            • Sendgrid (by Twilio)
              • Set up SendGrid Integration
              • Obtain Response Data via Webhook
              • Create a Campaign Message
            • Mailgun
              • Set up Mailgun Integration
              • Obtain Response Data via Webhooks
              • Create a Campaign Message with Mailgun
            • Episerver (Optimizely)
              • Set up Episerver Integration
              • Create a Campaign Message with Episerver
          • Push Notifications
            • Airship
              • Set up an Airship Account
              • Set up an Airship Integration
              • Create a Campaign Message with Airship
        • Attachments
        • Delete an Integration
      • Personalization
        • Import Data
          • User Profile Data
          • Campaign Data
          • Cart Data
        • Formatting Functions
          • Date Formatting
          • Number Formatting
          • String Formatting
          • Hash Functions
        • General Helper Functions
          • Conditional Functions
          • Filtering Arrays
        • Product Helper Functions
          • Fetch from Product Feed
          • Fetch from Tracking Event
          • Fetch from User Journey
        • Misc. Helper Functions
          • Voucher Helper Function
            • Vouchers: Use Case
          • Event Helper Functions
          • Opt Out Helper Functions
        • Operators
      • Vouchers
        • Creating Vouchers
        • Using Vouchers
    • Campaign Management
      • Campaigns
        • Create an Audience Campaign
        • Create a Real-Time Campaign
        • Control Group
      • Stories
        • Building a Story
        • Use Case: Welcome Story
      • Segment Transfer
        • Create a Segment Transfer Campaign
    • Consent Management
      • Subscription/Consent Management
      • System Opt-Out/Opt-In
      • System Blacklist/Whitelist
    • Prediction Models
      • Create a new Model
      • Feature Engineering
      • SQL Filter
    • System Monitoring
      • Dashboard
        • Segment Tracker
      • Events Overview
      • Activity Log
      • Slack Notifications
        • Setting up Slack Notifications
    • Help & Support
      • System Status
      • Reach out to Customer Support
      • Suggest an Improvement
      • Privacy Policy
    • Glossary - Data & Engagement
  • 📈Predictions Platform
    • Data Model
      • Customer Data
      • Transactions
      • Activities
    • Overview
      • Data Tab
        • Data Tables in the Predictions Platform
      • Insights Tab
      • Model Builder Tab
        • Feature Engineering
        • Custom SQL Filter
        • Model Report
      • Prediction Tab
      • Selections Tab
    • Tutorials
      • Prepare and Validate Data
      • Analyze RFM Customers
      • Create a new Model
      • Predict Campaign Profit
    • Glossary - Predictions
Powered by GitBook
On this page
  • Evaluation
  • Recommendation for single subscriptions
  • Recommendation for multi-subscriptions
  • Known issues
  1. Data & Engagement Platform
  2. Consent Management

Subscription/Consent Management

Evaluation

  • System functionalities

  • Custom functionalities

  • User Ids

Recommendation for single subscriptions

  • Subscription

  • Unsubscription

Recommendation for multi-subscriptions

  • Subscription

  • Unsubscription

Known issues

  • Segments have more users in it than newsletters are send

  • #segments-have-more-users-in-it-than-newsletters-are-send-1

  • External Id is not known/doesn’t exist


The Crossengage system is very flexible and there is not only one correct way to manage subscriptions and unsubscriptions etc.. We can give pointers and maybe some recommendations, but in the end it depends on the scenario and environment it connects to.

Note: The information in this section is not legal advice. Each customer shall set up their subscription concept under their legal and technical considerations.

For the purpose of this documentation we will mostly cover scenarios that store necessary information in Crossengage and give context to the options.

Evaluation

In the beginning it is important to evaluate if there is more than one topic that a user can subscribe to or unsubscribe from, even if it is just a vague plan for the future. This will determin if the approach is mostly system functionalities only, or mostly custom functionality.

This step should not be taken lightly, because it can get tricky to introduce custom options later down the line.

System functionalities

Crossengage is an “opt out”-system, so technically it is not necessary to process Opt-Ins within it, but unless its only used for transactional communication, it is recommend to do so somewhere (usually also required by law and therefore also by the ESP).

The only actual system functionality that is connected here, is the opt-out status of a user. The default is “false”, which means that this user is not opted out and they can receive messages. If the status is set to “true” and the user is therefore opted out, the system will block any sendouts automatically, unless its marked as transactional in case of Realtime Campaigns.

Custom functionalities

On top of the system functionalities which will always apply, it is also possible to include custom functionalities. This could be the use of custom events and/or user traits, which can give more options to segment users (e.g. preferences), trigger campaigns, give information about the progress in a subscription workflow or similar.

User Ids

It is also important to know when exactly you will have which information about a user. User management in Crossengage can be done via “External Id” (e.g. a customer number), or (partly) via a combination of “Email” and “Business Unit” (short “BU”). But:

  • the external Id can only exist once in the system

  • the combination of “Email” and “BU” can also only exist once

  • if no “BU” is used, it will be an invisible “default” in the background

  • users with an external Id are managed with the API endpoint “users”

  • users without an external Id are managed with the API endpoint “leads”, once an update with the same combination of “Email” and “BU” is made with an “external Id” as well, this users management will get moved to the “users” endpoint and the “leads” endpoint can’t be used anymore

  • events can be send with the external Id as “id”, or with “email” and “businessUnit” (even for full users)

Recommendation for single subscriptions

In this scenario there is only one topic to subscribe to and from, so its basically an on/off switch. But there are still several steps to take and several API calls to make, in order for it to work.

Subscription

Step 1: Preparation

If not already existing, the following need to get created (names of traits are examples):

  • user trait “doi” with the datatype “STRING”

  • event “Subscribe Newsletter” with a property that include the “doiLink”

  • Website: Landingpage which will serve as the property “doiLink”. Here its important to establish how a user is recognized. It might be necessary to use something like a hashed email-address.

  • RT campaign “DOI” which will send the user a DOI-mailing with the “doiLink”

  • event “Confirmed Subscription”

  • Website: Landingpage to confirm the subscription was successful

Step 2: Subscription Form

When a user sends his subscription information, several API calls need to get send:

  • {"id": "USERID", "events": [ { "event": "Subscribe Newsletter", "properties": { "doiLink": "https://subdomain.domain.tld?id=USERID"}}]}

Step 3: DOI Mailing

The event “Subscribe Newsletter” triggers the RT campaign “DOI”, which sends a doi mailing to the users to confirm the subscription.

This mailing needs to be marked as “transactional”, just in case the user was already opted out for some reason and must contain the property “doiLink” with the help of a handlebar. In this example case it would be:

{{{journey.steps.[0].[properties.doiLink]}}}

Usually handlebars have two curly brackets surrounding them, but in case of a URL its safer to user three, because it will enforce that the content is used as is and not accidentally url-encoded, which could cause problems at the destination.

If external templates from the ESP are used, this handlebar needs to get inserted into the value mapping to transfer this information to the ESP for rendering it into the template.

Step 4: Confirmation Landingpage

Once the user clicks on the “doiLink”-URL to confirm the subscription they get redirected to the confirmation page and again several API calls need to get send:

  • {"id": "USERID", "email":"user.name@gmail.com", "businessUnit":"de", "doi": "confirmed"}

  • {"id": "USERID", "events": [{"event": "Confirmed Subscription"}, {"event": "Opt In", "channel.type":"MAIL"}]}

Unsubscription

For unsubscribing the previous steps need to get kind of reversed, but with less steps. Usually an unsubscription is done via an unsubscribe link in a mailing, which also usually should be one-click (meaning: with clicking the unsubscription should be already done and no other steps from the user are necessary).

There are two ways to do that:

  1. use the standard unsubscribe link of the ESP. This will automatically process the unsubscription through this provider, which then sends the event “mail.unsubscribe” to Crossengage, which will automatically trigger the change of the opt-out-status to “true”. No further message can get send to the user (unless its transactional) from this point on.

  2. using a custom unsubscribe link that leads to another landingpage, which then sends:

    • {"id": "USERID", "email":"user.name@gmail.com", "businessUnit":"de", "doi": "unsubscribed"}

    • {"id": "USERID", "events": [{"event": "Opt Out", "channel.type":"MAIL"}]}

  • the first option will not update any custom trait, so the users will remain in any “subscribed” segment, even though they are opted out. No message will get send, but the numbers will be wrong.

  • even if the second option is used, it is still possible that there are unsubscriptions without the update of user traits, if some automatic process like the so-called list-unsubscribe-header is involved

  • more traits or events can be included as well, but these are the basics

Recommendation for multi-subscriptions

Most of the steps from the single subscriptions are the same here. But if a user can subscribe to and unsubscribe from multiple different newsletters or topics, the system functionalities for unsubscriptions need to get replaced by fully custom options and instead of one user trait “doi”, there needs to be at least one specific trait per option, maybe even two, if you want to add a date for the (un)subscription as well.

Subscription

Example where the user can choose multiple categories, e.g. “kids”, “pets” and “shoes”.

  • {"id": "USERID", "email":"user.name@gmail.com", "businessUnit":"de", "newsletterKids": "pending", "newsletterPets": "pending", "newsletterShoes": "pending"}

The "doiLink"-property in the event “Subscribe Newsletter” should then also contain parameters that include the chosen categories:

  • {"id": "USERID", "events": [{"event": "Subscribe Newsletter", "properties": {"doiLink": "https://subdomain.domain.tld?id=USERID&kids=1&pets=1&shoes=1"}}]}

The rest of the steps are the same, just that after confirming not one, but all specified user traits get updated with “subscribed”.

Unsubscription

Since using the system opt-out (via events “Opt Out” or the providers “mail.unsubscribe”) would result in a total opt-out from the whole channel, only the custom unsubscribe version without the events can be used here.

To stay with the above example, the API call would set the wanted category to “unsubscribed”

  • {"id": "USERID", "email":"user.name@gmail.com", "businessUnit":"de", "newsletterKids": "unsubscribed", "newsletterShoes": "unsubscribed"}

    In this example, the subscription for “newsletterPets” would still remain subscribed, the others are unsubscribed.

In this scenario there is no system functionality that takes care of the opt out status of the user! There should always be a check for the necessary traits in the segments that are used for campaigns and stories, otherwise opted out users could still receive messages!

Known issues

There are system-opt-outs, although only custom traits are used

The reason is most likely, that some users did not use the regular custom unsubscribe link in a mailing, but the unsubscribe option that got automatically rendered from the so-called list-unsubscribe-header by the email client. Especially freemail providers like Gmail will sometimes show an unsubscribe link in the inbox overview, which contains the system opt-out of the ESP, which will then trigger a system opt-out in Crossengage. Some email providers also will render a regular opt-out-link into templates, if there was none detected.

Solution:

  • this list can then be used to custom opt-out the users in it. Usually all possible user traits should get the “unsubscribed” content, unless it is know exactly which option the user wanted to unsubscribe from.

  • after that the users should get send the event “Opt In”, to reverse the system opt-out- status:

    {"id": "USERID", "events": [{"event": "Opt In", "channel.type":"MAIL", "properties": {"status":"opt out via traits"}}]}

Segments have more users in it than newsletters are send

The reason is most likely system-opt-outs because of the reasons above.

External Id is not known/doesn’t exist

The external Id is usually used as “id” to create/update users or sent events. If it does not exist or is unknown, its possible to use “Email” in combination with “Business Unit” instead.

  • {"email": "user.name@gmail.com", "businessUnit": "de" "events": [{"event": "Confirmed Subscription" }, { "event": "Opt In", "channel.type":"MAIL" }]}

  • for user trait updates its a bit more complicated, because there are two API endpoints, “leads” and “users”. If the external Id does not exists, the endpoint “leads” must be used instead of “users”. If the external Id might exist, but is not known at this point, you can only try to use “leads”, but in case the person already exists as a full user, the API will respond with "EXTERNAL_IDS_MISMATCH".

PreviousConsent ManagementNextSystem Opt-Out/Opt-In

Last updated 8 months ago

See for specifics how to send API calls in both cases.

API call to create/update user with the user trait “doi” to set the status: PUT {"id": "USERID", "email":"user.name@gmail.com", "businessUnit":"de", "doi": "pending"}

event “Subscribe Newsletter”: POST

See for more information about handlebars, if needed.

API call to create/update user with the user trait “doi” to set the status: PUT

events “Confirmed Subscription” and “Opt In” POST

The event “Opt In” is necessary to reverse the opt-out-status of a possible earlier unsubscription to “false”. But more about “Opt In” and “Opt Out” in the about it. ”Confirmation Subscription” could trigger a welcome mailing or a welcome story and doesn’t necessarily need properties, but can always get enhanced with some, if needed.

API call to update user with the user trait “doi” to set the status: PUT

event “Opt Out” POST

Similar to the single subscription with the trait “doi” the subscription form could trigger: PUT

POST

API call to update user with the wanted category user trait to “unsubscribed” PUT

create a workflow that regularely requests the users of recent system opt-outs (e.g. via SFTP export campaign or Export API), if there is a .

for events its fairly easy, just use “email” and “businessUnit” instead of “id”. Example: events “Confirmed Subscription” and “Opt In” POST

📨
https://api.crossengage.io/users/{id}
https://api.crossengage.io/events
Event Helper Functions | Documentation
https://api.crossengage.io/users/{id}
https://api.crossengage.io/events
separate documentation
https://api.crossengage.io/users/{id}
https://api.crossengage.io/events
https://api.crossengage.io/users/{id}
https://api.crossengage.io/events
https://api.crossengage.io/users/{id}
segment to request
https://api.crossengage.io/events
User Management API 1.0