Configure the EXM retryers

Abstract

Overview of the retryers used by EXM and how to configure them.

EXM uses three retryers, based on the transient fault handling framework. You can read more about transient fault handling in this documentation from Microsoft. The three EXM retryers in Sitecore are:

  • The EmailCampaign.EDS.Core.Net.Smtp.Send.Retryer (referred to as the Send retryer), which EXM uses to send messages over SMTP.

  • The EmailCampaign.EDS.Core.Net.Smtp.ValidateConnection.Retryer, which EXM uses to get and validate an SMTP connection from the connections pool.

  • The EmailCampaign.XConnect.Conflict.Retryer (referred to as the xConnect conflict retryer), which EXM uses to retry a method if there is a conflict with xConnect.

The retryers have default values that you can configure while configuring EXM. You can:

  • Configure the exponential backoff retry strategy.

  • Convert the Send retryer to a fixed interval retry behavior.

  • Add specific SMTP-related transient fault codes to the Send retryer.

In the Sitecore.EDS.Core.config file, the following is the configuration code for the first two EXM retryers:

<TransientFaultHandling>
    <Retryers>
        <!-- Retryer to send messages over SMTP. -->
        <EDS.Core.Net.Smtp.Send.Retryer>
            <Type>Sitecore.EDS.Core.TransientFaultHandling.RetryerFactories.SmtpSendExponentialRetryerFactory, Sitecore.EDS.Core</Type>
            <!-- <Type>Sitecore.EDS.Core.TransientFaultHandling.RetryerFactories.SmtpSendFixedRetryerFactory, Sitecore.EDS.Core</Type> -->
            <Options>
                <ExponentialRetry>
                    <MaxAttempts>10</MaxAttempts>
                    <MinBackoff>00:00:01</MinBackoff>
                    <MaxBackoff>00:00:30</MaxBackoff>
                    <DeltaBackoff>00:00:10</DeltaBackoff>
                </ExponentialRetry>
                <!--
                <FixedRetry>
                    <RetryCount>3</RetryCount>
                    <RetryInterval>00:00:01</RetryInterval>
                    <FirstFastRetry>false</FirstFastRetry>
                </FixedRetry>
                -->
                <TransientSmtpErrorCodes>
                    <ServiceIsNotAvailable>421</ServiceIsNotAvailable>
                </TransientSmtpErrorCodes>
            </Options>
        </EDS.Core.Net.Smtp.Send.Retryer>
        <!-- Retryer to validate SMTP connection. -->
        <EDS.Core.Net.Smtp.ValidateConnection.Retryer>
            <Type>Sitecore.EDS.Core.TransientFaultHandling.RetryerFactories.SmtpValidateFixedRetryerFactory, Sitecore.EDS.Core</Type>
            <Options>
                <FixedRetry>
                    <RetryCount>3</RetryCount>
                    <RetryInterval>00:00:01</RetryInterval>
                    <FirstFastRetry>false</FirstFastRetry>
                </FixedRetry>
            </Options>
        </EDS.Core.Net.Smtp.ValidateConnection.Retryer>
    </Retryers>
</TransientFaultHandling>

By default, the Send retryer uses an exponential backoff retry behavior, which means that repeated retries are spaced out at random intervals. For more information about exponential backoff strategies, see this article on Wikipedia.

To configure the exponential backoff strategy:

  • In the <ExponentialRetry> section of the Send retryer, configure the following values:

Setting

Default

Description

MaxAttempts

10

Specifies the amount of retry attempts for transient exceptions. Once it hits this amount, the retryer defines the target service as unavailable.

MinBackoff

00:00:01

The minimum time period between retry attempts.

MaxBackoff

00:00:30

The maximum time period between retry attempts.

DeltaBackoff

00:00:10

The delta backoff interval between retries.

EXM supports the option to have retries in fixed intervals instead of the default exponential behavior.

To convert to an interval retry behavior:

  1. In the code for the Send retryer, find the <ExponentialRetry> section, and comment that out with the comment indicators <!--and -->.

  2. Find the <FixedRetry section, and un-comment it by removing the comment indicators <!-- and -->.

In the <ExponentialRetry> section of the Send retryer, you can configure the following values:

Setting

Default

Description

RetryCount

3

Specifies the maximum amount of retries for transient exceptions.

RetryInterval

00:00:01

The fixed time interval between retries.

The <TransientSmtpErrorCodes> section specifies which SMTP-specific transient faults the EmailCampaign.EDS.Core.Net.Smtp.Send.Retryer retryer checks for. By default, the retryer always checks for the fault code 421, which indicates that the recipient service is not available. To make the retryer more specific in its checks, you can add additional fault codes to this section.

To add specific fault codes:

  1. In the configuration code, find the <TransientSmtpErrorCodes> section.

  2. Add a new line with <YourDescription>[the fault code]</YourDescription>.

Tip

Use the <YourDescription> field to write a useful description for yourself about what the error code means.

For more information on SMTP transient fault codes and their meaning, refer to the SMTP Enhanced Status Codes Registry.

EXM uses the EmailCampaign.XConnect.Conflict.Retryer to retry a method if there is a conflict with xConnect. When such a conflict happens, the retryer attempts to fetch the conflicted entity from xConnect again.

In the Sitecore.EmailExperince.xConnect.config file (path: \<Your Instance Name>\App_Config\Sitecore\EmailExperience), the following is the configuration code for the xConnect conflict retryer:

<TransientFaultHandling>
    <Retryers>
        <EmailCampaign.XConnect.Conflict.Retryer>
            <Type>Sitecore.EmailCampaign.XConnect.Web.TransientFaultHandling.RetryerFactories.XConnectConflictFixedRetryerFactory, Sitecore.EmailCampaign.XConnect.Web</Type>
            <Options>
                <FixedRetry>
                    <RetryCount>3</RetryCount>
                    <RetryInterval>00:00:01</RetryInterval>
                    <FirstFastRetry>false</FirstFastRetry>
                </FixedRetry>
            </Options>
        </EmailCampaign.XConnect.Conflict.Retryer>
    </Retryers>
</TransientFaultHandling>

In the xConnect conflict retryer, you can configure the following values:

Setting

Default

Description

RetryCount

3

Specifies the maximum amount of retries for fetching a conflicting entity from xConnect.

RetryInterval

00:00:01

The fixed time interval between retries.

FirstFastRetry

false

Specifies whether EXM should perform the first retry immediately after encountering a conflict. By default, this is false, which means that the first retry happens according to the RetryInterval.