Using refactored.email

Overview

Refactored.Email is a dotNet 2.0 Library that provides functionality for sending templated emails with mail merge functionality in both HTML and Plain Text formats from within dotNet websites.

Features:

Any images embedded in the HTML format are converted to attachments and referenced correctly so that message format is not compromised.
Mail Merge capabilities - with customisable field placeholders and fields
Full HTML Email and Plain Text alternative support
Support for BCC email addresses allows masking of recipients list in the final email.

This library takes advantage of the System.Net.Mail framework, and is essentially a wrapper.

Downloads

Download it from here.

Sending Mail

After including the Refactored.Email dll, you can send an email in Html format using the following code:

// Set the Mail Merge Field Pattern:

Email.FieldPattern = "[{0}]";


// Set up our HTML and Plain Text templates:

string html = @"<html>

 <head>

 <title>Simple Html Email</title>

 </head>

 <body>

 <p>Hello World!</p>

 <p>This email contains a link to the <a href="""">Refactored Website</a></p>

 <p>It also contains a mail-merge field delimited by [ and ]: [date]</p>

 </body>

</html>";



 string text = @"Hello World!

This email contains a link to the Refactored Website:

It also contains a mail-merge field delimited by [ and ]: [date]";



 // Create a new parameters collection to hold our mail-merge fields:

 NameValueCollection parameters = new NameValueCollection();

 parameters.Add("date", DateTime.Today.ToString());

 string subject;



 // We now want to parse the message templates, inserting the mail merge data and extracting the subject:

 string htmlContent = Email.ParseMessageTemplateContent(html, parameters, out subject);

 string textContent = Email.ParseMessageTemplateContent(text, parameters);



 Email.SendEmail("no-reply@refoster.com.au", "info@refoster.com.au", subject, htmlContent, textContent);

This is a basic example that will send html formatted email with it's plain text equivalent. It contains a field delimited by '[' and ']' and the html will link back to the website. The default field pattern however uses '{' and '}', so we need to tell the library to use our chosen delimiters. To do that, we use the line :

Email.FieldPattern = "[{0}]";

The {0} part must be present for it is the placeholder in the field pattern for the field names. Having the ability to change the field pattern means that the user can write email templates that are compatible with the templates used by Microsoft's ASP.Net MailDefinition class such as the CreateUserWizard control. These controls use the delimiters '<%' and '%>'.

Note that calling Email.ParseMessageTemplateContent and including the subject parameter will try to extract the subject from within any <title></title> tags in the content.

Using Email Template files

The ability to use files containing the html and plain text templates is a powerful way of managing the content of the emails.

Refactored.Email has the ability to parse templates by file name or by AppSettings key name if the template filename has been set in the AppSettings section of the web.config configuration file.

// Set the Mail Merge Field Pattern:

 Email.FieldPattern = "[{0}]";



 // Set the Base URL for hyperlinks found in the message templates

 Email.WebBaseUrl = "";



 // Set the directory containing the message templates

 Email.MailTemplateDirectory = @"C:\Mail Templates";



 // Create a new parameters collection to hold our mail-merge fields:

 NameValueCollection parameters = new NameValueCollection();

 parameters.Add("date", DateTime.Today.ToString());

 string subject;



 // We now want to parse the message templates, inserting the mail merge data and extracting the subject:

 string htmlContent = Email.ParseMessageTemplate("htmlTemplate.htm", parameters, out subject);

 string textContent = Email.ParseMessageTemplate("textTemplate.txt", parameters);



 // Send the email with both html and plain text content.

 Email.SendEmail("no-reply@refoster.com.au", "info@refoster.com.au", subject, htmlContent, textContent);

Note we have introduced 2 new Properties: MailTemplateDirectory and WebBaseUrl. MailTemplateDirectory is set to allow us to just name the templates without having to set the full path. WebBaseUrl allows us to have relative urls embedded in the HTML mail. More on that later.

The string passed into Email.ParseMessagTemplate may be a direct file name, or it could be a Web.Config AppSettings key name, where the value of that key is the actual file containing the template. This means that we can have the AppSettings key specified in the code, and if we decide to use a different file later on, we can just go and change the configuration instead of recompiling.

That's about it really, take a look at the API documentation found on the download page, and feel free to post any questions and suggestions, and I'll try to answer them as quickly as I can.

Enjoy!