How to configure double opt-in in EXM and Sitecore 9.0.1 using Sitecore Forms

In latest versions of Sitecore there are two new features available for public audience. Sitecore Forms and integrated EXM.

Typical usecase for use of these two features will involve newsletter subscribing offered by Newsletter Subscription Form and maintaining double opt-in process inside of EXM.

Unfortunately, there is no straightforward way how to manage double opt-in together with Sitecore Forms, and we will need to make some additional (development) steps.

What we will need to do?

To make everything working, we will need several steps. It involves:

Configure EXM
Configure double opt-in prerequisities
Configure contact lists and mailing campaign
Subscription

1. Configuration of EXM

If we still haven’t configured EXM, we need to process basic configuration values which enables sending emails from EXM.

1.1 SMTP configuration

As a first step, SMTP configuration must be checked prior any further steps.

EXM has SMTP configuration in file App_Config\Sitecore\EmailExperience\Sitecore.EDS.Providers.CustomSMTP.config. Default configuration provided by Sitecore expects locally running SMTP server on port 25.

1.2 EXM configuration

If you haven’t yet configured EXM, there is necessary to perform basic EXM intial setup.

Open Sitecore Launchpad, and click on Email Experience icon:

When EXM opens, select Default settings to configure default settings.

Configuration screen appears. Few fields should be filled:

Base URL – base URL used for links used in sent emails

From email – email which will be used in From header and appears as sender of email

From name – name which will be used as sender

Reply to – email which will be used if recipient of email replies on received email

If everything was processed, new item tree appears in Sitecore /sitecore/Content node:

2. Double Opt-In prerequisities

EXM installation has all required mail templates for double opt-in predefined (you can find these templates in /sitecore/content/Email/Messages/Service Messages/Self-Service Subscription). The most interesting messages are Subscription Notification and Subscription Confirmation.

Subscription Confirmation – this email template is used for confirmation of double opt-in process and is automatically sent to user when subscribing into newsletter. It also utilizes $link$ token, which is replaced by link “final page” if user clicks on confirmation link. The page which will be used can be configured in Final Confirmation Page field on item /sitecore/content/Email.

Subscription Notification – this email template is used for confirmation of subscription, and it is sent when user confirms subscription by clicking on link in confirmation email.

3. Contact list and mailing campaign

For successful mailing sent via EXM, we need to have Contact List, which will be used as a source of contacts to which emails will be send, and content of email

3.1 Contact list creation

Contact list are created with help of List Manager application in Sitecore.

To create a list, follow these instructions:

Open List Manager application

Create new list by clicking on Create button

Select Empty Contact List

Fill the name of list

And the list is created.

3.2 Mailing campaign creation

Mailing campaign is the “key” functionality offered by EXM. Typically it represents one email sent to set of recipients (represented by contact list).

As soon as campaign is sent, EXM will evaluate campaign statistics, and you cannot send this campaign again.

Why we are creating this campaign now? Because Subscription mechanism used for subscribing recipients works with campaigns, instead of contact list (you need to pass ID of campaign in subscribe function, and this function adds recipient into first contact list used by this Campaign).

To create campaign, follow these steps:

Open EXM application

Click on Create button to create new Mailing Campaign

Select Regular Email Campaign

Select Plain Text Type message

On General step, fill the name of Campaign

On Recipients tab select the list created in step 3.1

On Message step, prepare some content for Mailing (you can skip this step, as this Campaign will be used for recipients subscribing)

On Review step, you can send testing mail to mail entered into box

On Delivery step click on Save button in top right and save campaign.

Switch to Content editor and navigate on item /sitecore/content/Email/Message/year/Month/Day/Name_of_Campaign and write ID of item somewhere on paper. We will use this ID later, when we will develop subscribe submit action.

4. Maillist subscription

So, at this moment, we have configured and prepared EXM to maintain our double opt-in process.

But, we need channel to allow visitors to subscribe to receive data from us.

We have several ways how to do that. We can implement our own form with subscribing logic, or we can utilize Sitecore Forms and use it’s editor to develop form quick and easy and use own Submit form activity to subscribe user.

In this article, I will use Sitecore Forms, but the code used for subscribing we can use on any other variant of subscribing.

Before we will continue, we need to know that subscribing user into mailing requires Sitecore identified contact.

For email subscription, we will use following API call:

IClientApiService.Subscribe(SubscribeMessage subscribeMessage);

1	IClientApiService.Subscribe(SubscribeMessage subscribeMessage);

where SubscribeMessage class is defined by following way:

class SubscribeMessage
{
    public Guid MessageId { get; set; }
    public ContactIdentifier ContactIdentifier { get; set; }
    public bool RequireSubscriptionConfirmation { get; set; }
}

