A4 - the Sitecore Developer Network

A4 - the Sitecore Developer Network
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Administrator’s and Developer’s Guide Rev: 23 April 2015
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Administrator’s and
Developer’s Guide
A Quick Start Guide and Configuration Reference for Administrators and Developers
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Table of Contents
Chapter 1 Introduction .......................................................................................................................... 4
Chapter 2 Quick Start Guide ................................................................................................................ 5
2.1
Setting up the Module ............................................................................................................. 6
2.1.1 Configuring Default Settings ............................................................................................... 6
2.1.2 Configuring Message Transfer Agent ................................................................................. 7
Using Sitecore App Center’s Email Delivery Service as an MTA ................................................ 7
Using a Custom MTA ................................................................................................................... 7
2.2
Adding a Subscription Form to a Page ................................................................................... 8
2.2.1 Subscription Form Control Properties ................................................................................. 8
2.3
Assigning Security Roles to ECM Users ............................................................................... 10
Chapter 3 Configuration Manual ........................................................................................................ 11
3.1
Configuring Sitecore Application Center ............................................................................... 12
3.2
Collecting Delivery Status Notifications ................................................................................ 13
Using the Sitecore MTA ............................................................................................................. 13
Using a Custom MTA ................................................................................................................. 14
3.3
Configuring Dedicated Servers ............................................................................................. 15
3.4
Configuring the Module on Scaled Environment................................................................... 16
3.4.1 Multi-server Environment .................................................................................................. 16
3.4.2 Deploying the Module on a Content Delivery Server ........................................................ 16
3.5
Verifying a Connection between ECM and MTA................................................................... 18
3.6
Installing Design Importer with ECM 2.1 ............................................................................... 20
3.7
Enabling Multi-Language Message Dispatch ........................................................................ 21
Chapter 4 Performance Tuning .......................................................................................................... 22
4.1
Using the Performance Measurement Tool .......................................................................... 23
4.2
Using the Emulation Mode to Test Performance .................................................................. 24
Chapter 5 ECM Configuration Reference .......................................................................................... 25
5.1
Sitecore.EmailCampaign.config ............................................................................................ 26
5.1.1 The EmailValidation setting ............................................................................................... 29
5.2
Global Settings ...................................................................................................................... 30
5.2.1 Common Text .................................................................................................................... 30
5.2.2 Tasks ................................................................................................................................. 30
5.2.3 System .............................................................................................................................. 31
App Center ................................................................................................................................. 31
Root List ..................................................................................................................................... 31
Security Key ............................................................................................................................... 31
5.3
Manager Root Settings ......................................................................................................... 32
5.3.1 Message Generation ......................................................................................................... 32
5.3.2 Subscription Control .......................................................................................................... 33
5.3.3 Implementation Details ...................................................................................................... 33
5.3.4 Delivery Status Notifications ............................................................................................. 34
5.3.5 Default Message Header .................................................................................................. 34
5.4
Message Type Configuration ................................................................................................ 35
5.4.1 Message ............................................................................................................................ 35
Configuring Insert Options for the Message Type ..................................................................... 35
5.4.2 Subscription Message ....................................................................................................... 36
Configuring Insert Options for the Subscription Message Type ................................................ 36
5.4.3 Triggered Message ........................................................................................................... 38
Configuring Insert Options for the Triggered Message Type ..................................................... 38
5.5
Message Configuration ......................................................................................................... 40
5.6
ECM Actions.......................................................................................................................... 41
5.6.1 Engagement Automation Actions ...................................................................................... 41
5.6.2 Send E-mail Rule Engine Action ....................................................................................... 41
5.7
Using ECM in Multi-Site Environments ................................................................................. 42
5.7.1 How to Differentiate Manager Roots between Sites ......................................................... 42
5.8
Personalization and the Online Message Version ................................................................ 43
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 2 of 69
Administrator’s and Developer’s Guide
5.8.1 Process Personalization Tokens Sublayout ...................................................................... 43
5.9
Emails that Bounce and the Undelivered Max Setting .......................................................... 45
5.10 The Message Engagement Plan ........................................................................................... 46
5.11 ECM Security Roles .............................................................................................................. 48
5.12 Designing Message Layouts and Renderings ...................................................................... 49
5.13 Issues with Sitecore CMS Web.config Settings .................................................................... 50
Chapter 6 Implementation Details ...................................................................................................... 51
6.1
Dispatch General Overview .................................................................................................. 52
6.1.1 Using the Sitecore MTA .................................................................................................... 52
6.1.2 Using a Custom MTA ........................................................................................................ 54
6.2
Dispatch Process .................................................................................................................. 55
6.2.1 DispatchNewsletter Pipeline ............................................................................................. 55
CheckPreconditions ................................................................................................................... 55
MoveToProcessing .................................................................................................................... 55
DeployAnalytics .......................................................................................................................... 55
QueueMessage .......................................................................................................................... 56
LaunchDedicatedServers ........................................................................................................... 56
SendMessage ............................................................................................................................ 56
MoveToSent ............................................................................................................................... 57
NotifyDispatchFinished .............................................................................................................. 57
FinalizeDispatch ......................................................................................................................... 57
6.2.2 SendEmail Pipeline ........................................................................................................... 57
FillEmail ...................................................................................................................................... 57
SendEmail .................................................................................................................................. 57
Chapter 7 Advanced User Guide ....................................................................................................... 58
7.1
Send a Message When a Specific Event Occurs ................................................................. 59
7.2
The ECM Double Opt-In Process.......................................................................................... 62
7.2.1 Customizable Settings of the Double Opt-In Process ....................................................... 62
Chapter 8 Tips and Tricks .................................................................................................................. 64
8.1
Detecting Requests from ECM.............................................................................................. 65
8.2
IIS Access ............................................................................................................................. 66
8.3
How to Use $name$ token .................................................................................................... 67
8.4
Code Samples ....................................................................................................................... 68
8.4.1 Creating a Simple Custom Email ...................................................................................... 68
8.4.2 Subscribing for a Newsletter ............................................................................................. 68
8.4.3 Sending an ECM Message to a Single E-mail .................................................................. 69
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 3 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Chapter 1
Introduction
This document is designed for Sitecore administrators and developers. It contains
information about how to set up, configure and tune the module.
For end user instructions, read the ECM Marketer’s Guide.
The document contains the following chapters:

Chapter 1 — Introduction
The introduction to this guide.

Chapter 2 — Quick Start Guide
The steps required for the quick setup of the E-Mail Campaign Manager. The quick
setup is the minimal amount of configuration that would let you use the module.

Chapter 3 — Configuration Manual
Practical advice on actions that you must perform to make the module ready for use
by end users.

Chapter 4 — Performance Tuning
Some important techniques that let you optimize the module performance
significantly.

Chapter 5 — ECM Configuration Reference
Module’s configuration settings. This chapter also contains information that will help
you to extend or modify the module.

Chapter 6 — Implementation Details
Description of the dispatch process in detail.

Chapter 7 — Advanced User Guide
The actions that you must perform to configure the module to send messages when a
specific event occurs.

Chapter 8 — Tips and Tricks
Additional information on ECM requests and IIS user credentials.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 4 of 69
Administrator’s and Developer’s Guide
Chapter 2
Quick Start Guide
This chapter describes how to quickly set up the E-Mail Campaign Manager. The
quick setup is the minimal amount of configuration that would let you use the module.
This chapter contains the following sections:

Setting up the Module

Adding a Subscription Form to a Page

Assigning Security Roles to ECM Users
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 5 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
2.1
Setting up the Module
After you install ECM, you must perform a Smart publish of the website. After that, you must configure
the default settings and the Message Transfer Agent.
2.1.1
Configuring Default Settings
When you installed the module package, configure default settings:
The default settings include the following ones:

Base URL
This is a required setting. Enter the website address of the ECM server in it. This URL is used
in all the links in the email message.

From address
This is a required setting. Enter the sender email address in it.

From name
This is an optional setting. Enter the sender name in it.

