Sending E-mail using Ucommerce

Any good e-commerce solution lets the store owner stay in contact with customers. One of the most well established ways of doing this is using the tried and true e-mail. As with any part in Ucommerce, you may choose to use the default built-in way of sending emails, or you can connect to any 3rd-party email provider of your choice.

In this article we'll focus on the default way of sending emails.

Steps Involved in Sending E-mail

To send e-mail you’ll need to:

• Add the types of e-mails you’ll be working with in Ucommerce
• Set up a profile for your store to use
• Configure the actual e-mails and their templates
• Configure your store to use that profile
• Configure the smtp settings
• And finally trigger the e-mail
• Custom Email Service

Adding a New E-mail Type

Ucommerce employs the notion of E-mail Types, which are your basic kinds of e-mails that you’re working with. Out of the box a single type is supplied called “order confirmation”, but you can configure your own types as needed.

Other types might include “Welcome new customer”, “Thank you signing up to the newsletter”, or more business-like type e-mails like “Your items are shipping” or “Invoice”.

To set up a new e-mail type you need to go to Settings => E-mail => Types, right click Types, and click Create.

Add an E-mail Profile

“What’s an E-mail Profile and why do we need one?”, you might ask.

Ucommerce supports multiple stores in a single installation and these stores might vary wildly in look and feel so we needed a way to set up multiple instances of the same e-mails on a per store basis to match that same look and feel from store on e-mails across different stores, e.g. an invoice for Store A might have a different look and feel than an invoice for Store B. Thus the notion of an E-mail Profile was introduced to group e-mail instances together for use on individual stores.

As you can see from the screenshot below the profile has an e-mail instance associated per e-mail type created previously. The difference being that for an E-mail Profile we’re dealing with an actual e-mail while an E-mail Type is a placeholder. The system basically ensures that we’re dealing with the same e-mail setup across all stores and makes it easier to deal with in code.

The process of creating a new profile is the same as you just used to create an E-mail Type.

Create the E-mail Content

Email content in Ucommerce is created as a regular (hidden) page within the CMS. For each type of email you're interested in sending, there'll be a corresponding page in the CMS. The CMS will then be requested for the particular page, and the email content is scraped via an internal http request. Typically you'll have the context needed as querystring parameters within the page request itself. This allows you to use your favorite tech stack (SPA or MVC) to render the content as a regular page. Each e-mail is language enabled so if you need multiple language variations of your e-mail you can set up a content node for each language you wish to support.

In each template you're typically interested in sending an email associated with an order. Ucommerce will add the OrderGuid parameter and you can then use the following code snippet to load the order and render the content needed.

    string orderGuidParameterFromQueryString = System.Web.HttpContext.Current.Request.QueryString["OrderGuid"];
    transactionLibrary.GetPurchaseOrder(Guid.Parse(orderGuidParameterFromQueryString));
    
    

Configure Contents of E-mail

Going back to Ucommerce you need to specify which content node Ucommerce is to use when generating the e-mail.

First you’ll set up the basics of the e-mail such as the name the e-mail is coming from and sender address and optionally whether the e-mail is to CC or BCC’d to anyone, e.g. stores owners like to get an e-mail notification when new orders roll in and this is the perfect use case for CC and BCC.

Next up you’ll configure the multilingual pieces of the e-mail like the subject and the contents of the e-mail, which you set up in a earlier step.

Select the template in the CMS using the content picker. Please note that this might be any content node; OrderConfirmation is used only as an example.

You can specify dynamic subjects of your e-mails, which are populated by the e-mail parameters sent to the e-mail service. To do this you use the e-mail parameters surrounded "{}", so to use the "ordernumber" parameter you specify "{ordernumber}" in the subject line.

You can specify additional parameters for the EmailService when calling it from .NET. This is covered in the next section.

Configure Your Store to use an E-mail Profile

Once you’re happy with the e-mails in your installation you’re ready to tell your store to use those e-mails. To do so go to Product Catalog => and select your E-mail Profile.

