Custom Email provider example

Customizing the email provider allows you to:

• Execute custom actions when sending emails (for example logging the sent emails for auditing purposes)
• Use third‑party components for sending emails

Once you create and register your custom email provider, it is used to process all emails sent out by Kentico.

The following example demonstrates how to define a custom email provider. This sample provider supports all of the default email functionality, but additionally creates an entry in the Event log whenever the system sends an email.

Writing the custom email provider

1. Open your web project in Visual Studio.

2. Create a new class in the App_Code folder (or Old_App_Code on web application installations). For example, name the class CustomEmailProvider.cs

3. Edit the class and add the following references:

   Copy

   
   
   
    using System.ComponentModel;
    using System.Net.Mail;
   
    using CMS.EmailEngine;
    using CMS.EventLog;
   
   
    

4. Modify the class’s declaration to make it inherit from the CMS.EmailEngine.EmailProvider class:

   Copy

   
   
   
    /// <summary>
    /// Customized email provider.
    /// </summary>
    public class CustomEmailProvider : EmailProvider
    {
   
    }
   
   
    

   Custom email providers must always inherit from the default EmailProvider class. This allows you to call the base methods before adding your own custom functionality.

5. Add the following method overrides into the class:

   Copy

   
   
   
    /// <summary>
    /// Customized email provider.
    /// </summary>
    public class CustomEmailProvider : EmailProvider
    {
        /// <summary>
        /// Synchronously sends an email through the SMTP server.
        /// </summary>
        /// <param name="siteName">Site name</param>
        /// <param name="message">Email message</param>
        /// <param name="smtpServer">SMTP server</param>
        protected override void SendEmailInternal(string siteName, MailMessage message, SMTPServerInfo smtpServer)
        {
            base.SendEmailInternal(siteName, message, smtpServer);
   
            string detail = string.Format("Email from {0} was sent via {1} (synchronously)", message.From.Address, smtpServer.ServerName);
            EventLogProvider.LogInformation("CMSCustom", "EMAIL SENDOUT", detail);
        }
   
        /// <summary>
        /// Asynchronously sends an email through the SMTP server.
        /// </summary>
        /// <param name="siteName">Site name</param>
        /// <param name="message">Email message</param>
        /// <param name="smtpServer">SMTP server</param>
        /// <param name="emailToken">Email token that represents the message being sent</param>   
        protected override void SendEmailAsyncInternal(string siteName, MailMessage message, SMTPServerInfo smtpServer, EmailToken emailToken)
        {
            base.SendEmailAsyncInternal(siteName, message, smtpServer, emailToken);
   
            string detail = string.Format("Email from {0} was dispatched via {1} (asynchronously)", message.From.Address, smtpServer.ServerName);
            EventLogProvider.LogInformation("CMSCustom", "EMAIL SENDOUT", detail);
        }
   
        /// <summary>
        /// Raises the SendCompleted event after the send is completed.
        /// </summary>
        /// <param name="e">Provides data for the async SendCompleted event</param>
        protected override void OnSendCompleted(AsyncCompletedEventArgs e)
        {
            base.OnSendCompleted(e);
            string detail = "Received callback from asynchronous dispatch";
            EventLogProvider.LogInformation("CMSCustom", "SEND COMPLETE", detail);
        }
    }
   
   
    

The provider uses these methods to send out emails. Each method calls the base from the parent provider class and then logs an information event into the system’s event log. You can use the same approach to add any type of custom functionality.

Registering the provider class

To register your custom provider:

1. Edit the class containing your custom provider (CustomEmailProvider.cs in this case).
2. Add the RegisterCustomProvider assembly attribute above the class declaration (requires a reference to the CMS namespace).

using CMS;

[assembly: RegisterCustomProvider(typeof(CustomEmailProvider))] 

The attribute’s parameter specifies the type of the custom provider class (as a System.Type object).

Result

The system now uses the custom email provider (defined in the CustomEmailProvider class) when sending emails.

To try out the functionality:

1. Send some emails using Kentico.
   • For example, you can use the System -> Email interface to send a test email (synchronously).
2. Check the log in the Event log application.

The event log displays an entry for every successfully sent email, identified by the CMSCustom Source value (two entries for emails sent asynchronously).