Reply to
This is an optional setting. Enter the email address where the replies will be sent to.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 6 of 69
Administrator’s and Developer’s Guide
To edit the default settings later, in the ECM application, in the Most Recently Dispatched
Messages, click Default Settings.
2.1.2
Configuring Message Transfer Agent
You can use either SAC’s Message Transfer Agent (MTA) or custom MTA.
Using Sitecore App Center’s Email Delivery Service as an MTA
The ECM module uses the external MTA by default. MTA is software that transfers email messages
from one computer to another using a client–server application architecture.
The module obtains all the necessary SMTP settings from the Sitecore App Center. For more
information about configuring SAC, see the Configuring Sitecore Application Center section.
You can test the MTA connection. For more information about how to test the connection, see the
Verifying a Connection between ECM and MTA section.
Using a Custom MTA
If you have purchased the right to use a custom MTA, you should set the UseLocalMTA setting to true
in the Sitecore.EmailCampaign.Config file:
<setting name="UseLocalMTA" value="true" />
Then you should configure all the required SMTP settings in the
Sitecore.EmailCampaign.Config file in the <sitecore>/<settings> section.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 7 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
2.2
Adding a Subscription Form to a Page
The ECM module contains the Subscription Form control that you can add to your pages. By default,
the control is stored at /sitecore/layout/Sublayouts/Email Campaign/Subscription
Form.
2.2.1
Subscription Form Control Properties
The Subscription Form control has the following module-specific properties:
Require Authentication
When this check box is selected, only users who have logged in to the website can see the form
control. Unauthenticated users see the message Please login to change subscription settings.
If you want to edit this text, open the following item:
/sitecore/system/Modules/Email Campaign Manager/Common Text/Please Login
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 8 of 69
Administrator’s and Developer’s Guide
Show List
When this check box is selected, recipient lists specified in the Recipient Lists field are displayed on
the website.
When a user clicks Subscribe on the website, they are added to the mailing lists they selected and
removed from the lists they didn’t select. For instance, if the user does not select any mailing lists and
clicks Subscribe, they are unsubscribed from all of them.
When the Show List check box is not selected, recipient lists are not displayed on the website. When
a user clicks Subscribe on the form, the user is subscribed to all the recipient lists specified in the
Recipient List field of the control.
Recipient List
Use this field to specify the recipient lists for the current subscription form control.
The location of the manager roots (one or many) on your site is defined in the
/sitecore/system/Modules/Email Campaign Manager/System/Root List item. The
module updates this item automatically.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 9 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
2.3
Assigning Security Roles to ECM Users
To let the marketers use the ECM application, you must assign one of the following roles to them:

ECM Users

ECM Advanced Users
Those roles provide enough rights to the users to work with the ECM.
If in your CMS solution the roles in roles feature is disabled, you must assign two more Sitecore roles
to let the users edit the message body:

sitecore\Sitecore Client users

sitecore\Sitecore Client Authoring
For more information about ECM roles, see the section ECM Security Roles.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 10 of 69
Administrator’s and Developer’s Guide
Chapter 3
Configuration Manual
This chapter describes the actions that administrator must perform to make the
module ready for use by end users.
This chapter contains the following sections:

Configuring Sitecore Application Center

Collecting Delivery Status Notifications

Configuring Dedicated Servers

Configuring the Module on Scaled Environment

Verifying a Connection between ECM and MTA

Installing Design Importer with ECM 2.1

Enabling Multi-Language Message Dispatch
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 11 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
3.1
Configuring Sitecore Application Center
To be able to send Email Campaign messages, you must configure SAC. For the detailed instructions
about how to configure SAC, see the Getting Started with Sitecore App Center document on the SDN.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 12 of 69
Administrator’s and Developer’s Guide
3.2
Collecting Delivery Status Notifications
Errors can occur at multiple places during e-mail delivery. A sender may receive a bounce message
from the sender's mail server or from a recipient's mail server. When a server accepts a message for
delivery, it is also accepting the responsibility to deliver a DSN (Delivery Status Notification) in the
event the delivery fails.
Depending on whether you use the Sitecore MTA or not, the module uses one of the two methods to
collect the DSN messages.
Using the Sitecore MTA
If you use the Sitecore MTA, then the SAC collects the DSN messages and then passes them to the
module.
There is a scheduled task called Check Bounced Messages at the following location:
/sitecore/system/Tasks/Schedules/Email Campaign/Check Bounced Messages
This scheduled task defines when and how the SAC checks the bounced messages and passes them
to the ECM.
In the Schedule field, you can define when the task runs.
In this example, the Schedule field contains the following value:
20150126T235900|20151226T235900|127|12:00:00
This task will be executed from 26.01.2015 23:59:00 to 26.12.2015 23:59:00, every day (as specified
by the number 127) and every 12 hours (as specified by 12:00:00).
In the Schedule field, you can place 4 parameters divided by pipe separators:

From date

To date

Days of the week. Use the DaysOfWeek enumeration. For Monday and Friday, you should
write 34 (2+32).
public enum DaysOfWeek
{
None = 0,
Sunday = 1,
Monday = 2,
Tuesday = 4,
Wednesday = 8,
Thursday = 16,
Friday = 32,
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 13 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Saturday = 64,
}