class SubscribeMessage

{

public Guid MessageId { get; set; }

public ContactIdentifier ContactIdentifier { get; set; }

public bool RequireSubscriptionConfirmation { get; set; }

}

MessageId – guid of the mailing. User will be subscribed to first contact list attached to this mailing.

ContactIdentifier – identification of XConnect contact to be subscribed

RequireSubscriptionConfirmation – value indicating whether double opt-in will be used. Set to true to initialize double opt-in process for this subscription.

To identify user, we can use Identify contact submit action in article Sitecore Forms: How to identify Contact? .

I will assume that we already have some form created using Sitecore Forms from Sitecore Forms: How to identify Contact? article.

To subscribe, we need to use following Subscribe to newsletter submit action.

using System;
using System.Collections.Generic;
using System.Linq;
using Sitecore.DependencyInjection;
using Sitecore.EmailCampaign.Cd.Services;
using Sitecore.EmailCampaign.Model.Messaging;
using Sitecore.ExperienceForms.Models;
using Sitecore.ExperienceForms.Processing;
using Sitecore.ExperienceForms.Processing.Actions;
using Sitecore.XConnect;
using Sitecore.XConnect.Client;
using Sitecore.XConnect.Client.Configuration;
using Sitecore.XConnect.Collection.Model;

namespace Sitecore.Demo.SitecoreExtensions.Forms.Actions
{
    /// <summary>
    /// Save action for identifying contact in Sitecore Forms.
    /// </summary>
    public class SubscribeToNewsletter : SubmitActionBase<string>
    {
        /// <summary>
        /// EXM client service.
        /// </summary>
        private readonly IClientApiService clientApiService;

        /// <summary>
        /// Initializes a new instance of the <see cref="SubscribeToNewsletter"/> class.
        /// </summary>
        /// <param name="submitActionData">The submit action data.</param>
        public SubscribeToNewsletter(ISubmitActionData submitActionData) : base(submitActionData)
        {
            this.clientApiService = ServiceLocator.ServiceProvider.GetService(typeof(IClientApiService)) as IClientApiService;
        }

        /// <inheritdoc />
        protected override bool Execute(string data, FormSubmitContext formSubmitContext)
        {
            using (var client = this.CreateClient())
            {
                try
                {
                    var source = "sitedemo";
                    var email = GetFieldByName("Email", formSubmitContext.Fields);
                    var id = GetValue(email);
                    var trackerIdentifier = new IdentifiedContactReference(source, id);
                    var expandOptions = new ContactExpandOptions(CollectionModel.FacetKeys.PersonalInformation, CollectionModel.FacetKeys.EmailAddressList);
                    var contact = client.Get(trackerIdentifier, expandOptions);

                    var subscriptionMessage = new SubscribeMessage() { ContactIdentifier = contact.Identifiers.FirstOrDefault(), RequireSubscriptionConfirmation = true, MessageId = new Guid("{61B088B4-2876-4C19-BBCE-CF58AA30A44F}") };

                    this.clientApiService.Subscribe(subscriptionMessage);

                    Logger.Info("Contact submitting newsletter form was subscribed to newsletter.");

                    return true;
                }
                catch (Exception ex)
                {
                    Logger.LogError(ex.Message, ex + ex.StackTrace);
                    return false;
                }
            }
        }

        /// <summary>
        /// Creates the client.
        /// </summary>
        /// <returns>The <see cref="IXdbContext"/> instance.</returns>
        protected virtual IXdbContext CreateClient()
        {
            return SitecoreXConnectClientConfiguration.GetClient();
        }

        /// <summary>
        /// Parses object data send as parameter to action.
        /// </summary>
        /// <param name="value">Input value.</param>
        /// <param name="target">Target value.</param>
        /// <returns>A value indicating whether conversion was successfull.</returns>
        protected override bool TryParse(string value, out string target)
        {
            target = string.Empty;
            return true;
        }

        /// <summary>
        /// Gets the field by <paramref name="id" />.
        /// </summary>
        /// <param name="name">The field identifier.</param>
        /// <param name="fields">The fields.</param>
        /// <returns>The field with the specified <paramref name="id" />.</returns>
        private static IViewModel GetFieldByName(string name, IList<IViewModel> fields)
        {
            return fields.FirstOrDefault(f => f.Name == name);
        }

        /// <summary>
        /// Gets the <paramref name="field" /> value.
        /// </summary>
        /// <param name="field">The field.</param>
        /// <returns>The field value.</returns>
        private static string GetValue(object field)
        {
            return field?.GetType().GetProperty("Value")?.GetValue(field, null)?.ToString() ?? string.Empty;
        }
    }
}

100

101

