Email configuration

Some Xperience by Kentico features utilize emails, for example, digital marketing emails or when resetting a user password.

To allow Xperience to send emails, you need to set up one or more of the following options:

• an external SMTP server
• SendGrid integration (the only option supported when deploying to the SaaS environment)
• a custom email client that utilizes a different third-party mailout service (e.g., MailChimp)

Xperience then processes sent emails with an email queue stored in the database and relays the emails to a designated email server. To manage an email queue from the Xperience administration – monitor the email queue, resend failed emails, etc. – use the Email queue application.

If your project needs to handle a very large number of emails, you can offload the email queue processing from the main web application. See External mailout.

SMTP servers

Use the following process to connect external SMTP servers to your Xperience application. You can configure the SMTP settings separately for individual email channels, as well as system emails that do not belong under a specific channel (e.g., user registration, password reset emails). Depending on your preferences and project requirements, you can use different SMTP servers, share the same server, or combine SMTP servers with SendGrid accounts.

1. Open your Xperience project in Visual Studio and edit the Program.cs file.
2. Call one or more of the following methods for IServiceCollection when building the web application:
   • AddXperienceSystemSmtp – SMTP configuration for system emails that do not belong under a specific email channel.
   • AddXperienceChannelSmtp – SMTP configuration for a specific email channel. Specify the code name of the email channel as the method’s parameter.
   • AddXperienceSmtp – fallback SMTP configuration for system emails and all email channels without their own dedicated configuration.
3. For each method, configure the SMTP connection using the Server property of the method’s SmtpOptions parameter. The underlying SmtpServer type provides the following properties:
   • Host – the hostname of the SMTP server (domain name or IP address). Enter localhost to use a server provided by your local machine.
   • Port – the port number used by the server (typically 587).
   • UserName – if the server requires authentication, specify the user name.
   • Password – if the server requires authentication, specify the password for the user name.
4. (Optional) Set the encoding properties of the SmtpOptions parameter:
   • Encoding – sets the System.Text.Encoding applied to the subject and body of sent emails. The default is UTF8.
   • TransferEncoding – sets the System.Net.Mime.TransferEncoding used when sending emails. The default is Base64.

using System.Net.Mime;
using System.Text;

using CMS.EmailEngine;

...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

...

// Configures email sending using an SMTP server for system emails
builder.Services.AddXperienceSystemSmtp(options =>
{
    options.Server = new SmtpServer { Host = "smtp.server1.com", Port = 587 };
    options.Encoding = Encoding.UTF8;
    options.TransferEncoding = TransferEncoding.QuotedPrintable;
});
// Configures email sending using an SMTP server for the 'AcmeEmailChannel' email channel
builder.Services.AddXperienceChannelSmtp("AcmeEmailChannel", options =>
{
    options.Server = new SmtpServer { Host = "smtp.server2.com", Port = 587 };
});

// Loads the SmtpOptions configuration from configuration file sections
builder.Services.ConfigureSystemSmtpOptions(builder.Configuration.GetSection("SystemSmtpOptions"));
builder.Services.Configure<SmtpOptions>("AcmeEmailChannel", builder.Configuration.GetSection("AcmeSmtpOptions"));

{
   "SystemSmtpOptions": {
    "Server" : {
      "Host": "smtp.server1.com",
      "Port": 587
    }
  }, 
  "AcmeSmtpOptions": {
    "Server" : {
      "Host": "smtp.server2.com",
      "Port": 587
    }
  },
  ...
}

The system now relays emails to the connected SMTP servers. You can set sender addresses individually for each Xperience feature that sends emails, see Configurable sender email addresses.

To test whether your SMTP servers are correctly configured, see Test email sending. To monitor emails ready for mailout, use the Email queue application in the Xperience administration.

Bounced email tracking with SMTP servers

If you send emails using an SMTP server, and wish to track bounced emails and email delivery rates, you need to additionally configure a POP3 connection to a dedicated bounce mailbox. For more information, see Set up email tracking.

SendGrid integration

Xperience provides a client for sending email using the Twilio SendGrid email platform.

When deploying to the SaaS environment, Xperience provides the required SendGrid accounts and configuration – see managed SendGrid integration.

For self-managed Xperience deployments, you can use a self-managed SendGrid instance.

Managed SendGrid integration

Xperience applications deployed to the SaaS environment integrate Twilio SendGrid for sending emails. Kentico manages the SendGrid accounts with the required API keys and configuration as part of all project tiers.

Enable managed SendGrid integration

Perform the following steps before deploying your project to the SaaS environment:

1. Open your Xperience project in Visual Studio and edit the Program.cs file.

2. Call WebApplicationBuilder.Services.AddXperienceCloudSendGrid when building the web application. Use environment identification extension methods to enable SendGrid only for selected environments.

   SendGrid does not work in the local development environment. Use other email services for local development, for example, Papercut SMTP server. See SMTP servers on how to connect the Xperience application with an external SMTP server.

   Enabling SendGrid integration for QA, UAT and production deployment environments

   Copy

   
   
    using Kentico.Xperience.Cloud;
   
    ...
   
    WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
   
    ...
   
    if (builder.Environment.IsQa() || builder.Environment.IsUat() || builder.Environment.IsProduction())
    {
        builder.Services.AddXperienceCloudSendGrid(builder.Configuration);
    }
   
    

After you deploy your application to the SaaS environment, the system relays emails to SendGrid. Emails are considered as successfully sent when SendGrid accepts them. The actual delivery is not guaranteed by Xperience and relies on SendGrid. 

The sender addresses of emails use the following domains:

• System emails (e.g., user registration, password reset) – always use a default sender domain in format: <environment>-<project_name>.xperience-sites.com
• Email channels – initially use an automatically generated default domain, but you can configure your own custom domains in Xperience Portal. See Email channels in the SaaS environment.

Once your configuration is complete, you can:

• Test whether the integration is correctly configured.
• Monitor emails using the Email queue application in the Xperience administration.

Self-managed SendGrid integration

Use the following process to set up SendGrid integration for your self-managed Xperience application. You can configure the SendGrid settings separately for individual email channels, as well as system emails that do not belong under a specific channel (e.g., user registration, password reset emails). Depending on your preferences and project requirements, you can use different SendGrid accounts, share the same account, or combine SendGrid with other SMTP servers.

1. Set up one or more SendGrid accounts with an Email API plan.
2. Open your Xperience project in Visual Studio.
3. Install the Kentico.Xperience.SendGrid NuGet package.
4. Edit your application’s Program.cs file.
5. Call one or more of the following methods for IServiceCollection when building the web application:
   • AddXperienceSystemSendGrid – SendGrid configuration for system emails that do not belong under a specific email channel.
   • AddXperienceChannelSendGrid – SendGrid configuration for a specific email channel. Specify the code name of the email channel as the method’s parameter.
   • AddXperienceSendGrid – fallback SendGrid configuration for system emails and all email channels without their own dedicated configuration.
6. For each method, set your SendGrid API Key into the ApiKey property of the SendGridClientOptions parameter.
   • The SendGrid API Key must have the Full Access type and permissions.
   • You can use ASP.NET Core configuration providers to load the SendGrid API key from a configuration source, such as the default appSettings.json file or Azure Key Vault.
     • For system email SendGrid configurations added via AddXperienceSystemSendGrid, call the ConfigureSystemSendGridClientOptions method.
     • For email channel-specific SendGrid configurations added via AddXperienceChannelSendGrid, call the .NET Configure method. The name of the options instance must match the code name of the email channel.

using CMS.EmailEngine;
using Kentico.Xperience.SendGrid;

using SendGrid;

...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

...

// Configures email sending via SendGrid for system emails
builder.Services.AddXperienceSystemSendGrid();
// Configures email sending via SendGrid for the 'AcmeEmailChannel' email channel
builder.Services.AddXperienceChannelSendGrid("AcmeEmailChannel");

// Loads the SendGrid API keys from configuration file sections
builder.Services.ConfigureSystemSendGridClientOptions(builder.Configuration.GetSection("SystemSendGridClientOptions"));
builder.Services.Configure<SendGridClientOptions>("AcmeEmailChannel", builder.Configuration.GetSection("AcmeSendGridClientOptions")); 

{
  "SystemSendGridClientOptions": {
    "ApiKey" : "..."
  }, 
  "AcmeSendGridClientOptions": {
    "ApiKey" : "..." 
  },
  ...
}

The system now relays emails to the specified SendGrid instances. The system consider emails successfully sent when SendGrid accepts them. The actual delivery is not guaranteed by Xperience and relies on SendGrid.

To learn how to set email sender addresses suitable for your SendGrid account, configure individual Xperience features that send emails – see Configurable sender email addresses.

You can now test the email server configuration, and monitor emails using the Email queue application in the Xperience administration.

Configurable sender email addresses

The system allows you to configure the sender (From) email addresses used by various system features. See the following table for details:

Global sending domain for system emails

You can configure the sending domain for all system emails that are not created under a specific email channel (e.g., user registration, password reset emails) via the SystemEmailOptions class.

The specified domain is used when sending system emails if only the local part of the sender address is set (e.g., via SenderAddress in the email options of user invitation and password reset emails).

For example:

{
  "SystemEmailOptions": {
    "SendingDomain": "localhost.com"
  }
}