Interval, for example: 01:00:00 – every 1 hour.
The Items field contains the time when the SAC collected the DSN messages last.
When this task runs, it collects the DSN messages starting from the time in the Items field and ending
with the time defined by the expression “Current Time – 24 hours”.
For example, if you run the task for the first time on July 5, it collects information from the beginning of
the history to July 4. The Items field contains July 4 value. If you run this task next day, on July 6 it
collects information from July 4 to July 5. The Items field contains July 5 value.
Using a Custom MTA
If you use a custom MTA, the module uses the settings in a Manager Root to collect the DSN
messages.
The E-Mail Campaign Manager collects the DSN messages for analysis. To collect the DSN
messages, the module connects to the mailbox specified in the Return Address field in the Delivery
Status Notifications section of the Manager Root.
The following setting defines how frequently the module checks the Return Address e-mail for DSN
messages:
/sitecore/system/Tasks/Schedules/Email Campaign/Check DSN Messages
The module collects DSN messages once a day by default.
You can configure the Delivery Status Notifications on a Manager Root.
To configure the module to gather DSN messages:
1. On the Manager Root, on the Content tab, in the Delivery Status Notifications section,
check the Collect Notifications checkbox and enter the POP3 server settings.
For more information about the fields in the Delivery Status Notifications section, see Delivery
Status Notifications.
Now the module can connect to the sender’s mailbox and gather the DSN messages.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 14 of 69
Administrator’s and Developer’s Guide
3.3
Configuring Dedicated Servers
The E-mail Campaign Manager can use dedicated servers to speed up the message generation and
sending process.
Every dedicated server contains a copy of the Sitecore CMS installation from the master server. This
lets the dedicated server generate messages the same way as the master server. All servers share
the same databases. The database server must support remote access to databases.
To configure the dedicated server:
1. Copy the Sitecore CMS installation to the dedicated server. You should copy the whole file
system, but not the databases.
2. On the dedicated server, set the folder permissions required for Sitecore to run.
3. On the dedicated server, in the ConnectionStrings.config file, make sure the
connections point to the same databases as the master server uses.
4. On the dedicated server, in the Web.config file, edit the absolute paths so that they point to
correct locations. For example, the dataFolder setting.
5. On the dedicated server, remove the <scheduling> section from the
Sitecore.EmailCampaign.config file.
6. On the dedicated server, start Sitecore and make sure that it works.
7. On the master server, in the Sitecore.EmailCampaign.config file, in the
<DedicatedServers> section, enter the address of the dedicated server. For example:
<DedicatedServers>
<address value="http://ecmdedicatedserver.net" />
</DedicatedServers>
Note
If you enter the IP address of the dedicated server in the address setting (for instance: <address
value="http://10.38.41.24" />), then on the dedicated server Sitecore must run on the
Default Web Site.
You have now configured the dedicated server.
You can configure several dedicated servers in this manner.
When you start the dispatch process on the master server, the same process starts on the dedicated
servers. Each server accesses the list of subscribers in the Analytics database, takes one of the
remaining subscribers, generates the message for them, and passes the message to the MTA
configured for this server. The process continues as long as there are subscribers left in the list.
Tip
Use the Sleep setting to balance the load between the master server and dedicated servers. For more
information about the Sleep setting, see ECM Tuning Guide on the SDN.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 15 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
3.4
Configuring the Module on Scaled Environment
This section describes how to configure the module to work on a scaled environment - one Content
Management (CM) server, and one or more Content Delivery (CD) server(s).
3.4.1
Multi-server Environment
You can scale the ECM module by configuring a multi-server environment.
To configure a multi-server environment:
1. Install the SPEAK and ECM packages on a CM server. For more information about installing
the module, see Installation Guide on the SDN.
2. Deploy the module on all CD servers.
3. Make sure that the Base URL setting leads to a CD server.
4. Automate the Analytics Deployment on CD servers. For more information, see section 6.2.1
DeployAnalytics.
Important
Don't forget to publish message before sending (for online version availability).
3.4.2
Deploying the Module on a Content Delivery Server
When the module is installed on a CM server, deploy it on all CD servers.
To deploy the module on content delivery server(s):
1. Publish the Master database to every content delivery server.
For more information about publishing the Master database, see the Scaling Guide document,
section 3.1 Configuring a Remote Publishing Target.
2. Deploy the module files on CD servers.
If CD servers don’t have a client interface, copy the following files and folders from the CM
server to every CD server:
\App_Config\Include\Sitecore.EmailCampaign.config
\bin\Sitecore.EmailCampaign.dll
\layouts\ EmailCampaign\*
\sitecore\ConfirmSubscription.aspx
\sitecore\RedirectUrlPage.aspx
\sitecore\Unsubscribe.aspx
\sitecore\UnsubscribeFromAll.aspx
\sitecore modules\shell\ EmailCampaign\*
\sitecore modules\web\ EmailCampaign\*
\xsl\ EmailCampaign\*
If CD servers have the client interface, install the SPEAK and ECM packages on CD servers
using the Installation Wizard.
3. Add the following connection string to the connectionstrings.config file on every CD
server:
<add name="EmailCampaignClientService"
connectionString="url=http://<master_server>/sitecore%20modules/web/emailca
mpaign/ecmclientservice.asmx;timeout=60000" />
<master_server> stands for your master server address, for instance, www.site.net or
10.38.41.30.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 16 of 69
Administrator’s and Developer’s Guide
Ensure that the master server can handle the inbound connection from CD servers. This may
require configuring the firewall inbound rule with open port #80 or #443 for HTTP or HTTPS
protocol respectively.
4. In the \App_Config\Include\Sitecore.EmailCampaign.config file, remove the
following lines:
<initialize>
<processor
type="Sitecore.EmailCampaign.Presentation.UI.Pipelines.Loader.InitializePresenterBinde
r, Sitecore.EmailCampaign.Presentation.UI" />
<processor
type="Sitecore.EmailCampaign.Presentation.UI.Pipelines.Loader.ConfigurePresenterBinder
Container, Sitecore.EmailCampaign.Presentation.UI" />
</initialize>
and:
<scheduling>
<agent type="Sitecore.Tasks.DatabaseAgent" method="Run" interval="00:00:59"
hint="ECM">
<param desc="database">master</param>
<param desc="schedule root">/sitecore/system/modules/e-mail campaign
manager/tasks</param>
<LogActivity>true</LogActivity>
</agent>
</scheduling>
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 17 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
3.5
Verifying a Connection between ECM and MTA
If you use MTA provided by SAC or have configured your local (custom) MTA server, you can test the
connection.
To test the connection:
1. Start the E-mail Campaign Manager.
2. Select the E-mail Campaign root item.
3. On the E-mail tab, in the Server group, click Test Connection.
The module starts the Test Email Connection dialog box. Click Show Details to see the
detailed information.
Let’s take a look at the information that the dialog box contains.

Sitecore App Center user ID
This line indicates your ID in the SAC service.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 18 of 69
Administrator’s and Developer’s Guide

Calling Sitecore App Center…
To obtain your MTA settings, the tool contacts SAC and lists the settings it obtains if the call is
successful. If the call is not successful, the tool displays an error message and some hints
that may help you to troubleshoot the problem:

Calling MTA…
If the tool obtains the SMTP settings successfully, it uses them to call the MTA. If the call is
successful, you see the MTA OK message.
If the call is not successful, the tool displays an error message and some hints that may help
you to troubleshoot the problem. If you click the Connection failed link, the tool displays more
details about the problem that it encountered.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 19 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
3.6
Installing Design Importer with ECM 2.1
If you installed the Design Importer module after installing ECM 2.1 and if you plan to use the Design
Importer with ECM, then you must install the Design Importer Update package that you find on the
ECM 2.1 Downloads page.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 20 of 69
Administrator’s and Developer’s Guide
3.7
Enabling Multi-Language Message Dispatch
Starting from version 2.1, the ECM lets you deliver messages to recipients in their preferred language.
This functionality is disabled by default. To enable it, edit the following setting in the
Sitecore.EmailCampaign.config file:
<setting name="LanguageFieldName" value="" />
This setting specifies the property name of a user profile, which the ECM uses as a recipient’s
preferred language. For instance, the following setting will work with a default recipient profile:
<setting name="LanguageFieldName" value="ContentLanguage" />
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 21 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Chapter 4
Performance Tuning
The speed with which emails are sent and delivered depends on a complex set of
factors and dependencies. For more information about how to optimize the
performance of the ECM, see the ECM Tuning Guide on the SDN.
This chapter contains the following sections:

Using the Performance Measurement Tool

Using the Emulation Mode to Test Performance
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 22 of 69
Administrator’s and Developer’s Guide
4.1
Using the Performance Measurement Tool
The ECM Performance Measurement Tool is designed to give the customer or consultant a view
into the performance of an E-mail campaign based on current configuration settings.
For information about how to access and use this tool, see the ECM Tuning Guide document on the
SDN.
Note
A user must belong to the ECM Users or ECM Advanced Users role in order to use the tool.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 23 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
4.2
Using the Emulation Mode to Test Performance
The ECM module provides means of testing campaign throughput by emulating a MTA. MTA
emulation allows you to mimic the round trip time required to send an E-mail from the Sitecore CMS
to a MTA.
Emulation can be configured in two modes
1. Emulation for a Single Message.
You can select this mode for a specific message in the Options section, on the Content tab.
You can also select the emulation mode for a single message using the Dispatch Options
dialog in the ECM user interface:
2. Emulation for the Server level Dispatch.
You can configure this mode with the MtaEmulation.Active setting in the
Sitecore.EmailCampaign.config file.
For more information about configuring and using the emulation mode, see ECM Tuning Guide on the
SDN.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 24 of 69
Administrator’s and Developer’s Guide
Chapter 5
ECM Configuration Reference
This chapter describes the module’s configuration settings. You can configure the
module using the configuration file and tune it at different levels: global level,
message root level, message type level or at specific message level. This chapter
also contains information that will help you to extend or modify the module.
This chapter contains the following sections:

Sitecore.EmailCampaign.config

Global Settings

Manager Root Settings

Message Type Configuration

Message Configuration

ECM Actions

Using ECM in Multi-Site Environments

Personalization and the Online Message Version

Emails that Bounce and the Undelivered Max Setting

The Message Engagement Plan

ECM Security Roles

Designing Message Layouts and Renderings

