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.
See Email queue configuration for information about the email queue processing and the available configuration options.
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.
- Open your Xperience project in Visual Studio and edit the Program.cs file.
- 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.
- For each method, configure the SMTP connection using the
Server
property of the method’sSmtpOptions
parameter. The underlyingSmtpServer
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.
- (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 isUTF8
.TransferEncoding
– sets the System.Net.Mime.TransferEncoding used when sending emails. The default isBase64
.
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 };
});
SMTP server options in configuration files
You can use ASP.NET Core configuration providers to separate the SMTP server details from the application’s startup code to a configuration source (e.g., the default appsettings.json file). This allows you to make runtime changes to the SMTP server configuration without needing to adjust and redeploy the code or restart the application (depending on the specifics of your selected configuration source).
For system email SMTP configurations added via AddXperienceSystemSmtp
, call the ConfigureSystemSmtpOptions
method.
For email channel-specific SMTP configurations added via AddXperienceChannelSmtp
, call the .NET Configure method. The name of the options instance must match the code name of the email channel.
// 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.
SMTP connection restrictions on Microsoft Azure
If your application is hosted on Microsoft Azure, emails may fail to send from Xperience due to SMTP connection restrictions on the side of Azure.
To resolve such issues, read and follow the recommendations in the Troubleshoot outbound SMTP connectivity problems in Azure article.
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 service plans.
Enable managed SendGrid integration
Perform the following steps before deploying your project to the SaaS environment:
If you are using the provided .NET project templates (kentico-xperience-mvc
or kentico-xperience-sample-mvc
), the required method is called by default for the QA, UAT, and PROD environments.
Open your Xperience project in Visual Studio and edit the Program.cs file.
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.
C#Enabling SendGrid integration for QA, UAT and production deployment environmentsusing 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.
- Set up one or more SendGrid accounts with an Email API plan.
- Open your Xperience project in Visual Studio.
- Install the Kentico.Xperience.SendGrid NuGet package.
- Edit your application’s Program.cs file.
- 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.
- For each method, set your SendGrid API Key into the
ApiKey
property of theSendGridClientOptions
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 theConfigureSystemSendGridClientOptions
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.
- For system email SendGrid configurations added via
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
Configuration of sender email addresses as described below is only supported for self-managed environments.
For applications deployed in the SaaS environment, the sender domain for system emails is fixed, and domains for email channels need to be configured in Xperience Portal (see Email channels in the SaaS environment).
The system allows you to configure the sender (From) email addresses used by various system features. See the following table for details:
Supported email address formats
The system supports all email address formats allowed by the System.Net.Mail.MailAddress class. For example:
user@host
"display name" <user@host>
Feature | Default from address | Description |
| Custom emails for the form autoresponder. Sent automatically to every user who submits the form. The sender can be set in the code that defines each custom email. If the sender is not set directly, the default address reflects the global sending domain for system emails. | |
| Xperience administration user invitation emails (RegistrationEmailMessageProvider) and user password reset emails (ResetPasswordEmailMessageProvider). The sender reflects the global sending domain for system emails if only the local part of the address is set. | |
none | Email created within an email channel use the sender configuration of the given channel. |
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:
- Open your Xperience project in Visual Studio and edit the Program.cs file.
- Call the
Configure<EmailQueueOptions>
method forIServiceCollection
when building the web application (usingWebApplicationBuilder
). - 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:
Open the Email queue application in the Xperience administration.
On the Email queue tab, select Send test email.
Fill in the email fields.
When using SendGrid, use a verified domain address.Select Send test email.
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:
- Open the email channel application in Xperience.
- Create a testing email.
- Expand the action menu in the upper right of the view and select Send draft.
- Send a draft email to an address where you can check the email’s delivery.
External mailout
External mailout configuration is only supported for self-managed environments.
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:
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
)
Call the
Configure<EmailServiceOptions>
method forIServiceCollection
when building the web application (usingWebApplicationBuilder
).Set the
MailOutIsExternal
property ofEmailServiceOptions
totrue
.C#Program.csusing 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.
- 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.
- By default, this is determined by the
- 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.