Add SHA-256 Hashed Entries to a Blacklist

Goal

Add email addresses to a System Blacklist or Group Blacklist as SHA-256 hash values instead of clear text. This way, you never upload or send the email addresses themselves. Use this option if your security requirements do not allow clear-text or MD5 entries.

A hash value is a 64-character code calculated from an email address. It cannot be converted back into the address. Before you calculate it, you add a salt: a secret value that is unique to your Mapp Engage account. Mapp Engage knows your salt and calculates the same hash values for the email addresses of your contacts. This is how it recognizes blacklisted contacts.

Mapp Engage removes matching contacts and blocks the email address from future imports, registrations, and updates. For details, see Blacklist Management.

Note
SHA-256 entries support email addresses only. You cannot add domains or mobile numbers as SHA-256 entries. The same applies to MD5.

Prerequisites

System Blacklist: your system role must have permission 203 (Contact Management: Edit system blacklist).
Group Blacklist: your group-specific role or group-override system role must have permission 505 (Members: Edit group blacklist).

Procedure

1. Get Your Salt

Request the salt for your account from your Customer Success Manager (CSM). The CSM sends it to you through a secure channel.

The salt is a 64-character string of digits and letters.
Each Mapp Engage account has its own salt. If you use several accounts, for example for testing and production, each one has a different salt. Always use the salt of the account you add the entries to.
The salt is permanent. Hash values you create remain valid.

Warning
Keep the salt confidential. Do not include it in support tickets, emails, or log files.

2. Create the Hash Values

For each email address:

Remove any spaces before and after the email address and convert it to lowercase. For example, Alice@Example.com becomes alice@example.com.
Put the salt directly in front of the email address, without a space or separator. Use the salt as plain text, exactly as you received it.
Calculate the SHA-256 hash of this combined text, encoded as UTF-8.
Use the result as a 64-character hexadecimal string (digits 0-9 and letters a-f).

Most programming languages and tools do steps 3 and 4 in a single function. UTF-8 matters for email addresses with special characters, such as ü.

Short form for developers:

hex(SHA-256(UTF-8(salt + lowercase_email)))

Note
Use standard SHA-256. SHA3-256 and other algorithms create different hash values that do not match.

Example

This example uses a sample salt. For real entries, always use your own salt.

Field	Example value
Salt	`37024be05cdd4a9d87b152b1146d09c1084e123f0aab4325b59ac14f6ca72952`
Email address	`Alice@Example.com`
After step 1	`alice@example.com`
After step 2	`37024be05cdd4a9d87b152b1146d09c1084e123f0aab4325b59ac14f6ca72952alice@example.com`
Hash value	`539b637d7a8f6ab59b937dc973c2b991001c2349414452189bda240f2170c02a`

To check your implementation, run it with the sample values. It must return the hash value from the table. Example in Python:

import hashlib

salt = "37024be05cdd4a9d87b152b1146d09c1084e123f0aab4325b59ac14f6ca72952"
email = "Alice@Example.com"

digest = hashlib.sha256((salt + email.strip().lower()).encode("utf-8")).hexdigest()
print(digest)  # 539b637d7a8f6ab59b937dc973c2b991001c2349414452189bda240f2170c02a

3. Add the Hash Values to the Blacklist

You can add SHA-256 entries in the same ways as clear-text entries. In each case, select SHA-256. Mapp Engage then checks your contacts against the new entries. In the System Blacklist overview, new entries show the status Not Verified until this check is complete, then Verified.

File Import

Go to Audience > Blacklists > System Blacklist. For a group blacklist, go to Audience > Blacklists > Group Blacklist and select the group.
Click Import.
Set List Type to SHA-256 and configure the other import settings.
Click Import.

In a text file, separate the hash values with commas:

539b637d7a8f6ab59b937dc973c2b991001c2349414452189bda240f2170c02a,1aede1a34f32aca5ed47a4be7869c1f1bcd14839864a0732cae45dc6e8c56e27

In an XML file, put each hash value in an <email> tag. For all import settings, see Add Entries to Group Blacklist.

Manual Entry

Go to Audience > Blacklists > System Blacklist. For a group blacklist, go to Audience > Blacklists > Group Blacklist and select the group.
Click Create.
Set List Type to SHA-256.
In the Email field, enter one hash value per line.
Click Save.

REST API

Use the hashed endpoints with the query parameter hashed=sha256:

System blacklist: POST /blacklist/createSystemEntriesHashed?hashed=sha256
Group blacklist: POST /blacklist/createGroupEntriesHashed?hashed=sha256&groupId=<groupId>

Set type to EMAIL and pattern to the 64-character hash value:

[
  {
    "type": "EMAIL",
    "pattern": "539b637d7a8f6ab59b937dc973c2b991001c2349414452189bda240f2170c02a"
  }
]

If a value is not a 64-character hexadecimal string, or if the entry type is not EMAIL, the API returns HTTP 400 with the error code INVALID_PARAMETER. For all parameters, see Create hashed system blacklist entries and Create hashed group blacklist entries.

Event-Based Automation

In the jobs Add to System Blacklist (C) and Add to Group Blacklist (C), set hashing_algorithm to SHA-256. Mapp Engage then creates the hash value from the contact's email address with your account salt. You do not need to provide a salt or hash value.

The Add to Blacklist job in whiteboards does not offer this option.

Remove SHA-256 Entries

Mapp Engage cannot convert hash values back into email addresses. To remove the entry for a specific email address, first create its hash value as described in step 2. Then use one of the following options:

Select the entry on the System Blacklist or Group Blacklist page and click Delete.
Import a file with the list type SHA-256 and the import mode Delete.
Send the hash value with type set to EMAIL to POST /blacklist/deleteSystemEntries or POST /blacklist/deleteGroupEntries?groupId=<groupId>.

Removing an entry only lifts the block. It does not restore deleted contact data or group memberships.

Troubleshooting

If a contact whose email address you blacklisted is still in your system or group, check how you created the hash value:

Salt: You used the salt of the account you added the entry to.
Order: The salt comes before the email address, not after it.
Separators and spaces: There is nothing between the salt and the email address, and no spaces around the email address.
Lowercase: You converted the email address to lowercase before hashing.
Salt as text: You used the salt as plain text and did not convert it into bytes first.
Algorithm: You used SHA-256, not SHA3-256 or MD5.

To test your implementation, use the sample values from the example. Upper- or lowercase letters in the hash value itself are not a problem, because Mapp Engage converts hash values to lowercase.