Issues with Sitecore CMS Web.config Settings
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 25 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.1
Sitecore.EmailCampaign.config
This section describes the main Sitecore.EmailCampaign.config settings, located in the
<sitecore>/<settings> section.
Setting name
Sample
Description
value
UseLocalMTA
false
Set to "true" if you want use the custom SMTP
settings from the
Sitecore.EmailCampaign.config file.
You should purchase the right of using the
"UseLocalMTA" setting first.
Debug
false
Specifies whether verbose logging in Sitecore
log files is enabled. Use to troubleshoot ECM
problems.
NumberThreads
4
The number of threads that you can use for
sending messages. For information about
tuning the performance using this setting, see
ECM Tuning Guide on the SDN.
MaxGenerationThreads
8
Specifies how many sending threads can
generate messages at the same time. By
default, the MaxGenerationThreads setting has
a default value of
Environment.ProcessorCount * 2. For more
information about this setting, see ECM Tuning
Guide, Chapter 4, Tuning Procedures.
RecipientsRequestSize
500
This is the number of recipients that are
queued from the analytics database in a single
request. For more information about this
setting, see ECM Tuning Guide, Chapter 4,
Tuning Procedures.
Sleep
50
The amount of time to wait between sending
messages (ms).
MaxConnectionUnavailable
9000
The period of time (in seconds) the module
tries to restore an MTA connection before a
dispatch is paused.
MaxSendingAttempts
5
The number of attempts to send a message (in
case of need). These attempts are done when
there is a connection with the MTA, but the
sending process fails on the sending server
side.
CheckReceiverRights
false
If the value of this setting is false, the module
does not check whether the current subscriber
has access to the item being rendered during
the message generation. For best
performance, make sure that this setting is
false.
RolesInRoles
false
This setting defines whether the module
accounts users that belong to roles that are
nested in roles. This is related to the Optin/Opt-out Role fields.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 26 of 69
Administrator’s and Developer’s Guide
Setting name
Sample
value
Description
ConfirmationPeriod
10
The period (in days) after which Sitecore
deletes a user who used a subscription control
to subscribe to a mailing list, but did not
confirm the subscription.
EmailValidation
Any valid
RegExp
The regular expression that is used for e-mail
validation. For more information, see section
5.1.1, The EmailValidation setting.
MaxMessageFolderSize
50
The maximum number of messages (or
message related campaigns, tests, etc.) that
ECM creates in a single folder. If there are
more messages than this number, the ECM
creates another folder.
PhoneFieldName
phone
The field name in a Sitecore user profile. The
value of this field is used as a contact phone
number. This property was added to the
Sitecore.EmailCampaign.config file
because a corresponding field does not exist in
the default user profile in Sitecore CMS. You
should change the value of this setting if you
already have the phone number field in your
custom user profile.
ShellSiteName
shell
The name of the Shell website as it is specified
in your Web.config file.
IIS.User
serviceuser
The user name to log in with if anonymous
access is disabled.
IIS.Password
12345
The password to log in with if anonymous
access is disabled.
MtaEmulation.Active
false
Set to true to enable MTA emulation mode. For
more information about this setting, see ECM
Tuning Guide, Section 4.4, MTA Emulation.
MtaEmulation.MinSendTime
200
This is the minimum amount of time, in
milliseconds, to emulate the sending of a
single E-mail. Use this in conjunction with
MtaEmulation.MaxSendTime to mimic the
behavior of Sitecore CMS to MTA round trip
time.
MtaEmulation.MaxSendTime
400
This is the maximum amount of time, in
milliseconds, to emulate the sending of a
single E-mail.
MtaEmulation.FailProbability
0.01
This setting allows you to introduce the
probability of connection failure into your
emulation. For more information about this
setting, see ECM Tuning Guide, Section 4.4,
MTA Emulation.
Proxy.Enabled
false
If this setting is set to true, the ECM will
request the SMTP server via a proxy server.
Proxy.Type
HTTP
This setting contains the type of the proxy
server. Valid values are: "HTTP", "SOCKS4",
"SOCKS5".
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 27 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Setting name
Sample
value
Description
Proxy.HostName
site.com
This setting contains the proxy server IP
address or DNS name.
Proxy.Port
80
This setting contains the proxy server port.
Proxy.AuthMethod
LOGIN
This setting contains the HTTP authentication
method of the proxy server. Valid values are:
"LOGIN", "NTLM"
Proxy.Username
username
This setting contains the user name for logging
into the proxy server.
Proxy.Password
Pass123
This setting contains the password for logging
into the proxy server. The value is ignored for
SOCKS4 proxy type.
QueryStringKey.Campaign
ec_camp
This setting specifies the name of the query
string parameter, which identifies an e-mail
campaign.
QueryStringKey.AutomationState
ec_as
QueryStringKey.EcmId
ec_id
QueryStringKey.Recipient
These settings are used internally by the
module when building query strings for
generating messages.
ec_recipien
t
QueryStringKey.Subscription
ec_subscr
SMTP.Server
localhost
SMTP server address or IP.
SMTP.Port
25
Port number of the SMTP server.
SMTP.LoginDomain
Domain for logging into SMTP server.
SMTP.UserName
admin
User name for logging into SMTP server.
SMTP.Password
12345
Password for accessing the SMTP server.
SMTP.AuthMethod
LOGIN
SMTP Authentication method ("NONE",
"LOGIN", "PLAIN", "CRAM-MD5", "NTLM")
SMTP.StartTLS
false
Start TLS option. When set to true, this makes
the mailman to issue a STARTTLS command
and switch over to a secure SSL/TLS
connection prior to authenticating and sending
e-mail.
SMTP.MaxConnections
100
The maximum number of concurrent SMTP
connections allowed to open. For more
information about this setting, see ECM Tuning
Guide, Chapter 4, Tuning Procedures.
SMTP.ConnectionExpiration
180
The period of time (in seconds) the module
keeps an SMTP connection open (since the
last usage).
StandardMessages.
SubscriptionConfirmation
<relative
path to the
item>
When a visitor subscribes to a mailing list, they
receive this message from Sitecore. This
message contains the subscription
confirmation link.
StandardMessages.
SubscriptionNotification
<relative
path to the
item>
When a user clicks on the confirmation link in
the subscription confirmation message, the
ECM sends this message to them.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 28 of 69
Administrator’s and Developer’s Guide
Setting name
Sample
value
Description
StandardMessages.
UnsubscribeNotification
<relative
path to the
item>
When a subscriber opts out from a mailing list,
they receive this message from ECM.
StandardMessages.UnsubscribeFr
omAllNotification
<relative
path to the
item>
When a subscriber opts out from all mailing
lists, they receive this message from ECM.
StandardMessages.
DispatchCompleted
<relative
path to the
item>
When the dispatch process is finished,
Sitecore sends this message to the e-mail
address specified in the Dispatch Process
Notifications section.
StandardMessages.TrickleNotifi
cation
<relative
path to the
item>
This setting specifies the path to the activation
status message of a triggered message.
UrlValidation
Any valid
RegExp
The regular expression that is used for URL
validation. This validation is applied in places
where users enter URLs.
5.1.1
The EmailValidation setting
When a user submits an email address, E-mail Campaign Manager uses the EmailValidation setting
to verify that the string is in valid email format.
The EmailValidation setting takes a regular expression for email validation as a value.
The default regex is not RFC compliant and does not cater for all cases. To address specific regional
use cases or business needs, you should use a custom regular expression.
For more information about the RFC standards, see the RFC specifications at the IETF website.
The EmailValidation setting is located in the <sitecore>/<settings> section of the ECM
configuration file:
\App_Config\Include\Sitecore.EmailCampaign.config
You can replace the default value with your custom regex:
<setting name="EmailValidation" value="^[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*@(?:[a-zA-Z09](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$" />
The recommended way to modify the setting is to comment out the default value or to override the
configuration file to keep a record of the initial value.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 29 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.2
Global Settings
This section describes the global module settings that are common to all the manager roots in a
solution.
The item that contains the global module settings is located at
/sitecore/system/Modules/Email Campaign Manager.
You can also access this item by selecting Sitecore, All Applications, Email Campaign, Settings
on the Sitecore Desktop.
This item contains the following settings:
Setting name
Sample value
Description
Default Root Parent
<path to item>
This field defines the parent item, under which the
manager root should be located.
No Send
false
When selected, the actual access to the SMTP server is
suppressed and you receive the “Sending Disabled”
message when you try to dispatch messages.
5.2.1
Common Text
This item contains the various labels and messages that are used throughout the module.
5.2.2
Tasks
This item contains the scheduled dispatches. If you decide to dispatch messages at a specific time,
Sitecore creates the appropriate task under this item.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 30 of 69
Administrator’s and Developer’s Guide
5.2.3
System
This item contains the system items that are used by the module.
App Center
This item stores settings for Sitecore Application Center in the ECM application.
Root List
This item contains the list of manager roots in the Manager Roots field. The module uses this list,
among other things, to display the available subscription lists in a subscription form. This item is
updated automatically.
Security Key
This item contains the private system key used during the message generation. The module
generates this key automatically during the installation.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 31 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.3
Manager Root Settings
This section describes the manager root settings. To see these settings, select the manager root item
and then select the Content tab on the right.
The manager root item contains the following sections:

Message Generation

Subscription Control

Implementation Details

Delivery Status Notification

Default Message Header
5.3.1
Message Generation
This section contains the following settings:
Setting name
Sample value
Description
Base URL
http://localhost/
The website address used for links in
messages and for images, if they are hosted on
the website.
Encoding
utf-8
The encoding used for the outgoing messages.
Embed Images
true
Whether images are embedded in the message
or links to images are inserted.
Track Message Open
true
When selected, the module embeds a one-pixel
image in the message to track whether a
subscriber opens the message.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 32 of 69
Administrator’s and Developer’s Guide
5.3.2
Subscription Control
In this section, you specify the pages that a site visitor is redirected to when they subscribe to a
mailing list and when they change their subscription preferences.
This section contains the following settings:
Setting name
Sample value
Description
Already Unsubscribed
<path to item>
When a visitor who is already unsubscribed clicks on
the unsubscribe link, the module displays this page.
E-mail Sent Confirmation
Page
<path to item>
When a visitor submits the subscription form,
Sitecore sends a confirmation e-mail and redirects
the visitor to this page. By default, this field is empty
which means that the visitor stays on the same page
after submitting the form.
Final Confirmation Page
<path to item>
This is the page the visitor is redirected to after
changing their mailing list subscriptions (for instance,
cancelling a subscription to a specific mailing list).
By default, this field is empty which means that the
visitor stays on the same page.
5.3.3
Implementation Details
In this section, you specify the security domain for the manager root, the opt-out role common to all
target audiences under this root, and the default subscriber profile.
This section contains the following settings:
Setting name
Sample value
Description
Common Domain
Emailcampaign
The domain common to all the recipient lists under
this root.
Common Opt-out Role
Emailcampaign\
Common Opt
Out
This is the opt-out role that is common to all the
recipient lists under this root. Users who are
members of this role will not receive messages from
any of the recipient lists under this root.
Default Subscriber Profile
Profiles/Subscri
ber
The user profile that is used for all the subscribers of
this manager root.
Undelivered Max
10
The maximum number of temporary delivery failures
per subscriber. For example, recipient server
response timeout is a temporary failure. For more
information about this setting, see section 5.9,
Emails that Bounce and the Undelivered Max Setting
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 33 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.3.4
Delivery Status Notifications
If the module uses a custom MTA to send messages, it uses this section to configure how the DSN
messages are collected. If the module uses the Sitecore MTA, then it uses SAC to collect the DSN
messages and this section is ignored.
This section contains the following settings:
Setting name
Sample value
Description
Collect Notification
cleared
Whether or not to collect delivery status notifications
from the e-mail box used by the module for sending
messages. If this check box is cleared, the rest of the
section is ignored.
If this check box is selected, but other fields of this
section are empty, these fields will be inherited from the
manager root.
If this check box is cleared, the module behaves as
though all the messages are delivered successfully.
Return Address
dsn@site.net
The e-mail address for collecting the DSN messages.
The MTA service sends DSN messages to this address.
The module gets DSN messages from this address for
analysis using POP3 protocol.
POP3 Server
pop.server.com
The POP3 server address/name.
POP3 SSL
Default
Whether or not the POP3 server uses SSL for
transferring messages.
POP3 Port
110
The port for transferring messages from the POP3
server.
POP3 User Name
serveruser
The POP3 server user name.
POP3 Password
12345
The POP3 server user password.
5.3.5
Default Message Header
In this section, you can specify the From Name, From Address and Reply To settings that are used
by all the messages.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 34 of 69
Administrator’s and Developer’s Guide
5.4
Message Type Configuration
You can configure messages on a message type level, setting up their default parameters.
5.4.1
Message
The item that contains the message type settings is located at sitecore.
This item contains the following settings:
Setting name
Sample value
Description
Campaign Position
Emails
This field defines the default campaign category that
stores campaigns related to this message type.
Marketers can change this value in the ECM UI.
Standard Message
Plan
Standard/Emails
This field defines the default engagement plan for the
message type. Marketers cannot choose another
engagement plan in the ECM UI, they can only edit it.
Configuring Insert Options for the Message Type
To change the range of message templates that marketers can choose under the Message type:
1. Select /sitecore/system/Modules/Email Campaign Manager/Message
Types/Message/Default item.
2. On the ribbon, in the Configure tab, click Assign.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 35 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
3. In the Insert Options dialog box, change the range of message templates.
5.4.2
Subscription Message
The items that contain the subscription message type settings are located at
/sitecore/system/Modules/Email Campaign Manager/Message Types/Subscription
Message.
You can configure several templates for subscription messages so they contain specific recipient list
and message header.
This item contains the following settings:
Setting name
Sample value
Description
Recipient List
<path to item>
Default recipient list for the message
From Name
Paolo
Default sender’s name
From Address
Paologi@paologiacom.com
Default sender’s address
Reply To
support@paologiacom.com
Default email address for replies
Campaign
Position
Emails
This field defines the default campaign category
that stores campaigns related to this message
type. Marketers can change this value in the
ECM UI.
Standard
Message Plan
Standard/Emails
This field defines the default engagement plan
for the message type. Marketers cannot change
this value in the ECM UI.
Configuring Insert Options for the Subscription Message Type
You can change message template that marketers can use under the Subscription Message group.
For example, you want to implement two different groups of subscription messages with different
default settings. Moreover, each group should contain specific message templates.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 36 of 69
Administrator’s and Developer’s Guide
To implement this task, perform the following actions:
1. Create items under /sitecore/Content/Home/E-mail Campaign/Message
Types/Subscription Message:
2. Configure insert options for both items:
Now when you configured two groups of subscription messages, marketers can use them in the ECM
UI. They see groups as folders:
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 37 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
When marketers select a group, they see insert options as message templates:
5.4.3
Triggered Message
The item that contains the triggered message type settings is located at
/sitecore/system/Modules/Email Campaign Manager/Message
Types/Triggered/Default.
This item contains the following settings:
Setting name
Sample value
Description
Campaign Position
Emails
This field defines the default campaign category that
stores campaigns related to this message type.
Marketers can change this value in the ECM UI.
Standard Message
Plan
Standard/Emails
This field defines the default engagement plan for the
message type. Marketers cannot choose another
engagement plan in the ECM UI, they can only edit it.
Configuring Insert Options for the Triggered Message Type
To change the range of message templates that marketers can choose under the Triggered Message
type:
1. Select /sitecore/system/Modules/Email Campaign Manager/Message
Types/Triggered/Default item.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 38 of 69
Administrator’s and Developer’s Guide
2. On the ribbon, in the Configure tab, click Assign.
3. In the Insert Options dialog box, change the range of message templates.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 39 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.5
Message Configuration
You can configure settings on a specific message.
To configure a message, in the Content Editor, under the Sitecore/Content/Home/E-mail
Campaign/Messages folder, select a message in the appropriate subfolder.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 40 of 69
Administrator’s and Developer’s Guide
5.6
ECM Actions
This section describes the engagement automation actions and rule engine actions that the ECM
installs.
5.6.1
Engagement Automation Actions
The ECM module provides two engagement automation actions in the default installation: Send
Email Campaign Message and Edit Email Audience. The Marketing Automation Monitor performs
these actions on the visitors who meet the conditions that you specify in the plan. The items of both
actions are stored in the following folder:
sitecore/system/settings/analytics/engagement automation/predefined
items/actions.
You can configure both actions directly in the engagement plan. For more information about
configuring automation actions, see the How to Use ECM Actions section in the ECM Marketers
Guide.
5.6.2
Send E-mail Rule Engine Action
The ECM module installs the Send Email rule engine action at the following path:
/system/Settings/Rules/Common/Actions/Send Email
You can use this action to send a triggered message to the current context user when a specific event
occurs.
Make sure that the triggered message that you use with this action is activated. Otherwise, the ECM
will not send it.
Note
If the current context user has an empty Email field in their user profile, the action will not work.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 41 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.7
Using ECM in Multi-Site Environments
Organizations that use the E-mail Campaign Manager in multi-site environments must define
business logic to differentiate between sites when:

A Sitecore user accesses the E-mail Campaign Manager.

