The EXM configuration settings

Last updated Tuesday, November 28, 2017 in Email Experience Manager for Administrator, Developer
Keywords: Configuration

To configure the Email Experience Manager and to change the default settings shipped with EXM, you can edit the EXM configuration files on the Content Management and Content Delivery instance located in \App_Config\Include\EmailExperience\. In all the files, the settings are located in the <sitecore>/<settings> section.

This topic describes the settings in the following files:

A new exm site has been added to the sites collection:

<sites>
   <site name="exm" inherits="shell" virtualFolder="/" physicalFolder="/" startItem="/none" cacheHtml="true" />
</sites>

EXM uses the exm site when rendering email messages. By default, the exm site inherits all of the properties of the shell website, with the exception of cacheHtml='true' so that the caching settings of components are respected. You can adjust the settings in the same way as you can for any other site. The documentation for this is available in the Sitecore.config file.

Sitecore.EmailExperience.ContentManagement.config

The Sitecore.EmailExperience.ContentManagement.config file contains the following settings:

Setting

Example

Description

DispatchEnqueueBatchSize

300

Specify the number of recipients in each batch that is added to the dispatch queue.

DispatchEnqueueThreadsNumber

2

Specify the number of threads that must add recipient batches to the dispatch queue.

CheckContactSubscriptionAfterDispatchPause

false

Set to true to check the contact subscription when resuming a dispatch that was paused.

EXM.AttachmentTotalSizeInBytes

7340032

Specify the maximum size in bytes of all the attachments for a message. The default value is 7340032.

EXM.CheckRecipientListsCount

true

Set to true to check if the expected and the actual number of contacts match before the email campaign is dispatched. You must only enable this setting if list locking is disabled.

EXM.EmailTestDefinitionPath

/sitecore/system/Marketing Control Panel/Test Lab/Emails

Specify the path to the Email Test Definition.

EXM.TasksPath

/sitecore/system/Modules/E-mail Campaign Manager/Tasks

Specify the path to where you want to locate the EXM tasks.

MaxGenerationThreads

8

Specify the maximum number of dispatch tasks that should run simultaneously to generate and send email messages to individual recipients.

You can lower this value to decrease the load on the server during the dispatch. For example, if you specify 16 for both the NumberThreads setting and the MaxGenerationThreads setting, 16 dispatch tasks are processed simultaneously. If you specify 8 for the MaxGenerationThreads setting and 16 for the NumberThreads settings, only 8 dispatch tasks are processed simultaneously. The other 8 tasks are blocked and waiting to be processed.

The value must be the same or lower than the value specified for the NumberThreads setting. If you specify a higher value, it has no effect.

Note

If you specify a high value in both the NumberThreads and MaxGenerationThreads settings, the dispatch speed of an email campaign increases, but it also causes a higher CPU load.

MtaEmulation.Active

false

Set to true to enable MTA emulation mode.

MtaEmulation.MinSendTime

200

Specify the minimum amount of time in milliseconds spent to emulate the sending of a single email. Use this in conjunction with MtaEmulation.MaxSendTime to mimic the behavior of Sitecore XP to MTA round-trip time.

MtaEmulation.MaxSendTime

400

Specify the maximum amount of time in milliseconds spent to emulate the sending of a single email.

MtaEmulation.FailProbability

0.01

Specifies the probability of connection failure into your emulation.

NumberThreads

16

Specify the number of threads that you want to use when dispatching. Each thread creates a dispatch task that is responsible for sending an email campaign to a contact.

The number must be equal to the exm/eds/connectionPoolSettings/maxPoolSize setting.

ResetTimeout

3600

Specify the period in seconds after which the module considers an automated message as failed and tries to resend it.

StandardMessages.DefaultGlobalOptOutList

<relative path to the item>

Specify the path of the default global opt-out contact list that should be used for a new manager root.

StandardMessages. SubscriptionConfirmation

<relative path to the item>

Specify the path to the message that a contact should receive after subscribing to a mailing list. This message contains the subscription confirmation link.

StandardMessages. SubscriptionNotification

<relative path to the item>

Specify the path to the message that a contact should receive after clicking the confirmation link in the subscription confirmation message.

StandardMessages. UnsubscribeNotification

<relative path to the item>

Specify the path to the message that a contact should receive after opting out of a mailing list.

StandardMessages.UnsubscribeFromAllNotification

