Harnessing Email Campaign Manager
Recently I was asked to build a messenger tool in Sitecore that would send emails to site users and allow select members to send messages to groups of users.
I built the tool by harnessing Sitecore’s Email Campaign Manager (ECM) functionality (now known as the Email Experience Manager) and this post highlights how to use the API for managing, sending and scheduling email.
For the uninitiated, Email Campaign Manager allows you to manage and send emails from your Sitecore shell.
The latest version has a cool new SPEAK interface which makes the management of emails easier than working with standard Sitecore items. Reporting tools are also much improved and simplified.
Anthony Hook has a great overview on using ECM 2.0.
For the build of this messaging tool I used ECM v2.1(I haven’t been able to get my hands on 2.2 just yet!). To get up and running with ECM, firstly download install the Speak Components package and then the ECM 2.1 Package.
You may find that the install takes a while, but go with it, it’ll get there in the end!
With the package installed, fire up the the SPEAK interface by going to All Programs -> Email Campaign Manager from the Sitecore Desktop. This will then create the necessary Email Campaign Manager node and various other items in Sitecore .
Creating and editing emails
So then firstly, how do you create an email?
For the tool I wanted to send emails of type AB Test Message as these are the most customisable.
// Create the Message
var master = Sitecore.Configuration.Factory.GetDatabase("master");
// This is the ID branch for the email - Two Column
string branchId = "{9E170B31-F8AA-4E1F-B605-2FC0BD4FE120}";
// This is the type of message - this is Adhoc.
Item typeItem = master.GetItem(Sitecore.Data.ID.Parse("{401F5ECD-5931-4C05-A4D1-501C07820830}"));
// This is the node where want to create the message
Item destination = master.GetItem(Sitecore.Data.ID.Parse("{2CF0A9C8-FE56-44D8-B750-6BDE3A34A532}"));
Sitecore.Modules.EmailCampaign.Messages.MessageItem message = Sitecore.Modules.EmailCampaign.Messages.MessageItemSource.Create("New Mail Messsage", templateId, typeItem, destination);
It’s in the Sitecore tree, so far so good!
Once we’ve called the Create method it will return a Message item. You can get access to the Sitecore item by using the InnerItem property on the message and treating it like any other Sitecore item.
// Edit the Message
var messageReturned = Sitecore.Modules.EmailCampaign.Factory.GetMessage(message.ID);
messageReturned.InnerItem.Editing.BeginEdit();
messageReturned.InnerItem["Body"] = "Message";</pre>
Sending an email
Ok, let’s send an email..
// Send the message Asynchronously
Sitecore.Modules.EmailCampaign.AsyncSendingManager manager = new Sitecore.Modules.EmailCampaign.AsyncSendingManager(message);
manager.SendMessage();
Let’s schedule an email for tomorrow!!
// Send Scheduled Message - This Creates a new Sitecore Task which sends at a specified time
Sitecore.Modules.EmailCampaign.Core.ScheduledDispatch dispatch = new Sitecore.Modules.EmailCampaign.Core.ScheduledDispatch(messageReturned);
DateTime tomorrow = DateTime.Now.AddDays(1);
dispatch.CreateSendingTaskItem(Sitecore.DateUtil.ToIsoDate(tomorrow));
Overrriding the Distribution List
A requirement for this tool was to have the distribution list for the email pulled in from an external service rather than using the target audiences and roles that are the default setup of ECM. This took a while to figure out, but I managed to get it working by adding a new pipeline processor.
The Email Campaign config file contains the DispatchNewsletter Pipeline. I inserted an entry here to run some code that would populate the distribution list before ECM’s default functionality take place.
<DispatchNewsletter>
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.CheckPreconditions, Sitecore.EmailCampaign" />
<!-- Insert Processor here -->
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.MoveToProcessing, Sitecore.EmailCampaign" />
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.DeployAnalytics, Sitecore.EmailCampaign" />
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.QueueMessage, Sitecore.EmailCampaign" />
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.LaunchDedicatedServers, Sitecore.EmailCampaign" />
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.SendMessage, Sitecore.EmailCampaign" />
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.MoveToSent, Sitecore.EmailCampaign" />
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.NotifyDispatchFinished, Sitecore.EmailCampaign" />
<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.DispatchNewsletter.FinalizeDispatch, Sitecore.EmailCampaign" />
</DispatchNewsletter>
The pipelne processer code below goes through a list of subscribers pulled from a REST service and adds them to the subscribers collection.
foreach (Person person in people)
{
Contact useraccount;
var username = Util.AddressToUserName(person.EmailAddress);
string commonDomain = managerRootFromId.Settings.CommonDomain;
string fullName = commonDomain + "\\" + Util.AddressToUserName(username);
if (User.Exists(fullName))
{
// Use existing details
useraccount = Contact.FromName(fullName);
}
else
{
// Create User Account
useraccount = Contact.GetAnonymousFromEmail(person.EmailAddress, managerRootFromId);
}
useraccount.InnerUser.Profile["Fullname"] = string.Format("{0} {1}", person.Firstname,
person.Surname);
useraccount.InnerUser.Profile["userid"] = person.Id;
// Update Subscriber Lists.
args.Message.Subscribers.Add(useraccount);
args.Message.SubscribersNames.Add(useraccount.InnerUser.Name);
}
You’ll notice that you still have to create a user in Sitecore - this unfortunately, is a requirement of ECM. The code above checks to see whether the user already exists in the system or creates a new anonymous user.
You can also access the Profile property of each user here to add in any extra personal information. For the tool I need to have the user ID available in the sent email.
To make this value available in the email, just use a standard Sitecore token:
One other thing to note; your email must have a target audience otherwise the subscribers collection will always be empty. So setup your email with a dummy target audience and you should be able to add/remove subscribers. You can find the Recipient List field under the System group in a AB Test Message item. You’ll want to set up the target audience in recipient list in the standard values of the item.
And that was all I needed to get my messenger tool up and running. I hope this post will provide a few shortcuts for anyone else wishing to use Email Campaign Manager functionality in the future.
Any questions? Leave a comment or get me on twitter @ianjohngraham.
