Configuring SMTP servers

Kentico includes many features that utilize e‑mail messages as part of their functionality, such as:

• Automatic notifications
• Newsletters
• Various types of confirmation messages
• Content subscriptions

To allow the application to send out e-mails, you need to register and configure at least one SMTP server in the administration interface.

Setting up the default SMTP server

To register the main SMTP server:

1. Open the Settings application.

2. Navigate to the System -> E-mails category.

3. Select an option in the Site selector:

   • Choose a specific site to register a server dedicated to a single website.
   • Choose (global) to register a designated global server — the server processes e‑mails from all sites in the system, and also handles mails that are not related to any specific website.

4. Fill in the following settings:

   • SMTP server - enter the domain name or IP address of the server, including the port number (if it is not 25). Enter localhost to use a server provided by your local machine.

   • SMTP server user - if the server requires authentication, type the user name here.

   • SMTP server password - if the server requires authentication, type the password here.

     Note: After you enter and save a password, the field always displays 8 “masking” characters, even if the password is longer or shorter. This measure helps protect your password.

   • Use SSL - enable to use an SSL secured connection to the SMTP server. The server must be configured for SSL in order for this to work.

5. Click Save.

The system uses the primary server as the default option when sending e‑mails.

Configuring additional SMTP servers

In addition to the default server, you can add any number of servers in the SMTP servers application. Having multiple SMTP servers allows the system to send out a greater volume of e‑mail traffic. E-mails use the extra servers whenever the default server is busy.

You can manage existing servers through the following actions:

•  Edit - opens the server’s configuration interface
•  Delete
•  Enable /  Disable - enables or disables the server within the context of Kentico

To register new servers, click New SMTP server.

When creating new SMTP servers or editing existing ones on the General tab, you can fill in the same options as described for the default server. In addition, you can choose the delivery method for e-mails:

• Network - e-mails are sent directly to the SMTP server defined by the server name and credentials. This is the default setting for the default SMTP server defined in Settings -> System -> E-mails.
• Pickup directory - use this option if you expect high e-mail traffic on your servers (the method is faster and safer then the Network method). The e-mails are copied to a folder on the disk (defined by the Pickup directory option), from where they are processed by the SMTP server. Note that you have to grant the IIS_IUSRS group write permissions for the chosen folder.
• Pickup directory from IIS - similar to the Pickup directory, but may be more difficult to configure. Choose this method if you are already using Microsoft SMTP servers on Windows Server operating systems. You also need to install the SMTP server feature into your IIS and configure it properly. See Configure SMTP E-mail (IIS 7) for more information. Note that you have to ensure that the NETWORK SERVICE group has write permissions for the defined pickup folder.

You may also select the server’s Priority. See the Configuring e-mail processing section below for more information about server priority.

If there are multiple sites running under your application, you can assign servers to individual websites on the Sites tab. SMTP servers can either be global or limited to one or more specific websites.

Configuring e-mail processing

You can configure how the system delivers e-mails to the SMTP servers through the settings in Settings -> System -> E-mails.

If Enable e‑mail queue is checked, the system temporarily stores all outgoing e‑mails in the database instead of sending them directly to the SMTP servers. This allows advanced e‑mail processing and resending of mails that are lost due to errors. Refer to Sending e-mails to learn more about the e-mail queue.

The system periodically processes the e-mail queue (every minute by default) and asynchronously distributes the stored e‑mails to the SMTP servers:

1. A predefined amount of e‑mails is loaded from the queue as a batch.

2. The system goes through the e-mails one by one and assigns them to servers according to their priority and availability.

   • The default SMTP server always has the highest priority.
   • Other servers are ordered according to the value of their Priority property (i.e. e-mails are first assigned to High priority servers, then Normal and finally Low).

3. When a server receives an e‑mail, the server is flagged as busy until the sending is complete.

4. The system loads a new batch from the queue and continues assigning individual e-mails to available servers.

This process is repeated until all e‑mails in the queue are mailed out.

Batch size

The maximum number of e‑mails which is loaded from the database in a single batch is determined by the value of the Batch size setting. The batch size affects all sites in the system, so it is only available if the (global) option is selected in the Site selector on the top left of the settings page.

The value of the batch size affects the number and frequency of database queries. If you set the batch size too large, the system will have to process a lot of database data at one time. Using a smaller batch size increases the frequency of database queries and may reduce the database performance.

Testing SMTP servers

To confirm that your SMTP servers are configured correctly and available, you can send testing e-mails in the System application on the E-mail tab.

Debugging e-mails

Debugging can help resolve problems with e-mails sent by Kentico.

To enable e-mail debugging, add the following keys to the configuration/appSettingssection of your project’s web.config file:

<add key="CMSLogEmails" value="true"/>
<add key="CMSDebugEmails" value="true"/>

• CMSLogEmails - logs all sent e-mails to the ~/App_Data/logemails.log file. The log contains each e-mail’s recipient and subject.

• CMSDebugEmails - disables sending of e-mails to the actual recipients. The system only logs e-mails into the event log. Helpful if you need to test the functionality, but do not want the e-mails to actually reach the recipients.

  • To view the event log, open the Event log application.
  • The e-mails are logged as Information type events.
  • The Event code column contains the recipient’s address.
  • The system randomly generates Sending failed for <recipient’s e-mail address> errors to simulate sending errors.