<relative path to the item>

Specify the path to the message that a contact should receive after opting out of all mailing lists.

StandardMessages. DispatchCompleted

<relative path to the item>

Specify the path to the message that should be sent to the email address specified in the Dispatch Process Notifications section when the dispatch process is finished.

StandardMessages. TriggeredNotification

<relative path to the item>

Specify the path to the activation status message of an automated message.

Sitecore.EmailExperience.ContentDelivery.config

The Sitecore.EmailExperience.ContentDelivery.config file contains the following setting:

Setting

Example

Description

EXM.DuplicateProtectionInterval

300

For two email events that relate to the same message and contact, specify the maximum interval (in seconds) between the events for them to be considered as duplicate events. If the two events occur within this time frame, only the first email event is stored.

This value is specified in seconds.

Sitecore.EmailExperience.Core.config

The Sitecore.EmailExperience.Core.config file contains the following settings:

Setting

Example

Description

CampaignClassification.Channel

{DDAFB85B-1511-48B8-9374-2A8A1F371645}

Specify the channel ID that you want to add to the email campaign item when a new email campaign is created. The channel ID is used to track the email campaign when a recipient clicks a link in a message.

ContentSearch.MasterIndexName

sitecore_master_index

Specify the name of the Master database index that you want to use for message search in EXM.

DispatchUserAgent

ECM Dispatch

Specify the name of the UserAgent that you want to use to request pages for rendering email messages in the dispatch process.

EXM.DefaultEventSiteName

exm

Specify the name of the website that email events, such as Message sent and Message undelivered, should be associated with in Experience Analytics.

EXM.Dispatch.TargetRecipientsBatchSize

10000

Specify the number of contacts that should be retrieved at a time from the search index during a dispatch.

EXM.OpenHandlerPath

/sitecore/RegisterEmailOpened.ashx

Specify the path to the handler that processes the email open events.

EXM.EmailValidationRegex

Any valid regex

Specify the regular expression validation class that you want to create and use for email validation.

EXM.RendererUrl

Valid URL

Specify the host name that should be used to download the message source when an email message is being previewed and/or sent to a recipient.

If you do not specify this value, the RendererUrl is populated with the server URL when EXM sends the first request to Sitecore. The value is by default empty.

IIS.Password

12345

Specify the password that you can log in with if anonymous access is disabled.

IIS.User

serviceuser

Specify the user name that you can log in with if anonymous access is disabled.

LanguageFieldName

ContentLanguage

Specify the name of the property in a user profile that you want to use as the preferred language for the contact.

MaxMessageFolderSize

50

Specify the maximum number of messages or message-related campaigns, tests and so on that EXM can create in a single folder. If there are more messages than this number, a new folder is created.

PhoneFieldName

Phone number

Specify the contact phone number of a Sitecore user profile. This property was added to the Sitecore.EmailExperience.Core.config file because a corresponding field does not exist in the default user profile in Sitecore XP. You should change the value of this setting if you already have the phone number field in your custom user profile.

PrivateKey

ECM_Key

Specify the private key for data encrypting or decrypting of the contact_id.

Note

This is only used if you enable encryption for legacy links.

QueryStringKey.AnalyticsContactId

ec_contact_id

Used by the module to build query strings for generating messages.

QueryStringKey.EcmId

ec_id

QueryStringKey.Recipient

ec_recipient

QueryStringKey.Subscription

ec_subscr

QueryStringKey.MessageId

ec_message_id

QueryStringKey.Campaign

ec_camp

Specify the key for identifying the email campaign on the query string.

QueryStringKey.Email

ec_email

Specifies the key for identifying the email address in the query string.

QueryStringKey.ec_lang

ec_lang

Specify the key for identifying the target language in the query string.

QueryStringKey.ec_tvi

ec_tvi

Specify the key for identifying the test value index in the query string.

QueryStringKey.ExmEncryptedQuery

ec_eq

Specify the key for identifying the module's page requests.

EXM.MessageBodyMaxCacheSize

5MB

Specify the size of the message body cache.

QueryStringKey.OnlineVersionQueryStringKey

sc_pd_view

Specify the key that you want to use for online versions of email messages.

QueryStringKey.RedirectUrl

ec_url

Specify the key for identifying the target URL in a redirect request.

EXM.UrlValidationRegex

Any valid regex

Specify the regular expression validation class that you want to create and use for URL validation.

