EXM recipient profiles

Last updated Thursday, January 19, 2017 in Email Experience Manager for Developer, Administrator

You can use various sources of recipients to send email campaigns to, including both those provided by Sitecore and your own sources.

The Email Experience Manager represents a recipient as a basic entity containing the recipient ID only. The recipient entity is implemented by the Sitecore.Modules.EmailCampaign.Recipients.Recipient class.

The recipient ID

The recipient ID is a class that identifies a recipient in the source. Depending on the source, the type of the recipient ID may vary, which is why the recipient ID is represented by the abstract Sitecore.Modules.EmailCampaign.Recipients.RecipientId base class. This lets you avoid specifying the source and type of the recipient when it is not necessary.

Each recipient source must have a corresponding class that extends the RecipientID class and defines the type and behavior of the ID.

EXM can use the recipient ID as a key in hash-based collections. To ensure that these types of collections can work properly, you must provide custom implementations of the Equals() and GetHashCode() methods.

If the recipient ID is stored in plain text, for example, in a database, EXM invokes the ToString() method to get a string representation of the ID. This means that the ToString() method must return a string that identifies the type of the recipient ID and can be used to create an instance of the recipient ID class.

EXM uses the prefixes xdb: , for example, xdb:12345678-abcd-1234-abcd-000123456789 for xDB contacts.

Recipients come from the Sitecore Experience Database (xDB) or your custom source. By default, EXM provides the following implementation of RecipientID:

  • To identify an xDB contact by the contact ID, use the Sitecore.Modules.EmailCampaign.Xdb.XdbContactId class.

    For example: xdb:12345678-abcd-1234-abcd-000123456789.


To specify additional information about the recipient, you can add custom properties to the basic entity. The recipient profile in EXM has the following default properties:

  • PersonalInfo { First name, Last name, Full name } contains personal details of the recipient.
  • Email { Email address, Undelivered count } contains an email address and the number of temporary delivery failures, also known as soft bounces, for the address. This property is required for the EXM to be able to send an email.
  • XdbRelation { Contact id, Identifier } describes how the recipient is related to xDB via an xDB contact. The DispatchNewsletter pipeline uses this property to queue message recipients. For this reason, the XdbRecipientRepository recipient repository adds this property to recipients.
  • Phone { Phone number } contains the recipient phone number.
  • CommunicationSettings { Is communication suspended, Preferred language } contains details about whether the recipient can be contacted and their preferred communication language.

ContactListAssociations { Contact list ids } contains the IDs of the contact lists that the recipient is associated with. This property is only relevant to xDB contacts, because it's the only recipient type that can be associated with contact lists. You can create new properties by creating new classes that extend the abstract Property class.

A recipient can have multiple properties of the same type, each of which is assigned a tag. When using multiple properties, the first property of each type that you add to the recipient is automatically set as the default.

Send feedback about the documentation to docsite@sitecore.net.