# System Blacklist/Whitelist

[#blacklist-status](#blacklist-status "mention")

[#how-to-blacklist](#how-to-blacklist "mention")

[#how-to-whitelist](#how-to-whitelist "mention")

[#which-is-better](#which-is-better "mention")

***

{% hint style="info" %}
When a user should not get any communication anymore, not even transactional, its possible to blacklist someone. The system will enforce this status.
{% endhint %}

The blacklist status will only be held for users that exist in the database. If the user gets deleted, their blacklist-status will be gone as well. This is important, if at any later time the user gets added again, Crossengage has no record of the blacklisting anymore.

### Blacklist status <a href="#blacklist-status" id="blacklist-status"></a>

Every user has an Blacklist-status, which per default is “false”. It is stored in a system user-trait that is not visible in the user profile. You could only assume that a blacklist is there, if there was a failed message, which will show up like this:

<div align="left"><figure><img src="https://985110910-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Hio8LJewN8lQY2Vlqy0%2Fuploads%2FnVovgY9oFxAsMACvf8Z2%2Fdispatch_failed.png?alt=media&#x26;token=329c10cd-01ce-4e03-9a0e-247a5cef3d7f" alt=""><figcaption></figcaption></figure></div>

### How to Blacklist <a href="#how-to-blacklist" id="how-to-blacklist"></a>

There are two ways to opt out a user:

* via API endpoint (see [![](https://api.documentation.crossengage.io/wp-content/uploads/cropped-android-chrome-512x512-1-32x32.png)User Management API 1.0](https://api.documentation.crossengage.io/) under “Opt-out management” → “Blacklist Endpoint“)\
  PUT <https://api.crossengage.io/users/id/blacklist-status>

  `{ "blacklisted": true }`
* via sending the system event “Blacklisted”\
  Event “Blacklisted”\
  POST <https://api.crossengage.io/events>

  `{ "id": "USERID", "events": [ { "event": "Blacklisted" } ] }`

Both ways will have the same technical result:

* the Blacklist status will be set to “true”
* the system triggers the “Blacklisted” event (which includes the timestamp when it happened)

<div align="left"><figure><img src="https://985110910-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Hio8LJewN8lQY2Vlqy0%2Fuploads%2FMJP6N2US1lCJLxK3jS9J%2Fblacklisted.png?alt=media&#x26;token=40ed5fc6-41bd-4ea5-b798-ba42c842d693" alt=""><figcaption></figcaption></figure></div>

### How to Whitelist <a href="#how-to-whitelist" id="how-to-whitelist"></a>

To remove a blacklisting, you do the same steps as for blacklisting, just set the status to “false” or use the “Whitelist”-event instead:

* API endpoint\
  PUT <https://api.crossengage.io/users/id/blacklist-status>

  `{ "blacklisted": false }`
* Event “Whitelisted”\
  POST <https://api.crossengage.io/events>

  `{ "id": "USERID", "events": [ { "event": "Whitelisted" } ] }`

<div align="left"><figure><img src="https://985110910-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Hio8LJewN8lQY2Vlqy0%2Fuploads%2FOUlNb2YfpzuOEJk15VaE%2Fwhitelisted.png?alt=media&#x26;token=23fc6a73-7789-4de9-b242-3216fa9b8c3b" alt=""><figcaption></figcaption></figure></div>

### **Which is better?** <a href="#which-is-better" id="which-is-better"></a>

Both ways have pros and cons.

* 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).
* 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).
  * 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, just like any other event