They use the E-mail Campaign Manager.
A manager root contains all the settings that control the end user experience when they work with the
module.
5.7.1
How to Differentiate Manager Roots between Sites
In this example, we assume that an organization has the following business logic:

There are several sites defined in a Sitecore solution and each site has its own manager root.

A user who logs into the Sitecore Desktop has access only to one manager root.
By default, the module searches for the manager root under the item defined in the Default Root
Parent setting:
In a multi-site solution, the manager roots that relate to different sites may be located in different
places in the content tree. The ECM can display several manager roots for one user and the user can
switch between roots using the root switcher:
You can use standard Sitecore security applications to grant users permissions to specific manager
roots.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 42 of 69
Administrator’s and Developer’s Guide
5.8
Personalization and the Online Message Version
In an e-mail campaign, you may want to have an online version of your newsletter and let people view
it in a browser or send links to it to their friends.
For instance, take a look at the following sample newsletter. It contains tokens and the link that lets
subscribers view the online version:
When a subscriber receives the message and clicks this link, they are redirected to the online copy of
the newsletter.
The online copy:

Is personalized.

Does not contain the “Please click here to see…” header and the “Unsubscribe Instructions”
footer.

Is created automatically when the message is created.
The online copy looks like this:
The ECM recognizes an online copy automatically and does not render appropriate controls.
5.8.1
Process Personalization Tokens Sublayout
The Process Personalization Tokens sublayout substitutes tokens with appropriate values from
subscriber profiles.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 43 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
When attached to a message definition item, this sublayout overrides the OnLoad method and
substitutes the tokens. For instance, this is how the Device Editor dialog box looks when you attach
the sublayout:
The sublayout uses the ec_as parameter to get the subscriber profile values for tokens. You can
change ec_as value in the QueryStringKey.AutomationState parameter, in the
Sitecore.EmailCampaign.config file.
The Process Personalization Tokens sublayout is attached to the following message templates by
default:

Newsletter Message.

Two-Column Message.

One-Column Message.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 44 of 69
Administrator’s and Developer’s Guide
5.9
Emails that Bounce and the Undelivered Max Setting
This section describes how the ECM deals with emails that bounce.
A bounce email is a message that is returned to the sender because it cannot be delivered for some
reason. There are two kinds of bounce email: soft bounce and hard bounce.
A soft bounce is a temporary failure and there is a chance that the recipient will receive the message
eventually. A soft bounce means that the email address is recognized by the recipient's mail server
but the message is returned to the sender because the recipient's email box is full, the mail server is
temporarily unavailable, or the recipient no longer has an e-mail account at that address.
A hard bounce is a permanent failure. A hard bounce means that the email is permanently bounced
back to the sender because the address is invalid.
A subscriber’s profile contains the UndeliveredCount property, which is incremented by one when a
soft bounce is registered for this subscriber.
A manager root item contains the Undelivered Max setting, which defines the maximum number of
soft bounces per subscriber, or the maximum value of the UndeliveredCount property.
When the UndeliveredCount value equals the Undelivered Max value, the module does not send
messages to this subscriber. If a hard bounce is registered for a subscriber, their UndeliveredCount
property is set equal to the Undelivered Max.
When a subscriber clicks a link in a message that was sent to them using the ECM, their
UndeliveredCount property is set to null.
Note
The Email Delivery service offered by the Sitecore App Center moves an e-mail to the suppression list
when the number of soft bounces for this e-mail reaches a predefined limit. Therefore, if the ECM is
used with the Sitecore MTA, the Undelivered Max setting must be configured according to this value.
For more details, see the Email Delivery for Sitecore ECM document.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 45 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.10
The Message Engagement Plan
The ECM installs the Engagement Plan called Message Plan, which is stored at the following
location: /sitecore/system/Marketing Center/Engagement Plans/Email
Campaign/Standard/Message Plan.
When a user creates a new message, Sitecore creates a copy of the standard engagement plan
(referred to as the “message plan”) in a location that is defined in the Campaigns Position field of a
message type:
The ECM uses this engagement plan to reflect the state of visitors during the dispatch process.
Business users may extend the message plan to define automated behavior for the message.
When a message is dispatched, the engagement plan must be deployed to the Analytics database
before the first message is queued for sending.
You can specify a default engagement plan for every target audience using the settings of the target
audience item.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 46 of 69
Administrator’s and Developer’s Guide
The following image shows the Marketing Automation Monitor with the ECM Message Plan:
For information about the groups, states and conditions in the message plan, see the manual ECM
Marketer’s Guide, Section 7.3, Marketing Automation Monitor.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 47 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.11
ECM Security Roles
The ECM installs two security roles:

ECM Users.

ECM Advanced Users.
Both roles provide access rights to the ECM application.
ECM Users
This role limits user’s access to some features of the ECM application:
Access Granted
Access Rejected
All the functionality of the ECM application is
accessible except for the features that are listed
in the Access Rejected column.
Change default settings
Delete messages
Edit the engagement plan
Open behavior monitor
Change recipient lists for the periodical
messages
Expand the More tab in the General tab
ECM Advanced Users
This role provides the user with the access rights to all the functionality of the ECM application.
Access Granted
Access Rejected
All the functionality of the ECM
application is accessible.
-
Sitecore Roles Required by ECM Users to Edit a Message Body
The ECM Users or ECM Advanced Users role is enough for the ECM user to be able to work with
messages. However, if a CMS solution, where the ECM is installed on, disables the roles in roles
feature in the Web.config file (the rolesInRolesManager parameter) then you must assign two more
Sitecore roles in addition to either ECM Users or ECM Advanced Users role:

sitecore\Sitecore Client users

sitecore\Sitecore Client Authoring
Make sure you added the mentioned above roles to the ECM Users and ECM Advanced Users roles
if roles in roles is disabled on your CMS solution.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 48 of 69
Administrator’s and Developer’s Guide
5.12
Designing Message Layouts and Renderings
In order to be processed properly, all renderings used in a message layout should have the following
value in the Parameters Template field of a rendering:
/sitecore/templates/Modules/Email Campaign/ID Source Based Parameters
For instance:
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 49 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5.13
Issues with Sitecore CMS Web.config Settings
If the following setting exists in the Web.config file on an installation where ECM 2.0 is installed, the
Create One Time message command will not work displaying the ”Page not found” error (383429):
<encodeNameReplacements>
<replace mode="on" find=" " replaceWith="-" />
</encodeNameReplacements>
This issue is caused by a limitation in ECM 2.0.
Workaround:

In the Web.config file, remove the following setting:
<replace mode="on" find=" " replaceWith="-" />
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 50 of 69
Administrator’s and Developer’s Guide
Chapter 6
Implementation Details
This chapter describes how the dispatch process works and what the administrator
must do to make this process reliable and smooth.
This chapter contains the following sections:

Dispatch General Overview

Dispatch Process
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 51 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
6.1
Dispatch General Overview
This section describes the general principles of the dispatch process. For instance, what services and
applications are involved in the process and how to configure the Firewall.
The dispatch process differs depending on which type of MTA you use – Sitecore’s MTA through the
Sitecore App Center or a custom MTA.
6.1.1
Using the Sitecore MTA
This section describes the general principles of the dispatch process in case you use the Sitecore
MTA.
The following diagram contains details about the steps in the dispatch process and the required
configuration:
Note
Sitecore MTA requires that you open ports 25, 80, and 443.
A typical environment contains the following components:

The ECM module installed on a Sitecore CMS behind a firewall.

The Sitecore App Center (SAC).
When the ECM starts dispatching the messages, it checks with the Sitecore App Center that
you have purchased the Email Delivery service to send this batch of messages and gets the
SMTP server settings to use when sending the messages. The ECM caches these settings
and uses them for all further dispatches to increase performance. The module requests the
updated settings from SAC only in case when it encounters a problem with sending a
message.

The in-house or third party MTA.
The following list describes the events that take place during the dispatch process and the settings
related to the steps.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 52 of 69
Administrator’s and Developer’s Guide
Step 1. The ECM module connects to the SAC and requests the MTA settings.
Related setting: the connection string in the ConnectionStrings.config file.
For this connection, in the firewall, you must create the outbound rule with open port #80. The HTTP
protocol is used.
The SAC charges your account to send this batch of messages and sends the MTA server settings.
Step 2. The SAC provides the MTA settings.
The MTA settings include:

MTA server name or IP.

Port number (#X).
The ECM module uses this port to contact the MTA.

MTA server access credentials (user name and password).
Step 3. The ECM module sends e-mail messages to the MTA.
The ECM module sends e-mail messages to the MTA using the settings obtained on the previous
step.
For this connection, in the firewall, you must create the outbound rule with open port #X. The SMTP
protocol is used.
Email messages contain the following data:

From – the email address of the person who sends the message.

To – the email address of the recipient.

Message body.
Step 4. The MTA sends the e-mail messages to the recipients.
Step 5. The ECM requests the information about the bounced messages from SAC.
The ECM requests the information about the bounced messages from SAC using a scheduled task.
For more information about this scheduled task, see section Using the Sitecore MTA.
For this connection, in the firewall, you must create the outbound rule with open port #443. The
HTTPS protocol is used.
Step 6. The SAC provides the information about the bounced messages to the ECM.
The SAC provides the information about the bounced messages to the ECM.
For this connection, the firewall must allow the inbound traffic coming as a response to the request
generated in step 5.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 53 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
6.1.2
Using a Custom MTA
This section describes the general principles of the dispatch process in case you use a custom MTA.
The following diagram contains details about the steps in the dispatch process and the required
configuration:
A typical environment contains the following components:

The ECM module installed on a Sitecore CMS behind a firewall.

The in-house SMTP server.
The following list describes the events that take place during the dispatch process and the settings
related to the steps.
Step 1. The ECM module sends e-mail messages to the MTA server.
The ECM module sends e-mail messages to the MTA server using the settings in the
Sitecore.EmailCampaign.config file.
For this connection, in firewall, you must create the outbound rule with open port #X. The SMTP
protocol is used.
Step 2. The MTA sends the e-mail messages to the recipients.
Step 3. The MTA server sends the DSN messages to the corporate email address.
The SMTP server sends the DSN messages to the address specified in the Return Address field.
Usually this address is hosted on a corporate e-mail server.
Step 4. The ECM module connects to the e-mail server and gets the DSN messages
for further analysis.
The POP3 protocol is used for this connection. For more information about collecting the DSN
messages, see section Collecting Delivery Status Notifications.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 54 of 69
Administrator’s and Developer’s Guide
6.2
Dispatch Process
The dispatch process starts when one of the following events occurs. There may be other conditions
that can start the dispatch process, but these are the most common ones.

A user launches the message dispatching using the Dispatch tab.

The scheduled dispatch time arrives.

A user clicks Resume on the Dispatch tab.

A user clicks Send Now on the Dispatch tab when the message is scheduled to be sent
later.

The Send Email Campaign Message action is triggered.
When the dispatch process is triggered, the following actions take place.
If you use the Sitecore MTA, the module checks with the Sitecore App Center that you have
purchased the Email Delivery service to send this batch of messages and gets the SMTP server
settings to use when sending the messages.
If the UseLocalMTA setting is set to true, the module checks whether your license permits you to use
your own MTA.
After the module has checked with the Sitecore App Center, the DispatchNewsletter pipeline
starts. The following section describes the processors of this pipeline.
6.2.1
DispatchNewsletter Pipeline
The DispatchNewsletter pipeline is defined in the Sitecore.EmailCampaign.config file.
This section describes the processors in this pipeline and contains a conceptual description of how
the message generation process works.
In this section, we assume that a Newsletter type message is being dispatched, since this message
requires the utilization of most of the module’s features.
CheckPreconditions
This processor checks whether all the conditions that are required to start sending the message are
met.
MoveToProcessing
This processor changes the state of the message from Draft to Sending.
DeployAnalytics
This processor changes the workflow state of the analytics definitions that are related to the message
(engagement plan, campaign, subject MV test) to Deployed and saves the definitions in the Analytics
database.
Automating the Analytics Deployment on CD Servers
If the value of the Analytics.DefaultDefinitionDatabase setting is different from master (for
example, on CD instances it may be set to web), make sure that the analytics definition items
(campaign, engagement plan) are published immediately after the dispatch is started (to be precise –
after the DeployAnalytics processor is executed). This will ensure that the analytics data tracking
is accurate.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 55 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
We suggest the following way to automate this:
1. Add an Auto Publish action (/sitecore/system/Workflows/Sample
Workflow/Approved/Auto Publish) to the Deployed state of the Analytics workflow
(/sitecore/system/Workflows/Analytics Workflow/Deployed).
2. In Web.config, in the /configuration/sitecore/databases/ setting, add the
definition of the workflow provider to the default definition database (on CD servers this is
often the Web database):
<database id="web" singleInstance="true" type="Sitecore.Data.Database,
Sitecore.Kernel">
...
<workflowProvider hint="defer" type="Sitecore.Workflows.Simple.WorkflowProvider,
Sitecore.Kernel">
<param desc="database">$(id)</param>
<param desc="history store" ref="workflowHistoryStores/main" param1="$(id)"/>
</workflowProvider>
...
QueueMessage
In this processor, the master server creates automation state records for subscribers (one automation
state per subscriber) in the Analytics database.
Note
If this processor stops unexpectedly (for example, if the server reboots), every automation state is
created again.
LaunchDedicatedServers
The master server launches the DispatchNewsletter pipeline on the dedicated servers. The web
service on the dedicated server ensures that the pipeline skips this step, the MoveToProcessing
processor, and other appropriate steps that should be skipped.
The master server and the dedicated servers share the same Analytics database.
SendMessage
In this processor, the master server and the dedicated servers generate and send messages.
In this processor, the following actions are performed:
The processor gets a contact from the list in the Analytics database.
Each server accesses the list of subscribers and takes one of the remaining subscribers to generate
the message for. The process continues as long as there are subscribers left in the list.
For every subscriber, the processor:

Assigns the appropriate automation state to the message.

Assigns the Sitecore user that corresponds to this subscriber to the message.

Raises the subscriber:assigned event.

Requests the page that corresponds to the message.
o
Sets the user as the context user for the requested page. Security restrictions are applied.

Adds the “message opened” image.

The processor starts the SendEmail pipeline and in that pipeline:
o
The page gets personalized.
o
The message is sent to the MTA defined in the Sitecore.EmailCampaign.config
file.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 56 of 69
Administrator’s and Developer’s Guide
The process continues as long as there are subscribers left in the list.
MoveToSent
This processor changes the state of the message from Sending to Sent.
NotifyDispatchFinished
This processor sends the notification when the dispatch process is finished.
FinalizeDispatch
This processor cleans up the internal variables of the round-robin MV test process and closes the
remaining connections to the SMTP server.
6.2.2
SendEmail Pipeline
The SendEmail pipeline is defined in the Sitecore.EmailCampaign.config file. The
SendMessage processor starts this pipeline for every email message to be sent. This section
describes the processors of this pipeline.
FillEmail
This processor implements the personalization in the message.
SendEmail
This processor sends the e-mail message to the MTA defined in the
Sitecore.EmailCampaign.config file.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 57 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Chapter 7
Advanced User Guide
This chapter contains information about the actions that administrator must perform to
configure the module to send messages when a specific event occurs.
This chapter contains the following section:

Send a Message When a Specific Event Occurs

The ECM Double Opt-In Process
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 58 of 69
Administrator’s and Developer’s Guide
7.1
Send a Message When a Specific Event Occurs
You use the Send E-mail rule engine action to send a message when a specific event occurs.
For instance, this section describes how to implement the following behavior:

You delete an item.

Sitecore checks whether this item is based on a specific template or not.

If it is, Sitecore sends a message to you.
To create the rule that implements this:
1. Navigate to the /sitecore/system/Settings/Rules/Item Deleted/Rules folder.
2. In the Folder tab, click Rule.
3. In the prompt dialog box, enter the name of the new rule and click OK.
Sitecore creates the new rule.
4. Select the new rule. Enter the name of the rule and click Edit Rule in the Rule field.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 59 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
5. Select the where the item template is specific template condition and the send specific e-mail
action.
6. In the Rule description field, in the phrase where item has specific template, click the word
specific and Sitecore opens the Select Item dialog box.
Select the template you would like to use as the rule condition and click OK.
7. In the Rule description field, in the phrase send specific e-mail, click the word specific and
Sitecore opens the Triggered Message dialog box.
Select the message that you want to send. Click OK.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 60 of 69
Administrator’s and Developer’s Guide
8. Now your Rule description field should look like this:
9. Click OK.
10. Save the rule.
You have now configured the rule. When you delete an item based on the specified template,
Sitecore sends you the message.
Important
ECM only sends active triggered messages.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 61 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
7.2
The ECM Double Opt-In Process
The E-mail Campaign Manager provides a series of controls and messages that help you to set up
and customize a double opt-in subscription process.
The ECM double opt-in process consists of the following steps:
1. Signing up via the self-service subscription control. ECM provides a default subscription form
control.
For more information about the subscription form control, see the section Adding a
Subscription Form to a Page.
2. Adding a subscriber to the database. After submitting the subscription form, a new subscriber
is assigned a unique ID and is added to the database as a user with the Subscriber role.
3. Redirecting to a confirmation page (optional).
4. Sending a confirmation message with a subscription confirmation link.
5. Sending a subscription notification message to a user who confirmed the subscription. A user
who subscribed to a mailing list, but did not confirm the subscription within the confirmation
period, is deleted from the database.
By default, subscribers stay on the same page after changing the mailing list subscriptions. However,
you can create custom confirmation pages and provide the module with the paths to start redirecting
subscribers. You can also customize messages that the module sends to subscribers during the
subscription process.
You cannot disable the subscription confirmation or otherwise switch to single opt-in.
7.2.1
Customizable Settings of the Double Opt-In Process
The ECM double opt-in process provides the following customizable settings:
Setting name
Setting location
Description
E-mail Sent Confirmation
Page
Manager root item >
Subscription control
Lets you redirect subscribers to a confirmation
page. You specify the relative path to your
custom page item. By default, this field is empty.
StandardMessages.
SubscriptionConfirmation
Sitecore.EmailCampaign.config
Lets you use a custom confirmation message.
You replace the default value with the relative
path to your custom message item.
The default value is:
Service Messages/Self-Service
Subscription/Subscription
Confirmation
Final Confirmation Page
Manager root item >
Subscription control
Lets you redirect subscribers to a final
confirmation page. You specify the relative path
to your custom page item. By default, this field is
empty.
StandardMessages.
SubscriptionNotification
Sitecore.EmailCampaign.config
Lets you use a custom subscription notification
message. You replace the default value with the
relative path to your custom message item.
The default value is:
Service Messages/Self-Service
Subscription/Subscription
Notification
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 62 of 69
Administrator’s and Developer’s Guide
Setting name
Setting location
Description
ConfirmationPeriod
Sitecore.EmailCampaign.config
Lets you set a custom confirmation period in
days. You specify how many days the
subscription confirmation link expires.
The default value is 10 (days).
For more information about the Subscription control section of the manager root item, see the section
Manager Root Settings.
For more information about the Sitecore.EmailCampaign.config settings, see the section
Sitecore.EmailCampaign.config.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 63 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
Chapter 8
Tips and Tricks
This chapter contains information about IIS user credentials and how to detect
requests from ECM.
This chapter contains the following sections:

Detecting Requests from ECM

IIS Access

How to Use $name$ token

Code Samples
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 64 of 69
Administrator’s and Developer’s Guide
8.1
Detecting Requests from ECM
You can let the layout on your page know whether the ECM is requesting the message body or if this
is a normal page request.
To do that, you should use the following Boolean method in your layout:
Sitecore.Modules.EmailCampaign.Util.IsMessageBodyRequest()
If the method returns true, the ECM is requesting the message body, otherwise it is a normal page
request.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 65 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
8.2
IIS Access
If your website requires authentication on IIS level, you can specify the appropriate IIS user
credentials in the following settings in the Sitecore.EmailCampaign.config file.
Setting name
Sample value
Description
IIS.User
serviceuser
The user name to log in with if anonymous access is
disabled.
IIS.Password
12345
The password to log in with if anonymous access is
disabled.
If anonymous access in IIS is enabled, you can leave these settings blank.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 66 of 69
Administrator’s and Developer’s Guide
8.3
How to Use $name$ token
You can replace a token with appropriate values from subscriber profiles. The $name$ token is
replaced with the value from the Profile.Name property.
However, by default, this field is available only in the API.
You can set it in the ECM Import Users Wizard.
Alternatively, you can perform the changes using the API:
Sitecore.Security.Accounts.User user =
Sitecore.Security.Accounts.User.FromName("Emailcampaign\\SubscriberNumberOne", true);
user.Profile.Name = "First Name";
user.Profile.Save();
Alternatively, you can add the Name field to a user's profile, for example:
core:/sitecore/system/Settings/Security/Profiles/Subscriber
In this case, you can edit the Name using the User Manager in the Profile section.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 67 of 69
E-Mail Campaign Manager 2.1 for Sitecore CMS 6.6
8.4
Code Samples
This section contains several code samples, which help to understand how to create a simple custom
email, subscribe/unsubscribe for a newsletter, and send an ECM message to a single e-mail.
8.4.1
Creating a Simple Custom Email
{
using Sitecore.Modules.EmailCampaign.Messages;
/// <summary>
/// Code sample of creating simple custom email
/// </summary>
public class CreateMessageExample
{
/// <summary>
/// Create message
/// </summary>
/// <param name="messageName">name of the message</param>
/// <param name="templateId">id of the Message template you want to use</param>
/// <param name="typeId">id of the Message Type item (example: /[manager root]/Message
Types/Adhoc/Default)</param>
public void CreateMessage(string messageName, string templateId, string typeId)
{
MessageItemSource.Create(messageName, templateId, typeId);
}
}
}
8.4.2
Subscribing for a Newsletter
{
using Sitecore.Modules.EmailCampaign;
/// <summary>
/// Code sample of subscribe/unsubscribe for newsletter in the ECM API document
/// </summary>
public class SubscribeExample
{
/// <summary>
/// Subscribe user to specific Recipient List
/// </summary>
/// <param name="username">
/// user name
/// </param>
/// <param name="recepientListId">
/// id of the Recepient List
/// </param>
/// <param name="confirmSubscription">
/// whether you need to send confirmation
/// </param>
public static void SubscribeToRecipientList(string username, string recepientListId, bool
confirmSubscription)
{
var targetAudiencesInfo = new[]
{
new TargetAudienceInfo
{
ID = recepientListId,
CustomData = "1"
}
};
ClientApi.UpdateSubscriptions(username, targetAudiencesInfo, confirmSubscription);
}
/// <summary>
/// Unsubscribe user from specific Recipient List
/// </summary>
/// <param name="username">
/// user name
/// </param>
/// <param name="recepientListId">
/// id of the Recepient List
/// </param>
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 68 of 69
Administrator’s and Developer’s Guide
/// <param name="confirmSubscription">
/// whether you need to send confirmation
/// </param>
public static void UnSubscribeFromRecipientList(string username, string recepientListId,
bool confirmSubscription)
{
var targetAudiencesInfo = new[]
{
new TargetAudienceInfo
{
ID = recepientListId,
CustomData = "0"
}
};
ClientApi.UpdateSubscriptions(username, targetAudiencesInfo, confirmSubscription);
}
}
}
8.4.3
Sending an ECM Message to a Single E-mail
using Sitecore.Modules.EmailCampaign;
using Sitecore.Modules.EmailCampaign.Messages;
/// <summary>
/// Sample for sending ECM message to single e-mail
/// </summary>
public class SendExample
{
/// <summary>
/// Send message to a single recipient
/// </summary>
/// <param name="messageItemId">ID of the message’s item you want to send</param>
/// <param name="userName">full name of the Sitecore User who will be message’s
recipient</param>
public void Send(ID messageItemId, string userName)
{
MessageItem message = Sitecore.Modules.EmailCampaign.Factory.GetMessage(<message item
id>);
Contact contactFromName = Contact.FromName(userName);
new AsyncSendingManager(message).SendStandardMessage(contactFromName);
}
}
Note
This code sample is applicable only to Standard or Triggered messages. This API can’t be used for a
common campaign message with an assigned recipient list like the One Time message.
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The
contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 69 of 69
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising