November Happy Hour will be moved to Thursday December 5th.

AI OnAI Off

Recipient Sources

Product version:

EPiServer Mail 5 and 5 R2

Document last saved:
  

For larger organizations, it is possible to create different “sites” that selected users or groups can be given access to.  See the section System Settings – Users and User Groups.

Source – Recipient List

To implement your own recipient source you need to implement the IRecipientSource interface.

Recipient class

The Recipient class is defined in the EPiServer.Mail.Core namespace. The Recipient class defines the following public properties:

  • Guid ID - The unique identifier of the recipient.
  • String Email - The email address of the recipient.
  • AttributeCollection Attributes - The collection of attributes of the recipient. These attributes are used for substitution of variables in the mail body. The variables in the mail body must be in the format §a§, §b§, §c§ etc. and are substituted by the corresponding attribute where the order of attributes in the attribute collection coincides with the alphabetic order of the variable name.
  • Bool IsUnsubscribed - Gets whether the user has been marked as unsubscribed.
  • Guid ContainerId - Gets the unique identifier of the RecipientContainer that this Recipient is connected to.

RecipientContainer class

The RecipientContainer class represents a specific list of recipients. One of the properties of a RecipientContainer is an implementation of the IRecipientSource interface that the RecipientContainer was provided by.

Creating a Source

This section describes the properties and methods defined in the IRecipientSource Interface in the EPiServerMail.Core.Sources namespace that is required at implementation. For methods and properties that adds or removes recipients, see the IRecipientStore interface.

  • Guid ID – The unique identifier for this source. This must be constant for any given source.
  • string Name– The name of this source. This must be constant for any given source.
  • RecipientContainerCollection GetRecipientContainers– Should return a recipient container collection (if the provided Site is not applicable, return your list of RecipientContainers when the Site is null), using page and pagesize to limit the result, returning the total number of items in totalItems and use order for sorting. The implemented sorting capabilities are exposed using the property SortingCapabilities.
  • RecipientContainer GetRecipientContainer– Should return the recipient container with the supplied Guid or name.
  • Recipient GetRecipient– Should return the recipient for the supplied Guid.
  • RecipientCollection GetRecipients– Should return the recipients for the supplied RecipientContainer.
  • Void UnsubscribeRecipient– Should toggle unsubscription of the supplied recipient.
  • Void AddBouncedAddress–Should add a bounced address to a recipient container in order to filter out invalid addresses.
  • RecipientSourceSortingCapabilities SortingCapabilities– Returns which sorting capabilities the source has, using the flag RecipientSourceSortingCapabilities.

Creating a Store

This section describes the properties and methods defined in the IRecipientStore Interface in the EPiServerMail.Core.Sources namespace that is required at implementation.

  • RecipientStoreCapabilities Capabilities– Returns which capabilities the store has, using the flag RecipientStoreCapabilities.
  • Void ImportStream– When importing is supported and exposed, using Capabilities, use of the upload form in EPiServer Mail Editor results in a recipient container being created and a stream containing the uploaded file is supplied.
  • RecipientContainer AddRecipientContainer– Should return and add a recipient container.
  • Void RemoveRecipientContainer– Should remove a recipient container with the supplied guid. If removal of RecipientContainers is not supported, just return.
  • InvalidImportRecordCollection GetInvalidImportRecordCollection– Should remove a collection of invalid import records for the supplied recipient container.

Place the compiled assembly in the bin directory on the web server.

Sample Code

When running EPiServer Mail together with EPiServer Community or EPiServer CMS 4.x there are options to install implementations of IRecipientSource for these, during the EPiServer Mail installation. The EPiServer Community source selects all current EPiServer Community users with the subscription user attribute set. The name of the attribute can be specified in the configuration file. The EPiServer CMS source selects all current EPiServer CMS users. The sample code provided in this Developers Guide is an example of a custom source.

 

Standard - Recipient List

Import

EPiServer Mail can import e-mail address lists from XML and CSV text files (semi colon separated).

CSV files

Most commonly email lists are imported from Excel.

When importing email addresses from Microsoft Excel the file needs to be saved in a specific format. Please see instructions below.

Recipients List

 

The first row is a header row and is not imported to EPiServer Mail. The first column is always used as the email address. It is possible to import a list that consists of only one column with email addresses. In the example above, there are additional columns with variables such as Name, Sur Name and Title. These variables can be used for different needs and are used to personalize each email sent from EPiServer Mail.

EPiServer Mail handles up to 20 variables for each recipient list.

Save the Excel sheet as a CSV-file (semi colon separated) and make sure that the file has the format UTF-8. If it is not possible to make sure that the CSV-file is in UTF-8format, open the file with a regular text editor, such as Notepad, and save the file again making sure that the file is in UTF-8 format. 

XML

An email list can also be imported from an XML-file. See below for an example of a compatible XML-file:

<?xml version="1.0" encoding="utf-8" ?>
<EPiServerMailImport>      
  <attributes>            
     <attribute id="1">attributeName1</attribute>
     <attribute id="2">attributeName2</attribute>
     <attribute id="3">attributeName3</attribute>
  </attributes>      
  <recipient>            
     <email>email1@example.com</email>            
     <attributeList>                 
         <attribute id="1">attribute value for attr 1</attribute>
         <attribute id="2">attribute value for attr 2</attribute>
         <attribute id="3">attribute value for attr 3</attribute>
     </attributeList>
  </recipient>
  <recipient>
     <email>email2@example.com</email>
     <attributeList>
         <attribute id="1">attribute value for attr 1</attribute>
         <attribute id="2">attribute value for attr 2</attribute>
         <attribute id="3">attribute value for attr 3</attribute>
    </attributeList>
  </recipient>
  <recipient>
     <email>email3@example.com</email>
     <attributeList>
         <attribute id="1">attribute value for attr 1</attribute>
         <attribute id="2">attribute value for attr 2</attribute>
         <attribute id="3">attribute value for attr 3</attribute>
    </attributeList>
  </recipient>
</EPiServerMailImport>