Customer Key

The platform uses the contact email address and first name to uniquely identify a contact.  The Customer Key feature allows you to use an alternate string. 

The Customer Key makes it easy to associate subscribe data from your CRM / in-house systems to contacts in the platform. The term "customer key" is a generic term and can be used to store the customer's account id, member id, user id or other unique identifier.  An alternate way to do this is through Relational Data tables.

The feature is enabled at the realm level when a new realm is created on a new database.  The feature adds a column named customer_key to the contacts table.  In a normal realm, the unique index is the composite realm_id, email and first_name columns.  In a realm with Customer Key enabled, the unique index in the contacts table is a composite of realm_id and customer_key. Because of the difference in the database and the index, the Customer Key feature cannot be enabled on an existing realm, and can only be enabled when creating a new realm on a new database.  In addition, the parent realm and the child realm must have matching indexes, so all child realms of a Customer Key realm must also be enabled for Customer Key, and all child realms of a non-Customer Key realm will not support Customer Key.

This feature is not recommended for existing users.  If an existing user wishes to use this feature, the only option is to create a new realm with the feature enabled. Once created, the user must export all contacts from the original realm and then import into the new realm.  There are no tools to migrate lists, templates, segmentation rules and other items.  None of the associated contact tracking information, reporting, or campaigns can be moved to the new realm, so contact history is lost.

Enabling Customer Key

To enable Customer Key:

1. Go to CUSTOMER CENTER > REALM MANAGMENT > CREATE REALM.  

2. Enter a Realm Name and Description.  

3. Select the option "Create a new database for this Realm", and then select a Database Server.

4. Select the Customer Key option that appears below the Database setting.

5. Enter your Name or Email address in the Customer Key Approval field.

6. Make your other selections and settings, then click CREATE.

To check if a realm has Customer Key enabled:

1. Go to CUSTOMER CENTER > REALM MANAGMENT > EDIT REALM. 

2. Select the Realm from the listbox. 

3. Check below the Parent Code for the notification "This realm uses Customer Key".

Areas Affected in User Interface

The following areas are affected by the use of Customer Key.  Several are unobtrusive changes, such as the option to include the Customer Key in a report, while Customer Key is required for other features to work properly.  Some features are no longer available if Customer Key is enabled.

The following reports include the Customer Key as a column in the result report file:

• Standard Report Library Active Contacts

• Standard Report Library Passive Contact

• Standard Report Library Inactive Contacts

• Standard Report Library Opt Out Report

The following features are not available in realms with Customer Key enabled:

• Batch Subscribe

• Batch Unsubscribe

The Customer Key is optional to include in the following reports:

• Event Report

• Contact Export

A Customer Key is required for the following features:

• Contact Import

• Contact Create

• Contact Edit

• Preference Sites

  • Subscribe is not available because no Customer Key yet exists for new contact

  • Unsubscribe and Manage require Customer Key

• Template Preview

Customer Key is optional in the following features:

• Contact Search

• Template and Article Content

• Event Macros

Areas Affected in APIs

Each of the platform APIs has several commands that are affected by the use of Customer Key in a realm.  Several commands were also created specifically to use the Customer Key. 

FTP API

The customer_key is required with email in the data argument for the following commands:

• Subscribe

• SmartSubscribe

• Unsubscribe

• Save

• Delete

• Send

HTTP API

The customer_key is required with email in the data argument for the following commands:

• Subscribe

• Unsubscribe

• Delete

• Send

The customer_key is optional in the following commands:

• Change

• Find Contact

• Find Subsciber in List

• Report Contact Events

The Update command will fail in a realm with Customer Key enabled.

The following reports include the Customer Key in the output results:

• Report Browser Info

• Report Contact Clicks

• Report Bounce Statistics

• Report Unsubscribes

• Report Contacts In List

• Report Tracked Events

• Report Tracked Events By Campaign

• Show Opt Outs

• Show Global Opt Outs

• Show Hard Bounces

• Show Soft Bounces

• Show Complaints

• Show Block Bounces

WebServices API

The following commands are new for Customer Key only realms.  They use the same functionality as their counterpart calls, but include customer_key as well:

• userSetDataByCustomerKey

• userSetDataStringByCustomerKey

• userSetDataBigStringByCustomerKey

• userSetDataIntByCustomerKey

• userSetDataDateByCustomerKey

• userSetDataFloatByCustomerKey

• userSetDataUnicodeByCustomerKey

• userUnSubscribeByCustomerKey

• userSubscribeByCustomerKey

• userSubscribeWithCustomDataByCustomerKey

• userSubscribeOptOutByCustomerKey

• indSubscriberByCustomerKey

• userGetDataByCustomerKey

• userGetAllDataByCustomerKey

• userClearDataByCustomerKey

• userClearAllDataByCustomerKey

• userDeleteByCustomerKey

• userOptOutsByCustomerKey

• userSubscribeToListsByCustomerKey

• userSubscriptionsByCustomerKey

• getSubscriberEventsByCustomerKey

• getSubscriberIDByCustomerKey

• useCustomerKey

• findSubscriberByCustomerKey   (same as userSearch)

• useCustomerKey    (used in ws_api_tests to intelligently display the correct API calls to use for a realm)

The customer_key is returned with the results of the following commands:

• getBounceStats

• getBrowserInfoByCampaign

• getSubscribersWhoClickedOnURL

• getTrackedEvents

• getTrackedEventsByCampaign

• getUnsubscribeReport

The customer_key is required in the <to> tag of sendMessage (with XML).  Instead of: <to>[email], it is now: <to><email>[email]<customer_key>[customer_key]. If the realm is not using Customer Key, no change is required, but the following is also acceptable: . However, this would also be acceptable: <to><email>[email].