Sitecore.ExM.Framework.config

The Sitecore.ExM.Framework.config file contains the following setting:

Setting

Example

Description

EXM.Debug

false

Set this to true to enable verbose logging in Sitecore log files. Use to troubleshoot EXM problems.

Sitecore.EmailExperience.ContentSearch.Solr.config

The Sitecore.EmailExperience.ContentSearch.Solr.config file is disabled by default (Sitecore.EmailExperience.ContentSearch.Solr.config.disabled) and EXM is set up to use the Lucene search engine.

To use the Solr search engine, for example when you configure EXM in a scaled environment, you must enable the Sitecore.EmailExperience.ContentSearch.Solr.config file.

Sitecore.EmailExperience.ContentSearch.Lucene.config

The Sitecore.EmailExperience.ContentSearch.Lucene.config file is enabled by default. If you want to enable and use Solr, you must disable this file (Sitecore.EmailExperience.ContentSearch.Lucene.config.disabled).

Sitecore.EDS.Providers.CustomSmtp.config

The Sitecore.EDS.Providers.CustomSmtp.config file contains the following settings:

Element

Settings

Description

proxySettings

enabled

Set to true to request the SMTP server via a proxy server.

hostName

Specify the proxy server IP address or the DNS name.

authMethod

Specify the HTTP authentication method of the proxy server. The valid values are Basic and NTLM.

password

Specify the password to use when logging into the proxy server. For the SOCKS4 proxy type, this value is ignored.

username

Specify the user name to use when logging into the proxy server.

port

Specify the proxy server port.

connectionType

Specify the type of the proxy server. The valid values are:

  • None
  • HTTP
  • SOCKS4
  • SOCKS5

smtpSettings

server

Specify the SMTP server address or the IP address.

port

Specify the port number of the SMTP server.

loginDomain

Specify the domain to use when logging into the SMTP server.

userName

Specify the user name to use when logging into the SMTP server.

password

Specify the password for accessing the SMTP server.

authenticationMethod

Specify the SMTP authentication method. The valid values are:

  • NONE
  • LOGIN
  • PLAIN
  • CRAM-MD5
  • NTLM

startTls

Set to true to enable the use of the SSL/TLS connection prior to authenticating and sending email.

proxySetting

Specify the proxy settings to request the SMTP server via a proxy server.

connectionPoolSettings

maxPoolSize

Specify the number of connections that can be created in the connection pool.

The number must be equal to the NumberThreads setting in the Sitecore.EmailExperience.ContentManagement.config file.

maxConnectionRetries

Specify the maximum number of retries allowed for obtaining a connection from the pool.  

If a connection is not obtained within the specified number of retries, a connection timeout exception is logged in the log file.

maxConnectionIdleTime

Specify the time from the last connection usage after which a connection is removed from the pool. 

maxConnectionWaitTime

Specify the maximum time that the connection pool should spend trying to obtain a specific connection if it failed the previous attempt.

If a connection pool exceeds the specified time, a connection timeout exception is logged in the log file.

delayBetweenConnectionRetries

Specify the time that the connection pool should delay between retrying to obtain a connection.

Sitecore.EDS.Providers.CustomSmtp.Sync.config

The Sitecore.EDS.Providers.CustomSmtp.Sync.config file contains the following settings:

Element

Settings

Description

pop3Setting

server

Specify the POP3 server IP address or the DNS name.

port

Specify the POP3 server port.

userName

Specify the user name to use when logging into the POP3 server.

password

Specify the password to use when logging into the POP3 server. 

useSsl

Set to true if you want the POP3 server to use SSL for transferring messages.

startTls

Set to true to use the TLS connection prior to authenticating and retrieving bounces.

proxySettings

Specify the proxy settings to request the POP3 server via a proxy server.

receiversCollection

settings

Specify the POP3 settings collection.

bounceInspector

Specify an inspector that verifies a message mime as a bounce and determines the type of bounce.

environmentIdentifier

Specify the environment identifier to use to identify the Sitecore instance.

Scheduling

agent

Specify the agent for synchronizing POP3 bounces.

method

Specify the name of the method in the agent class that must be executed.

interval

Specify the interval that the agent must be executed as a TimeSpan.

receviersCollection

Specify a receivers collection by providing multiple Pop3 accounts for bounces collection.

Send feedback about the documentation to docsite@sitecore.net.