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
  • Opt-Out status
  • How to opt-out
  • Special case: mail.unsubscribe
  • (Re)Opt In
  • Segmenting for Opt-Out-Status
  • But what happens if…
  1. Data & Engagement Platform
  2. Consent Management

System Opt-Out/Opt-In

PreviousSubscription/Consent ManagementNextSystem Blacklist/Whitelist

Last updated 9 months ago

Opt-Out status

  • How to opt-out

  • Special case: mail.unsubscribe

  • (Re)Opt In

Segmenting for Opt-Out-Status

  • Events

  • User-Trait

But what happens if…

  • What happens when the event “Opt In” or “Opt Out” is send directly without a channel-type?

  • What if a custom “opt out” is used?


When a user is ingested first into the CE system, they can technically receive any message, through any channel (given that the technical requirements like having an email address etc. exist). Our system does not require an opt-In, but it does process an opt-out, if sent the proper way.

Opt-Out status

Every user has an opt-out-status, which per default is “false”, an opt-out would be marked as “true”. It usually is channel-specific (e.g. only for email, but not for sms), but can be for “all” as well (not recommended).

It is stored in a system user-trait that you can see in the user profile. Here are some examples how it could look like:

Default (not opted out)

Channel-Specific opt-outs

Per default it is not possible to segment for this user trait, but the system will automatically make sure that no message (depending on the channel) gets send out, unless its a Realtime Campaign that is marked as “transactional”.

How to opt-out

There are two ways to opt out a user:

  1. via sending the system event “Opt Out”

Both ways will have the same technical result:

  • the opt-out status will be set to “true”

  • the system triggers the “Opt Out” event (incl. the timestamp when it happened)

Examples:

{
  "id": "88c5a896-28bb-44e9-850c-2bf60f01a0f9",
  "events": [
    {
      "event": "Opt Out",
			"channel.type":"ALL"
			}
    }
  ]
}
{
  "id": "88c5a896-28bb-44e9-850c-2bf60f01a0f9",
  "events": [
    {
      "event": "Opt Out",
			"channel.type":"MAIL"
			}
    }
  ]
}

Which is better?

Both ways have pros and cons.

  1. API endpoint

For using the API endpoint, the user needs to be a “full” user, because the identifier is the external Id of the user. Therefore this can’t be used for so-called “Leads”, users that only have an email address, but no external Id (e.g. Newsletter subscriber, not full customer). But it is possible to request the status of a user with it (just not for a lead). And it is a short API call (example externalId): url: https://api.crossengage.io/users/88c5a896-28bb-44e9-850c-2bf60f01a0f9/optout-status?channelType=MAIL body:

{
  "optOut": true
}
  1. Event

Sending the event instead has more pros than cons.

  • the event can have more properties and its possible to add more information like that (works like any other event). url: https://api.crossengage.io/events body:

{
  "id": "88c5a896-28bb-44e9-850c-2bf60f01a0f9",
  "events": [
    {
      "event": "Opt Out",
			"channel.type":"MAIL",
			"properties": {
				"status":"opt out via xy"
			}
    }
  ]
}
  • an external Id is not necessary, because an event can be send with an email address (plus business Unit if it exists) instead.

  • it can get technically get used in segmentation or to trigger a RT campaign, just like any other event (although a campaign would not be a good idea in context)

  • the only con is, that forgetting the channel might result in no system opt-out at all ("channel.type" is necessary for that)

Special case: mail.unsubscribe

mail.unsubscribe

This event is part of the response data CE gets from the ESP (Email Service Provider), similar to mail.open and mail.click.

If a user clicks on a regular unsubscribe link (or the unsubscribe-link provided by the list-unsubscribe-header), it will automatically send “mail.unsubscribe” to the CE system.

This event will trigger the change of the opt out-status for the channel “EMAIL” and the change will then trigger the “Opt Out”-event as described above.

(Re)Opt In

The API endpoint is the same, just the content needs to get set to “false” instead of “true”.

The event “Opt In” works pretty much the same way as “Opt Out”, just the name is different. It will set the opt out status automatically to “false”

Segmenting for Opt-Out-Status

Events

All of the events mentioned in this document can be used in segmentation to find out who recently opted out or -in, but only within the contractual retention time. That is why its not the best way to any long-term monitoring or excluding of users. Also its not possible to make sure in what order Opt Out- or Opt In-events happened.

A workaround would be, to exclude users for a specific time, then try a sendout again and in case they are still opted out, the system will not send anything (unless its a transactional message) and create the event "Message Dispatch Failes Because Of Opt-Out", which then can get used to segment again.

User-Trait

Cleaner would be to request the actual status of a user instead, no matter when it was changed. The opt-out-status is technically a user trait saved in the profile, but its a system-trait that without some extra steps does not appear in segmentation as an option.

{
"name": "traits.optOut.mail",
"attributeType": "BOOLEAN"
}

all, mail, sms, exit-intent, push-notification, direct-mail, onsite-display, web-notification

The status only connects after the user was updated again. It can be any user-trait update though, as long as the user profile was updated and therefore new indexed.

But what happens if…

What happens when the event “Opt In” or “Opt Out” is send directly without a channel-type?

Nothing. The event can be used to trigger a RT campaign, or be used it in a segment, but the system itself does nothing. No update to the system trait will happen, because the system doesn’t recognize it as a system event without it.

What if a custom “opt out” is used?

The system functionalities don’t need to be used, especially if there is kind of a preference center like subscription model (e.g. different shops, topics etc.) and its possible to work only with custom user traits instead.

In that case segments need to be very explicitly contain the user traits and should always be included.

via API endpoint (see under “Opt-out management”)

In order to make the status segmentable, a very specific user-traits needs to get created via (under "User Attribute Management":

This attribute connects directly to the system opt-out status for the "MAIL"-channel. The possible options correspond to the channels in the API documentation under and are written as they appear in the user profile:

But it is important to know that system opt-outs can still happen, e.g. caused by the so-called list-unsubscribe-header. There needs to be a workaround to process these cases in place or these users are opted out forever, even after trying to opt in again. Only using the system functionalities will reverse it (see ).

📨
API
Opt-Out-Management
(Re)Opt In
User Management API 1.0