Send E-mail Action to Sitecore 9 Forms

|
Comments
(0)

Sitecore 9 introduces an exciting new Forms System (see official documentation here). However, it lacks a feature that is widely used in most forms: a Send E-mail Action. WFFM does have an OOTB action, so this is really an important feature to implement.

 

Nish Tech’s Send E-mail Action

To fill this gap, Nish Tech implemented a custom Send E-mail Action for Sitecore 9 Forms. This action sends e-mails using the “Sitecore.MainUtil.SendMail” method, which uses the standard SMTP settings of Sitecore for message dispatching.

 

Download Module
For download and installation instructions 
check our Git Repository

The issues with the OOTB Action “Send E-mail Campaign Message”

Sitecore 9.0 Update 1 does bring a Send E-mail Campaign Action OOTB, which will use the EXM - Email Experience Manager to submit messages (see this article on how to use it). However, some issues you will face if you try to use this action are:

  1. EXM can only send e-mails to a known contact. To submit e-mails, the current user should be registered as a contact in Sitecore, which will require custom code;

  2. There is no OOTB way to add data from the form into the E-mail Message. To be able to replace data at the E-mail Message, you need no register all this data into the contact;

  3. You can only submit e-mail messages to the registered contact, which is a big limitation. Say you want to send e-mails to a static e-mail - such as “signup@mysite.com” - you will need some custom code to fake a contact and send the message.

 

How the action works

You build your Form normally, then you select a Submit button. Now you select a Send E-mail Action:

Select Send Email Action

When you select this Action, or when you click on the Edit Icon, you will be presented with a window where you can select an E-mail Template.

Select EMail Template

You save your Form and publish it, and that’s it: your form will now be able to submit e-mails using the selected E-mail template.

 

E-mail Templates

E-mail Templates are models you will use to configure the e-mails sent by the action. Below you have an example of E-mail Template with some content input.

Helper texts are setup in these fields with some self-explanatory text to help comprehension. 

Email Template Fields

 

Repository of E-mail Templates

By default, the repository for them is at /sitecore/system/Settings/Forms/E-mail Templates, but you can MOVE this folder to anywhere in the Database. 

The reference to it is setup to this Item ID at core:/sitecore/client/Applications/FormsBuilder/Components/Layouts/Actions/SendEmail/PageSettings/ItemTreeView at the field “StaticData”
 
If you want to use another folder item with a different ID instead of moving the original folder, you have to adjust the item above to point to your new ID.
 

Keyword Replacement

As you can see in the screenshot above, you can use keywords - such as {Subject} and {From} - at all fields of an E-mail Template. At the moment of submission, these keywords will be replaced with the content input by the user at the form.The keyword is composed of the Field Name between brackets. 

You can setup a field name at the Form Designer, selecting your individual field and editing “Field name”. So with the following field:

Field Names

You can use the {From} keyword to get the value input by the user in this field into the e-mail message. 

SMTP Server

The Send E-mail Action uses MainUtil.SendMail() method, which will use an SMTP server to submit e-mails. Setup your SMTP server by editing /App_Config/Include/smtp.config or use your own patch to patch the following settings:


  •  

Default values will use localhost a port 25, which is good for development with a tool such as SMTP4DEV. With that tool you will have a fake local SMTP server that does not actually submits a message, but offers a way to verify if Sitecore is sending to SMTP servers correctly, as well as verify the content of the submitted e-mail.

SMTP4Dev

 

Dictionary Items

Dictionary items used at this Action are stored under the Default Global Dictionary of Sitecore, at path /sitecore/system/Dictionary/Forms/Actions/SendMail
 
Dictionary Items

 You can move these Dictionary Entries to any other Dictionary if you want, and also modify their Texts. Just please make sure you don't change their Keys, so the code can find them:

Dictionary Item Key

Error Logging

Errors in the e-mail submission will be logged, along with their Exceptions, to Sitecore log files. The following pattern will be used:

[SendMail Action] Error sending e-mail based on template {ID}

 Example of error logging:

4208 09:25:47 ERROR [SendMail Action] Error sending e-mail based on template 342bee8b-9439-4e05-b91c-500dd3f2a6b2
Exception: System.InvalidOperationException
Message: The SMTP host was not specified.
Source: System
   at System.Net.Mail.SmtpClient.CheckHostAndPort()
   at System.Net.Mail.SmtpClient.Send(MailMessage message)
   at Sitecore.MainUtil.SendMail(MailMessage message

Test Send E-mail Form

The module comes with an optional package that provides a Test Send E-mail Form you can use, to quickly check if the Submit E-mail Action is working.

Test Send Mail Form

If you installed the optional package and want to use the Test Send E-mail Form, make sure to add an MVC Form Rendering (/sitecore/layout/Renderings/System/Forms/Mvc Form) to a placeholder in a page. After that, you can Preview the item with the Test Form and submit to have the E-mail message being sent. 

 

Implementation

Our Submit Action has the following setup:

Send Mail Action Settings

The main action logic happens at the SendMailAction.cs file, at the Execute method. The code has comments that will help understand what it does, so anyone can follow.

Important methods:

  • Execute - Main Execute method responsible for triggering the e-mail submission
  • ReplaceKeywords - Will parse a string replacing all keywords with content coming from the Form. This method is called for each field of the E-mail Template

The Action Editor

The window that allows selection of E-mail Templates, which is located at core:/sitecore/client/Applications/FormsBuilder/Components/Layouts/Actions/SendEmail, is implemented with SPEAK. This is actually a duplication of native RedirectToPage with some differences:
 
  1. In Layout Details, updated the PageCode component to point to our .js file

    Send Mail Editor Changes
    This .js file is also a copy of the Redirect.js file without modifications. I thought it would be better to have a specific file to respect semantics and we don’t have to rely on Sitecore’s code that can change in the future

  2. Modified /PageSettings/HeaderSubtitle - Text field into “Select the E-mail template that you want to use for submission.” 

  3. Modified /PageSettings/HeaderTitle - Text field into “Select E-mail Template”

  4. Modified /PageSettings/ItemTreeView - StaticData field into the ID of or E-mail Template folder
     

And that’s it, hope you enjoy the new Sitecore 9 Forms Send E-mail Action!