Sitecore for Developers
Sitecore Email Experience Manager – Installation & Configuration
Let’s get Sitecore Email Experience Manager(EXM) to work. By work I mean let’s install, configure and send some emails from EXM. When I landed on this territory of Sitecore ecosystem I had no idea what it all takes to get EXM working but finally playing with around for few hours I got a hold of it. So, if you are looking to start with EXM with no background knowledge of how to install & configure it this blog post would help you get started.
Latest version of Email Experience Manager can be downloaded from dev.sitecore.net. EXM is bundled up as a Sitecore package which can be installed on any Sitecore instance using Installation Wizard from Sitecore. Once the zip is downloaded point to note here is it is not a Sitecore package, the file name too has a disclaimer attached mentioning (not sc package). It contains many other packages too.
[caption id="attachment_3804" align="alignnone" width="780"] [/caption]
Installation
EXM Installation guide has all the details that are required to install EXM. Here I am going to mention an abstract of what is available in the guide. As a prerequisite before installing EXM module two steps needs to be completed,
1) Add two empty connection strings with the names master and exm.web. For example:
[code language="csharp"]<add name="exm.master" connectionString="" />
<add name="exm.web" connectionString="" />[/code]
2) Add the two connection strings CryptographicKey and EXM.AuthenticationKey. The keys must be represented in hexadecimal format by 64 characters, where you can use the symbols 0-9 and A-F. For example:
[code language="csharp"]<add name="EXM.CryptographicKey" connectionString= "E040C938FC9E4EBC3E93330B0F7837F284207B8180DB64CB5B6ABEB1AFBF6F5B" />
<add name="EXM.AuthenticationKey" connectionString= "9D80B4E56AEE694058567BD89C936FB88F2DB1272A4E88F419B6501919E0BB25" />[/code]
Installation guide does mentions a note that should not be ignored,
Note
For security reasons, do not use the example key provided above.
How to generate these keys? Well I used Random.Org.
Copy the string generated in some text editor, remove all the white spaces and update connectionString value for both EXM.CryptographicKey and EXM.AuthenticationKey. As an example my string now looked like
[code language="csharp"]<add name="EXM.CryptographicKey" connectionString="1acda6a3dd6178045eb13b28e4c5dac2cde2339ded292205743fc495d5edba84" />
<add name="EXM.AuthenticationKey" connectionString="ceb73b557b29f685d4b0ef6b2baeaba78ef539a9903d00adb9ad3783d60d4c7a" />[/code]
Let’s swing back to some action now! EXM installation is pretty simple and works like a charm as any other Sitecore package works. Install Email Experience Manager 3.4.1 rev. 170105.zip using Installation Wizard.
Installation will also dump EXM SQL database files so to complete the installation, move the following database files to the /Databases folder and attach them to a SQL Server instance.
o Sitecore.Exm.ldf
o Sitecore.Exm.mdf
o Sitecore.Exm_Web.ldf
o Sitecore.Exm_Web.mdf
I was eager to know what are the visual changes that were made to the content tree after the installation. Hope you too will be looking out for it, Are you?
After successful installation, the first visual change you will notice is on Launchpad which now have Email Experience Manager link under the Marketing Applications.
Content Tree will have a new node “/sitecore/content/Email Campaign” with Message Types and Messages. The module is installed at “/sitecore/system/Modules/E-mail Campaign Manager”
There are few configuration changes that needs to happen before we can start the actual usage of EXM and send out some test emails.
1) Update connectionstrings.config file to have below exm.master and exm.web connection strings. As an example,
[code language="csharp"]<add name="exm.master" connectionString="user id=user;password=password;Data Source=(server);Database=Sitecore_EXM" />
<add name="exm.web" connectionString="user id=user;password=password;Data Source=(server);Database=Sitecore_EXM.WEB"/>[/code]
2) In the /App_Config/Include/Sitecore.Analytics.Tracking.config file, ensure the value of the ClusterName setting is set to your instance host name. For example
[code language="csharp"]<setting name="Analytics.ClusterName" value="sc82up2exmplay"/>[/code]
3) Lastly setup the message transfer agent. EXM has made two options available for setting up an agent based on client’s need.
- Sitecore Email Cloud
- Custom SMTP
Sitecore has already provided “The Sitecore Email Cloud compared to the custom SMTP” compassion that will help you to make a decision.
As a playground, it’s better to use Custom SMTP which will leave out licensing issues and subscription to App Centre. On a production environment, you might of course want to configure Sitecore Email Cloud.
Configuring EXM for Custom SMTP
To start using the Custom SMTP:
1) In the?Website\App_Config\Include\EmailExperiencefolder, add the suffix .disabled to the end of the following file names:
- EDS.Providers.Sparkpost.config
- EDS.Providers.Sparkpost.Sync.config
2) In the Website\App_Config\Include\EmailExperiencefolder, remove the suffix .disabled from the following file names:
- EDS.Providers.CustomSmtp.config.disabled
- EDS.Providers.CustomSmtp.Sync.config.disabled
3) Update pop3Settings in EDS.Providers.CustomSmtp.config
4) Update smtpSettings in Sitecore.EDS.Providers.CustomSmtp.Sync.config
Making life better for a developer I have created xml patch files, ready for use that can be dumped into Sitecore instance at path Website\App_Config\Include\zzz
I used Gmail SMTP configuration to send out emails hence these files have all the details related to Gmail Pop3 and SMTP except username and password.
Lastly you might want to put on verbose logging to troubleshoot EXM issues if any faced after installation and while sending emails. To enable it update below setting to true in file Website\App_Config\Include\EmailExperience\Sitecore.ExM.Framework.config
[code language="csharp"]<setting name="EXM.Debug" value="true" />[/code]
Opening Email Experience Manager from Launchpad will take you to below screen where there is not data yet to report.
1) Update Default settings, more information can be found at The EXM default settings
2) Create an email campaign. As can be seen from screen shot there are two types of it. For simplicity, I went ahead creating a Regular email campaign. Looking for more information see Types of email campaigns.
EXM has some inbuilt template that can be used while creating a campaign.
I selected “Modern” as my campaign’s template. Are you wondering how do I get it? It is available in the EXM package as “Email Experience Manager Sample Newsletter 3.4.1 rev. 170105.zip” hence installing this Sitecore package will get a new template into EXM.
3) Creating a campaign is a five-step process. First one is to specify General information about the campaign.
EXM reports From Email field to be mandatory if it is not specified
4) Select Recipients, in order to create a list of recipients check Creating A Contact List section of this blog post
5) Message Details
6) Review: Before sending out actual emails we can review the email by sending it out to our self
I placed myself as the reviewer and was able to get an email as below,
7) Delivery: Final step for creating an email campaign. Hitting Send Message starts sending out emails and keeps posted about the activities.
Moving back to dashboard now will have has some data to be reported
1) Open List Manager for Sitecore Launchpad
2) Hit Create, different options are available to make it quick and easy for me I used Empty Contact List.
3) Enter information related to Contact List and Hit Save
4) Click on Contact Drop Down and click on Create and add new contact
5) Enter Email address, First name and Last name values and Save it.
6) Few warnings appears as contact is being created and indexed. Have patience I understand the eagerness to send out emails from EXM.
7) On refreshing the page added contact will appear on the list
Tips for Troubleshooting Email Sending
1) EXM records all activities in two log files, so checkout for any errors into these log files.
- Eds.log
- Exm.log
2) Gmail blocks signing in from unsecure apps which it did for me too. Turning “On” Allow less Secure App setting will allow EXM to send email message vis Gmail SMTP. I received and email from Gmail stating they have blocked access for an unsecure app.
Other way to enable this setting in Gmail is to,
- Login into Gmail
- Go to settings -> Account and Import
- Click on Other Google Account Settings
- Under Sign-in & Security click Connected apps & sites
- Enable Allow less secure apps. You may want to turn this setting off once playing around with EXM is completed.
Finally EXM is done and dusted. There is more to learn on EXM but whatever is noted down in the blog post helped me get started.