Email channel management

Email channels are a dedicated medium of communication between you and your audience. An Xperience project may contain multiple email channels, focusing on different content strategies, languages and audience engagement techniques. For example, you can have separate email channels dedicated to marketing and supporting different products or services offered by your company, each with a different different tone and style.

Channels allow for a clean separation of your organization’s emails. Every email channel has its own application in the Xperience administration, where marketers create and send emails. 

The defining property of every email channel is a sending domain, which represents your company or brand, and is used in all sender addresses for the channel’s emails.

Create and configure email channels

1. Open the Channel management application in Xperience.
2. Select New channel.
3. Fill in the channel properties:

   • Channel name – the name of the channel displayed in Xperience.

   • (Optional) Identifiers – specify the code name if you wish to use a code name different than the pre-filled value.

     • Note: Channel code names must be unique across all channels (of any type).

   • Channel type – select Email as the channel type.

   • Content language – the language of all emails in the channel.

   • Sending domain – the domain associated with the channel. This domain is used for the channel’s sender addresses, and must be unique across all email channels.

   • Email service domain – the domain used in various system links in the channel’s emails (click tracking links, the email open tracking pixel, asset URLs, subscription and unsubscription URLs). The specified domain must host an Xperience by Kentico application connected to the database where this email channel is configured. The most common setup is to use the domain of a related website channel. Alternatively, you can use the domain hosting the Xperience application where you manage your emails (if the application is publicly accessible).

     Email service domain format

     If the target application runs under a port different than  80 or with a specific URL path, both must be specified in the domain name. Do not include the URL scheme (http or https).

     Licensing

     Every service domain used by your email channels must have a valid license key. You need to register a separate license key for your email service domain if it does not match a licensed domain of a website channel.

4. Select Save.

The email channel is now ready. If you need to configure an existing channel, open the channel again via the Channel management application and edit the values on the General tab.

After you add a channel, the system automatically creates a new application matching the channel’s name in the Channels category of the administration’s application list. This is the application where users can create and view the channel’s emails.

Set up emails in multiple languages

Each email channel only supports one language (unlike pages in website channels or content items). Therefore, if you wish to send emails in a different language, you need to create a new email channel with a unique Sending domain for each language variant.

Add allowed content types

Every email in Xperience uses a specific content type. The content type defines the fields that users can edit when writing emails.

To create emails under a channel, you need to prepare suitable content types and allow them for the channel:

1. Open the Channel management application in Xperience.
2. Select your email channel.
3. On the Allowed content types tab, Select content types.
4. Select or clear the checkboxes to choose which content types you want to make available in the channel.
5. Select Save.

Add sender addresses

Every email has a sender name and address that recipients see in their inbox. In Xperience, you prepare sender addresses in advance for each email channel. When creating emails, users can choose from a list of the given channel’s sender addresses.

To add a sender addresses for an email channel:

1. Open the Channel management application in Xperience.

2. Select your email channel.

3. On the Sender addresses tab, select Add sender address.

4. Fill in the sender address properties:

   • Sender name – the name of the email sender.
   • Sender email address – the “From” address that recipients see in their inbox. The domain part of all sender addresses must match the sending domain of the email channel. The address must be unique across all senders under the email channel.

5. Select Save.

Configure sending and service domains programmatically

The sending and service domains of your email channels can be configured programmatically via the EmailChannelDomainOptions class using ASP.NET configuration providers. This configuration is prioritized over the channel domain values set via the Xperience administration interface.

For example, when configured via appsettings.json:

{  
  "EmailChannelDomains": {
    "DomainOverrides": {
      "AcmeEmails": {
        "SendingDomain": "mysendingdomain.com",
        "ServiceDomain": "myservicedomain.com"
      }
    }
  },
  ...
}

Where AcmeEmails is the code name of the channel to configure.

using CMS.Websites;

var builder = WebApplication.CreateBuilder(args);

// Apply the configuration from appsettings.json
builder.Services.Configure<EmailChannelDomainOptions>(builder.Configuration.GetSection("EmailChannelDomains"));

For channels not configured via application settings, the values specified via the administration interface are used.

Domains for different application environments

You can use the options pattern to set different domains per environment by introducing corresponding appsettings.environment.json files. The following example uses different sending and service domains when running the project under the Development environment.

{
  "EmailChannelDomains": {
    "DomainOverrides": {
      "AcmeEmails": {
        "SendingDomain": "localtest.com",
        "ServiceDomain": "localhost"
      }
    }
  }
}

Email channels in the SaaS environment

For applications deployed in the SaaS environment, you need to add your channels in Xperience Portal:

1. Open the Channels and Domains → Channels application in Xperience Portal.
2. Select Add channel.
3. Set the channel properties:
   • Display name – enter a name for the channel that will be displayed in Xperience Portal.
   • Code name – copy the exact code name of the email channel from the Channel management application in the Xperience administration.
   • Channel type – Email
4. Select Add channel.

After you add an email channel, the system automatically starts configuring the sending and service domains for the deployed applications. This process may take up to several minutes. You do not need to (and cannot) configure the channel’s domains in the Xperience administration.

Once the domain configuration is complete, the email channel uses automatically generated Default domains. For production environments, you need to add suitable custom domains for the channel.

Manage email channel domains in Xperience Portal

Email channels in Xperience Portal use the following basic domain types:

• Default – a default sending and service domain is generated for every email channel and environment. Default domains are replaced when you add a custom domain.
• Custom – custom domains added for the PROD environment.

and two different kinds of domains:

• Sending domain () – the domain used for the channel’s sender addresses.
  • Must be unique across all email channels.
  • Emails are always sent via Twilio SendGrid. See SendGrid integration for more information.
• Service domain () – the domain name used as the base of various system URLs in the channel’s emails (click tracking links, the email open tracking pixel, asset URLs, subscription and unsubscription URLs).
  • Do not include a URL path, port number or URL scheme in the service domain.
  • If your emails are related to a specific website, we recommend setting the email service domain to the main production domain of the given website channel.

To set custom domains for the PROD environment of an email channel:

1. Open the Channels and Domains → Channels application in Xperience Portal with a Tenant administrator or DevOps Engineer role.

2. Select the Domains () action for the given email channel.

3. Select Add domain.

4. Choose the Domain kind (Email sending domain or Service domain).

5. Enter the chosen Domain name and select Next.

6. Xperience Portal displays DNS settings. Apply these settings with your DNS registrar.

7. After the settings are successfully registered with your DNS registrar, select the checkbox confirming the DNS configuration and select Create. This triggers a DNS validation process.

8. Allow a few minutes for the DNS validation to finish.

   • If the DNS validation fails, double-check your DNS settings, wait a few minutes, and select Validate () to restart the validation. See Revalidate custom domain DNS settings.

When the custom domain’s DNS settings are successfully validated, the domain switches to the Active status and replaces the default domain. Each email channel can only have one Active sending and service domain.

The system then automatically configures the new domain settings for the deployed production application. This process may take up to several minutes. You do not need to (and cannot) configure the channel’s domain in the Xperience administration.

Domain status

You can check the status of a channel’s domains in the Channels and Domains → Channels application in Xperience Portal. Select the Domains () action for a specific channel.

• Active – The domain is active and working. Each email channel can only have one Active sending and service domain. Adding a new custom domain that reaches the Active status replaces the previous Active domain of the given kind.
• DNS validation failed – The DNS records are configured incorrectly, or the configuration has not yet been propagated through the DNS servers. See Revalidate custom domain DNS settings.
• Error – A system configuration issue with the domain. Contact Kentico support.
• Transient error – There was a temporary error while creating, validating, or deleting the domain. To recover from this status, use the Revalidate () action to resubmit the domain.
• Creating – The domain is being created.
• Deleting – The domain is being deleted.

Revalidate custom domain DNS settings

If you add a custom domain for a channel and its DNS validation fails, you need to revalidate the DNS settings in Xperience Portal.

1. Open the Channels and Domains → Channels application in Xperience Portal with a Tenant administrator or DevOps Engineer role.
2. Select the Domains () action for the related channel.
3. Select Revalidate () to restart the domain validation for a domain.
4. Xperience Portal displays DNS settings. Apply these settings with your DNS registrar.
5. After the settings are successfully registered with your DNS registrar, select the checkbox confirming the DNS configuration and select Validate. This triggers a DNS validation process.
6. Allow a few minutes for the DNS validation to finish.
7. Check the domain status.

Your custom domains are now revalidated. If the issues persist, contact Kentico support.