With this step completed Ucommerce will know which e-mail and template to select when you ask it to send a particular e-mail type in a given store. More on that in the next step.

Configure the SMTP Settings

Once you are ready to send out emails you need to configure the SMTP settings, which are standard SMTP in .NET. Ucommerce uses the standard smtp client to send emails, so once they are properly configured emails should start flying out. The xml configuration below shows an example of how it should be in web.config. Most installations will have the SMTP settings there already.

    
        <configuration>
             <system.net>
                    <mailSettings>
                        <smtp from="[email protected]">
                            <network host="smtp.gmail.com" 
                             port="587" 
                             userName="[email protected]" 
                             password="yourpassword" 
                             enableSsl="true"/>
                        </smtp>
                    </mailSettings>
            </system.net>
        </configuration>
    

Custom Email Service

If you wish to create a custom email service you can implement the interface Ucommerce.Transactions.IEmailService

This allows you to replace all emails going out from a custom implementation, like integrations with Sendgrid or similar services.

The service will automatically be called in the checkout pipeline once the order completes.

IEmailService

Ucommerce.Transactions.IEmailService

Description

Sends e-mail by requesting the configured template.

Methods

Send

• Description
  Sends an e-mail based on specified EmailProfile.
• Arguments
  • Ucommerce.Infrastructure.Globalization.ILocalizationContext localizationContext: Localization context to use for create culture specific e-mails.
  • Ucommerce.EntitiesV2.EmailProfile profile: The profile.
  • string emailTypeName: Name of the email type.
  • MailAddress to: To.
  • IDictionary<string, string> templateParameters: Dictionary containing template paremeter keys and their values.
• Return type string
  

Implementation

See an example of how to grab the order that you need to send an email with.

    using System;
    using System.Collections.Generic;
    using System.Net.Mail;
    using Ucommerce.Api;
    using Ucommerce.EntitiesV2;
    using Ucommerce.Infrastructure.Globalization;
    
    namespace UcommerceCodeSamples.TransactionFoundation
    {
        //example email service
        public class EmailService : Ucommerce.Transactions.IEmailService
        {
            private readonly ITransactionLibrary _transactionLibrary;
    
            public EmailService(ITransactionLibrary transactionLibrary)
            {
                _transactionLibrary = transactionLibrary;
            }
            
            /// <summary>
            /// Sends the email
            /// </summary>
            /// <param name="localizationContext">Contains the current language email should be send out in</param>
            /// <param name="profile">The profile as configured on the current store</param>
            /// <param name="emailTypeName">The type of email to send e.g order confirmation or cancellation.</param>
            /// <param name="to">The reciever e.g the customer on the order</param>
            /// <param name="templateParameters">dynamic properties that will contain order information.</param>
            /// <returns></returns>
            public string Send(ILocalizationContext localizationContext, EmailProfile profile, string emailTypeName, MailAddress to,
                IDictionary<string, string> templateParameters)
            {
                //grab order data
                Ucommerce.EntitiesV2.PurchaseOrder order = _transactionLibrary.GetPurchaseOrder(Guid.Parse(templateParameters["orderGuid"]));
    
                //Send the email :-)
                
                return string.Empty;
            }
        }
    }

Configuration

All there's left to do, is finding and replacing the email component. Here you'll find the default registration for the email service.

    
    		<component
    			id="EmailService"
    			service="UCommerce.Transactions.IEmailService, UCommerce"
    			type="UCommerce.Transactions.EmailService, UCommerce"/>
    

If you are unsure how to register your email service with the information above, you can read how to register custom components to learn more.

Wrap Up

The process of sending e-mail with Ucommerce does require a couple of steps to get going, however, in return you get the full power of the CMS to fully style your e-mails thus avoiding to have to learn some arcane templating system.

In addition you can even take advantage of some more advanced macros within Ucommerce. Think of the value of sending out your order confirmation e-mail, not only with the details of the order, but with added information about related items to each item bought or special offers tailored to the customer.

This is the value of having the CMS and Ucommerce handle your store e-mails.