Link generation and hostname mapping in EXM

Version: 10.4

EXM uses a web request to render the content of email messages and any internal links in the email messages are rendered using the LinkManager class.

Note

The logic for generating URLs in an email message to content items is the same approach that Sitecore uses when rendering pages on a website. In Sitecore, many settings influence how to generate internal links, for example, the site definitions or the configuration of the LinkManager class.

When a recipient clicks a link in an email message, it is critical that the link is an absolute URL that points to the publicly accessible content delivery servers. Therefore, when you send an email message, EXM checks and corrects any links in the email message that are not generated with absolute URLs or otherwise pointing to a content management server.

Note

In situations where, for example, you want to send a test email campaign and direct the test recipients who click a link to a website with content that has not yet been published, you can configure a separate preview hostname in the manager root.

EXM verifies and generates hyperlinks according to the following process that is specified in the modifyHyperlink pipeline:

  • Ignore links that start with #, javascript: or mailto:

  • Determine the current ServerUrl, for example, https://cms.domain.com.

  • If the link is not absolute, prefix the ServerUrl to make it absolute.

  • Check the hostname against the following hostname mappings and if necessary, EXM replaces the hostname, for example, https://preview.domain.com for a test or https://www.domain.com for a dispatch.

    EXM checks the hostnames by using the following hostname mappings:

    • The manager roots generates mappings from the PreviewUrl to the BaseUrl.

    • The mappings created under /sitecore/system/Settings/Email/System/Hostname Mappings in the content tree.

    • The RendererUrl maps to the PreviewUrl or the BaseUrl of the email message's manager root. The RendererUrl is the hostname that EXM should use for rendering the email content and it defaults to the hostname of the current server.

    Note

    This way of mapping hostnames is defined in the Sitecore.EmailExperience.Core.config file, in the HostnameMappingService and HostnameMappingRepository classes. To override this behavior, you can create your own classes that implement the IHostnameMappingService and IHostnameMappingRepository interfaces and then patch the configuration accordingly.

  • Add extra queryString parameters to the link to help identify the message, xDB contact, email address used, target language, and A/B test variant.

  • For dispatch only: Replace the link by the click tracker that defaults to RedirectUrlPage.aspx and add the original URL as a query string parameter.

  • For dispatch only: Encrypt the queryString.

Adding custom hostname mapping

If the default behavior for hostname mapping that is specified in the modifyHyperlink pipeline generates incorrect hostnames in the links, for example, if the link directs the recipients to the content management server, the wrong site, or the wrong language, you can add custom hostname mappings.

As an example, your organization has two sites:

  • Site1

    • Content management: https://cms.site1.com

    • Content delivery: https://www.site1.com

  • Site2

    • Content management: https://cms.site2.com

    • Content delivery: https://www.site2.com

In the example, you create an email campaign in a manager root with the base URL https://www.site1.com. In the email message, you add links to both Site1 and Site2.

By default, for webpages under Site2, the content management server generates links that point to https://cms2.site2.com but EXM cannot determine the correct address for the same page on the content delivery server. To resolve this problem, in the content editor, you can create a hostname mapping item that maps the hostname of the content management server to the equivalent content delivery server.

To create a hostname mapping item:

  • Create a new item under the /sitecore/system/Settings/Email/System/Hostname Mappings folder. Use the Hostname Mapping template (/sitecore/templates/Email Campaign/Global Settings/Hostname Mapping).

    • In the Original field, enter the hostname of the original content management server, for example, https://cms.site2.com/.

    • In the Preview field, enter the equivalent hostname of the preview website. This is optional.

    • In the Public field, enter the equivalent hostname for the content delivery server, for example, https://www.site2.com/.

Content Editor Hostname Mapping section.

Do you have some feedback for us?

If you have suggestions for improving this article,