Kentico CMS 6.0 Developer's Guide

Custom E-mail Provider

Custom E-mail Provider

 Previous topic Next topic Mail us feedback on this topic!  

Custom E-mail Provider

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

The custom e-mail provider allows you to use third‑party e‑mail components for sending e‑mails or add custom actions when an e-mail is sent (e.g. logging the sent e-mails for auditing purposes). All e-mails sent by Kentico CMS and its modules will use your custom e-mail provider once it is configured.

 

Example

 

The following example demonstrates how a custom e‑mail provider may be defined. This sample provider supports all of the default e‑mail functionality, but in addition creates an entry in the Kentico CMS Event log every time an e‑mail is sent.

 

1. Open the web.config file of your Kentico CMS application and add the following (if it is not already present):

 

<?xml version="1.0"?>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
 <configSections>

 
 ...
 

<!-- Extensibility BEGIN -->
 <section name="cms.extensibility" type="CMS.SettingsProvider.CMSExtensibilitySection" />
<!-- Extensibility END -->

 
 </configSections>
...

 

This defines a web.config section used to configure custom providers and helpers.

 

2. Next, create the actual cms.extensibility section and add the e‑mail provider as shown below:

 

...

 

<!-- Extensibility BEGIN -->
<cms.extensibility>
 <providers>
   <add name="EmailProvider" assembly="App_Code" type="CustomEmailProvider" />
 </providers>
 <helpers>
 </helpers>
</cms.extensibility>
<!-- Extensibility END -->

 

...

</configuration>

 

Save the changes made to the web.config file.

 

3. Now expand the App_Code folder (or Old_App_Code if you installed your project as a web application), navigate to the Samples\Modules\SampleClassLoaderModule.cs file and open it. This file demonstrates how you can load a custom class and ensure that it is used instead of the default e‑mail provider. You do not have to modify it for the purposes of this example, but the principles are the same when defining your own custom provider. Objects of the appropriate custom class are loaded by the ClassHelper_OnGetCustomClass handler:

 

[C#]

 

/// <summary>
/// Gets a custom class object based on the given parameters.
/// </summary>
private void ClassHelper_OnGetCustomClass(object sender, ClassEventArgs e)
{
  if (e.Object == null)
   {
      // Passes on an object of the appropriate custom class.
      switch (e.ClassName)
       {
          // Defines the MyTask class implementing ITask and you can create a scheduled task in App_Code
          case "Custom.MyTask":
               e.Object = new Custom.MyTask();
              break;

 
          // Defines the MyCustomIndex class implementing ICustomSearchIndex and you can create a custom smart search index in App_Code
          case "Custom.MyIndex":
               e.Object = new Custom.MyIndex();
              break;

 
          // Defines the MyCustomSiteInfoProvider class inheriting the SiteInfoProvider so that you can customize this provider
          case "CustomSiteInfoProvider":
               e.Object = new CustomSiteInfoProvider();
              break;

 
          // Define the MyCustomCacheHelper class inheriting the CacheHelper so that you can customize this helper
          case "CustomCacheHelper":
               e.Object = new CustomCacheHelper();
              break;

         

// Gets an object of the CustomEmailProvider class inheriting the EmailProvider.
case "CustomEmailProvider":
   e.Object = new CustomEmailProvider();
   break;

         
       }
   }
}

 

Notice that the ClassName property of the handler's parameter takes its value from the type attribute of the provider element in the web.config (CustomEmailProvider in this example). The example loads an object of the CustomEmailProvider class, but you may change the code here to use any class that you require when implementing a custom e‑mail provider.

 

4. Now expand the Samples\Classes folder and open the CustomEmailProvider.cs class, which contains sample customizations of the e‑mail provider. In this class, you can see how you can override the methods used to send out e‑mails (the actual code in the file may not be exactly the same as shown below, but you can modify it as necessary).

 

[C#]

 

/// <summary>
/// Sample customized e-mail provider.
/// </summary>
public class CustomEmailProvider : EmailProvider
{
  /// <summary>
  /// Synchronously sends an e-mail through the SMTP server.
  /// </summary>
  /// <param name="siteName">Site name</param>
  /// <param name="message">E-mail 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("E-mail from {0} through {1} was sent (synchronously)", message.From.Address, smtpServer.ServerName);

 
      EventLogProvider.LogInformation("CMSCustom", "EMAIL SENDOUT", detail);
   }
 
 

  /// <summary>
  /// Asynchronously sends an e-mail through the SMTP server.
  /// </summary>
  /// <param name="siteName">Site name</param>
  /// <param name="message">E-mail message</param>
  /// <param name="smtpServer">SMTP server</param>
  /// <param name="emailToken">E-mail 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("E-mail from {0} through {1} was dispatched (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 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);
   }
}

 

When writing a class implementing a custom e‑mail provider, it must always inherit from the CMS.EmailEngine.EmailProvider class. This means you can call the base methods as shown above and simply add the necessary functionality (logging information in the event log in this case).

 

5. To try out the sample custom e‑mail provider, send some e‑mails using Kentico CMS and check the log at Site Manager -> Administration -> Event log. Every successfully sent mail should have its own entry (two if it was sent asynchronously) as shown in the image below:

 

devguide_clip1495