102

103

104

105

106

107

108

using System;

using System.Collections.Generic;

using System.Linq;

using Sitecore.DependencyInjection;

using Sitecore.EmailCampaign.Cd.Services;

using Sitecore.EmailCampaign.Model.Messaging;

using Sitecore.ExperienceForms.Models;

using Sitecore.ExperienceForms.Processing;

using Sitecore.ExperienceForms.Processing.Actions;

using Sitecore.XConnect;

using Sitecore.XConnect.Client;

using Sitecore.XConnect.Client.Configuration;

using Sitecore.XConnect.Collection.Model;

namespace Sitecore.Demo.SitecoreExtensions.Forms.Actions

{

/// <summary>

/// Save action for identifying contact in Sitecore Forms.

/// </summary>

public class SubscribeToNewsletter : SubmitActionBase<string>

{

/// <summary>

/// EXM client service.

/// </summary>

private readonly IClientApiService clientApiService;

/// <summary>

/// Initializes a new instance of the <see cref="SubscribeToNewsletter"/> class.

/// </summary>

/// <param name="submitActionData">The submit action data.</param>

public SubscribeToNewsletter(ISubmitActionData submitActionData) : base(submitActionData)

{

this.clientApiService = ServiceLocator.ServiceProvider.GetService(typeof(IClientApiService)) as IClientApiService;

}

/// <inheritdoc />

protected override bool Execute(string data, FormSubmitContext formSubmitContext)

{

using (var client = this.CreateClient())

{

try

{

var source = "sitedemo";

var email = GetFieldByName("Email", formSubmitContext.Fields);

var id = GetValue(email);

var trackerIdentifier = new IdentifiedContactReference(source, id);

var expandOptions = new ContactExpandOptions(CollectionModel.FacetKeys.PersonalInformation, CollectionModel.FacetKeys.EmailAddressList);

var contact = client.Get(trackerIdentifier, expandOptions);

var subscriptionMessage = new SubscribeMessage() { ContactIdentifier = contact.Identifiers.FirstOrDefault(), RequireSubscriptionConfirmation = true, MessageId = new Guid("{61B088B4-2876-4C19-BBCE-CF58AA30A44F}") };

this.clientApiService.Subscribe(subscriptionMessage);

Logger.Info("Contact submitting newsletter form was subscribed to newsletter.");

return true;

}

catch (Exception ex)

{

Logger.LogError(ex.Message, ex + ex.StackTrace);

return false;

}

/// <summary>

/// Creates the client.

/// </summary>

/// <returns>The <see cref="IXdbContext"/> instance.</returns>

protected virtual IXdbContext CreateClient()

{

return SitecoreXConnectClientConfiguration.GetClient();

}

/// <summary>

/// Parses object data send as parameter to action.

/// </summary>

/// <param name="value">Input value.</param>

/// <param name="target">Target value.</param>

/// <returns>A value indicating whether conversion was successfull.</returns>

protected override bool TryParse(string value, out string target)

{

target = string.Empty;

return true;

}

/// <summary>

/// Gets the field by <paramref name="id" />.

/// </summary>

/// <param name="name">The field identifier.</param>

/// <param name="fields">The fields.</param>

/// <returns>The field with the specified <paramref name="id" />.</returns>

private static IViewModel GetFieldByName(string name, IList<IViewModel> fields)

{

return fields.FirstOrDefault(f => f.Name == name);

}

/// <summary>

/// Gets the <paramref name="field" /> value.

/// </summary>

/// <param name="field">The field.</param>

/// <returns>The field value.</returns>

private static string GetValue(object field)

{

return field?.GetType().GetProperty("Value")?.GetValue(field, null)?.ToString() ?? string.Empty;

}

How to customize

On line 43 you should adjust identification source to any string you are using to identify contacts. If you are using this submit action together with Contact Identification Submit Action, this value should be the same with value on line 41 in those submit action.

On line 50, instead of guid provided me there is necessary to provide guid representing campaign you created in chapter 3.

When developed and compiled, register this submit action in Sitecore Forms (steps to register are also noted in referenced article) and attach this action to form AFTER contact identification submit action.

Sitecore Blog

How to configure double opt-in in EXM and Sitecore 9.0.1 using Sitecore Forms

What we will need to do?

1. Configuration of EXM

1.1 SMTP configuration

1.2 EXM configuration

2. Double Opt-In prerequisities

3. Contact list and mailing campaign

3.1 Contact list creation

3.2 Mailing campaign creation

4. Maillist subscription

How to customize

2 thoughts on “How to configure double opt-in in EXM and Sitecore 9.0.1 using Sitecore Forms”

Leave a Reply Cancel reply

The First Czech Sitecore Blog