{
  "SystemEmailOptions": {
    "SendingDomain": "maindomain.com"
  }
}

var builder = WebApplication.CreateBuilder(args);

...

builder.Services.Configure<SystemEmailOptions>(builder.Configuration.GetSection("SystemEmailOptions"));

Email queue configuration

Emails created by the Xperience application are initially placed into an email queue and stored in the database. The queue reduces the risk of losing emails due to errors, allows manual resending, and can also be used to archive sent emails. Users can work with the email queue in the Email queue application of the Xperience administration. After you configure one or more email clients (SMTP server or SendGrid integration), the system starts processing emails from the queue.

Xperience runs an ongoing process that automatically manages the email queue:

• The process checks the queue for new emails at regular intervals.
• New emails in the queue are loaded in pre-defined batches and relayed to the configured email client.
• The process continues loading and sending batches until all items in the queue are mailed out.
• By default, successfully sent emails are deleted from the queue. You can configure archiving of successfully sent emails for a specific number of days.
• If delivery to the email client fails, the email remains in the queue until it is handled manually – either deleted or successfully re-sent later.

You can adjust the email queue configuration by changing the following options:

1. Open your Xperience project in Visual Studio and edit the Program.cs file.
2. Call the Configure<EmailQueueOptions> method for IServiceCollection when building the web application (using WebApplicationBuilder).
3. The EmailQueueOptions type provides the following properties:
   • ArchiveDuration – sets the number of days for which successfully sent emails are archived. The default value is 0, which completely disables archiving. Archived emails can be viewed on the Sent emails tab in the Xperience Email queue application.
   • BatchSize – sets the number of emails loaded from the email queue in a single batch. The default value is 100. You can adjust the batch size to optimize email sending performance based on the parameters of your web server and database.
   • LoadInterval – sets the interval between checks for new emails to be sent from the queue. The value is in milliseconds and the default is 60000 (one minute).

using CMS.EmailEngine;

...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

...

// Configures how the system processes the email queue
builder.Services.Configure<EmailQueueOptions>(options =>
{
    options.ArchiveDuration = 5;
    options.BatchSize = 500;
    options.LoadInterval = 30000;
});

Test email sending

If you wish to test or debug email sending, we recommend setting up a local SMTP client, such as Papercut SMTP. To verify that email sending from Xperience works correctly, send a test email.

To test the email client configured for system emails:

1. Open the Email queue application in the Xperience administration.

2. On the Email queue tab, select Send test email.

3. Fill in the email fields.

   When using SendGrid, use a verified domain address.

4. Select Send test email.

5. Check the recipient’s mailbox (or your virtual email viewer).

These test emails bypass the queue and are sent directly to the currently configured system email client.

To test the email client configured for individual email channels:

1. Open the email channel application in Xperience.
2. Create a testing email.
3. Expand the action menu in the upper right of the view and select Send draft.
4. Send a draft email to an address where you can check the email’s delivery.

External mailout

If your project needs to handle a very large number of emails, you may wish to offload email sending away from your main Xperience web application. This avoids potential performance impacts of email sending on the live site.

Main web application

To set up your main Xperience web application (live site) for external mailout:

1. Open the application’s Program.cs file and remove any configuration related to email sending:

   • Email client registration (e.g., SMTP server or SendGrid)
   • Email queue configuration (EmailQueueOptions)

2. Call the Configure<EmailServiceOptions> method for IServiceCollection when building the web application (using WebApplicationBuilder).

3. Set the MailOutIsExternal property of EmailServiceOptions to true.

   Program.cs

   Copy

   
   
    using CMS.EmailEngine;
   
    ...
   
    WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
   
    ...
   
    builder.Services.Configure<EmailServiceOptions>(options =>
    {
        options.MailoutIsExternal = true;
    });
   
    

The application now only adds emails to the queue. Loading of mails from the queue and the mailing itself needs to be handled by a separate application.

With the MailOutIsExternal property enabled, parts of the Xperience administration that rely on email sending remain active, even though the application itself does not have an email client configured. In this scenario, it is not possible to send test emails from the Xperience Email queue application (test emails bypass the queue, so they cannot be processed by an external mailout application).

Mailout application

External mailout can be handled either by a separate instance of Xperience, or a custom application that uses the Xperience API externally.

1. Ensure that the mailout application connects to the same database as your main Xperience web application.
   • By default, this is determined by the CMSConnectionString in the appsettings.json configuration file.
2. In the application’s startup class, add any required email configuration:
   • Email client registration (e.g., SMTP server or SendGrid)
   • Email queue configuration (EmailQueueOptions)

The mailout application now processes the email queue, which is shared with your main web application.