Kentico CMS 7.0 Developer's Guide

SMTP server configuration

SMTP server configuration

Previous topic Next topic Mail us feedback on this topic!  

SMTP server configuration

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

Kentico CMS includes many features and modules that utilize e‑mail messages as part of their functionality, including automatic notifications, various types of confirmation messages, subscriptions, newsletters and more. To allow the application to send out e-mails, you need to register and configure SMTP servers for it.


After you finish the New site wizard, you can set up the SMTP servers directly through the administration interface. The website's primary server can be specified in Site Manager -> Settings -> System -> E-mails. This server will be used as the default option when sending e‑mails. Depending on the value selected in the Site drop‑down list, the server will either be dedicated to a single website, or designated as a global server (i.e. it will accept e‑mails from all sites in the system and also handle mails that are not related to any specific website). You can enter the following values:


SMTP server - must contain the domain name or IP address of the server, including the port number if it is not 25. Enter localhost if you wish to use the server provided by your local machine.

SMTP server user - if the server requires authentication, you can enter the user name here.

SMTP server password - if the server requires authentication, you can enter the password here.

Use SSL - indicates if the SMTP connection to the server should be secured by SSL. The server must be configured to use SSL in order for this to work.




In addition to the default server, you may add any number of servers in Site Manager -> Administration -> SMTP servers. Having multiple SMTP servers available for a website allows it to send out a greater volume of e‑mail traffic, since the extra servers will be used whenever the default one is busy.




Servers can be defined by clicking NewServer New SMTP server. Once some servers are added, you can manage them through the appropriate icons in the actions column, i.e. delete (Delete) them or edit (Edit) their configuration. Servers may also be Disabled (SMTPServerDisable) or Enabled (SMTPServerEnable) at any time (within the context of Kentico CMS).


When creating a new SMTP server or editing an existing one on the General tab, you can fill in the same options as described above for the default server. In addition, you may also select a Priority. Further information about server priority can be found in the section below.




If there are multiple sites running under your application, you may wish to assign different servers to individual websites. You can do so by switching to the Sites tab of a server's editing interface, where the given server can either be set as global or limited to one or more specific websites.


E-mail processing


There are several other settings available in Site Manager -> Settings -> System -> E-mails that affect how e‑mails are delivered to the SMTP servers.


If Enable e‑mail queue is checked, e‑mails generated by the system are temporarily stored in the database instead of being sent directly to the servers. This allows advanced e‑mail processing (as described below) and automatic resending of mails that are lost due to errors. Please see the Modules -> E-mail queue chapter of this guide to learn more. Using the e‑mail queue is highly recommended when sending out large amounts of e‑mails over a short amount of time.


This queue is processed periodically (every minute by default) and the stored e‑mails are asynchronously distributed to the appropriate SMTP servers. First, a predefined amount of e‑mails is loaded from the queue as a batch. The system then goes through the available SMTP servers in the order of their priority and assigns the batch to the first server that is not busy. The default SMTP server always has the highest priority and other servers are ordered according to the value of their Priority property (i.e. batches are first assigned to High priority servers, then Normal and finally Low). When a server receives a batch of e‑mails, it is flagged as busy until the sending is complete. A new batch is then loaded from the queue and assigned to the next available server. This process is repeated until all e‑mails in the queue are mailed out.


The maximum number of e‑mails that can be transferred from the queue to an SMTP server in a single batch is determined by the value of the Batch size setting. This setting affects all sites in the system, so it is only available if the (global) option is selected from the Site drop‑down list on the top left of the settings page. Entering an appropriate batch size can significantly affect performance. The ideal batch size depends on the amount of available SMTP servers and their capacity. If it is too large, a server may not be able to process all of the e‑mails at once or its send limit may be reached. Using a smaller batch size requires more operations, but it ensures that the load is spread more evenly across multiple servers.


Testing an SMTP server


If you wish to confirm that the values entered for an SMTP server are valid and that it is available, you can send a testing e‑mail using the Site Manager -> Administration -> System -> E-mail dialog.