Defining general settings

The EXM configuration settings

Version:

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

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	Default value	Description
`EXM.CheckMtaConnection`	true	Set to true if you want to test the message transfer agent (MTA) connection before starting a dispatch.
`DispatchEnqueueBatchSize`	300	Specify the number of recipients in each batch that is added to the dispatch queue.
`DispatchEnqueueThreadsNumber`	4	Specify the number of threads that must add recipient batches to the dispatch queue.
`EXM.AttachmentTotalSizeInBytes`	7340032	Specify the maximum size in bytes of all the attachments for a message. The default value is 7340032.
`EXM.CheckRecipientListsStatus`	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.CheckSuppressionList`	true	Set to true if you want EXM to check the EXM supression list before sending an email message to the Email Cloud and then to the receipient. Set to false if you want the Email Cloud to perform the first suppression list check for every recipient included in the email campaign. Regardless of the value in this setting, contacts that appear on the Email Cloud suppression list will never receive an email message from EXM. For more information about this setting, see Manage the suppression list.
`EXM.DispatchBatchSize`	100	Specify the number of contacts that you want each dispatch thread to process at a time.
`EXM.EmailTestDefinitionPath`	/sitecore/system/Marketing Control Panel/Test Lab/Emails	Specify the path to the Email Test Definition.
`EXM.TasksPath`	/sitecore/system/Settings/ Email/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`	The common global opt-out list.	Specify the path of the default global opt-out contact list that should be used for a new manager root.
`StandardMessages. SubscriptionConfirmation`		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`		Specify the path to the message that a contact should receive after clicking the confirmation link in the subscription confirmation message.
`StandardMessages. UnsubscribeNotification`		Specify the path to the message that a contact should receive after opting out of a mailing list.
StandardMessages.UnsubscribeFromAllNotification		Specify the path to the message that a contact should receive after opting out of all mailing lists.
`StandardMessages.DispatchCompleted`		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`		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.OpenAndClickCache`	1MB	Specify the cache size that is used to track duplicate opens and clicks.
`TrackerXConnectFacetsFacetName`	XConnectFacets	The name of the Tracker facet to use.

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.
`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.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.
`EXM.Enabled`	true	Set to false to disable EXM.
`EXM.IncludePIIinLogFiles`	false	Change the value to true if you want PII sensitive data to be logged by EXM.
`EXM.OpenHandlerPath`	/sitecore%20modules/Web/EXM/ 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.
`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.
`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.ContactIdentifierSource`	ex_id_s	Specify the key for the contact identifier source on the query string.
`QueryStringKey.ContactIdentifierIdentifier`	ex_id_i	Specify the key for the contact identifier identifier on the query string.
`QueryStringKey.EmailHistoryEntryId`	ec_emailid	Specify the key for identifying the email history entry ID 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.
`EXM.UseContextContentLanguage`	false	Change the value to true, to use the `Context.ContentLanguage.Name` setting for the Marketing Operations API.

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.EDS.Core.config

The Sitecore.EDS.Core.config files contains the following EXM-specific settings:

Setting	Default	Description
`EXM.DispatchProvider.MessagesPerConnection`	10000	Specifies the maximum number of messages that can be sent in one connection.
EDS.Core.Net.Smtp.Send.Retryer	Max. 10 attempts	EXM uses this exponential backoff retryer to send messages over SMTP. For more information on how to configure this retryer, see Configuring the EXM retryers.
EDS.Core.Net.Smtp.ValidateConnection.Retryer	3 retries	EXM uses this retryer to get and validate an SMTP connection from the connections pool.

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 CRAMMD5 NTLM OAUTH
	`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.
	`useOAuth`	Set to true if you want to use OAuth.
`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.
	`receiversCollection`	Specify a receivers collection by providing multiple Pop3 accounts for bounces collection.

Sitecore.EDS.Providers.CustomSMTP.OAuth.config

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

Element	Settings	Description
oauthSettings	appCallbackUrl	The redirect URI, where authentication responses can be sent and received. It should be set to https://yourinstancename/sitecore/api/ssc/EXM/OAuth.
	authUrl	The authorization endpoint.
	accessTokenUrl	The token endpoint.
	clientId	The application (client) ID.
	clientSecret	The application secret.
	scope	The space-separated list of scopes.
	state	The randomly generated unique value.

If you have suggestions for improving this article, let us know!