MailMergeLib - A .NET Mail Client Library

• Download source including a small demo project - 191.5 KB

Introduction

During the time when I worked on .NET 1.1, I started to use the mail client DotNetOpenMail by Mike Bridge which really was doing a good job. Based on this, I built a library for doing basic mail merge in a Web service.

After moving to .NET 2.0, I thought that DotNetOpenMail had become obsolete because Microsoft had introduced their System.Net.Mail library. Today I still think that this is well designed code, but it has some annoying bugs and RFC violations - which I found out one after another, and which have not come to an end yet. Still the mail merge library grew and became quite comfortable to use.

Background

With System.Net.Mail, I did not encounter any show stoppers. It will send messages.

The point is: some bugs and RFC violations will increase the spam rating of spam filters for your message, and some mail clients may show parts as garbage.

While working on System.Net.Mail, I found and fixed the following bugs:

1. MailMessage.MailAddressCollection.Clear does not clear the corresponding headers. If you want to re-use an existing MailMessage object for different recipients, you will have to remove the recipients headers yourself (e.g. MailMessage.Headers.Remove("to")). - fixed in .NET 2.0 SP1
2. Display names of mail addresses that are not all 7bit characters must be encoded. This works fine with every address type except for to addresses. to addresses will never be encoded, no matter which Encoding parameter is used for a new MailAddress. - fixed in .NET 2.0 SP1, except that spaces are still not encoded.
3. MailMessage.To.ToString() returns the encoded string only after the message was sent. According to the documentation, this should be the case no matter whether the message was already sent or not.
4. With MailMessage.Headers there is a bug where headers will have white space in an encoded text. This will lead to non-RFC 2047 compliant messages, which will increase the SPAM rating of the message.
5. Attachments to a mail message must not have white space in the file name, which is neglected by System.Net.Mail.
6. Setting the transfer encoding to TransferEncoding.SevenBit turns into a header text sevenbit, instead of 7bit. sevenbit is not RFC compliant and causes problems with some mail clients. - fixed in .NET 2.0 SP1
7. Quoted-Printable encoding is not limited to a maximum of 76 characters in System.Net.Mail. RFC 2045 requires that Quoted-Printable encoding encodes lines be no more than 76 characters long. If longer lines are to be encoded with the Quoted-Printable encoding, "soft" line breaks must be used.

Although Microsoft has supplied some bug fixes, quite a few are not fixed up to .NET 3.5 SP1 (which includes .NET 2.0 SP1). So I tried to find ways to fix them on my own. All bugfixes are included in a static class Bugfixer which hopefully won't be needed in future versions of .NET. Pie in the Microsoft sky?

Using the Code

For sending a mail in System.Net.Mail, you'll first create a MailMessage, and then send it with SmtpClient. In MailMergeLib this is quite similar: you'll create a MailMergeMessage and then send it with MailMergeSender.

MailMergeMessage

Create a New Message

One big advantage of MailMergeLib comes from placeholders. {Placeholders} are the field names of a DataTable embedded in any text with curly braces.

So first create the message and adjust some settings. CultureInfo is relevant for formatting placeholders that contain dates, currency or numeric data.

// create the mail message
MailMergeMessage mmm = new MailMergeMessage("My subject for {Nickname}");

// adjust mail specific settings
mmm.CharacterEncoding = Encoding.GetEncoding("iso-8859-1");
mmm.CultureInfo = new System.Globalization.CultureInfo("en-US");
mmm.TextTransferEncoding = System.Net.Mime.TransferEncoding.SevenBit;
mmm.BinaryTransferEncoding = System.Net.Mime.TransferEncoding.Base64;

Formatting Capabilities

It is possible to add standard .NET formatting attributes to your placeholders. For a date that will show the day number and the month's name, you would write: {Date:"{0:dd MMMM}"}.

In case a column of DataRow will have ExtendedProperties for null and/or format, these properties will be used. Examples:

myDataTable.Columns["Date"].ExtendedProperties.Add("format", "{0:F}");
myDataTable.Columns["Date"].ExtendedProperties.Add("null", "#Display for null#");

Of course column types and formatting attributes must fit each other.

Message Body

The message body parts can be added or changed quite easily either by using them as a parameter in the constructor, or by setting the properties:

mmm.HtmlText = new System.IO.StreamReader("HtmlBody.html").ReadToEnd();
mmm.PlainText = new System.IO.StreamReader("TextBody.html").ReadToEnd();

HtmlText and PlainText can contain placeholders. You can insert a text file by using the special syntax {IncludeFile:"file"}. IncludeFile is the column name of the DataTable, while file means to interpret the content as a file name.

Attachments

You may also want to add some personalized attachments by adding placeholders to the file name. E.g.:

mmm.FileAttachments.Add
    (new FileAttachment("testmail_{Nickname}.pdf", "sample.pdf", "application/pdf"));

And that's the way to add string attachments:

mmm.StringAttachments.Add(new StringAttachment
    ("Some programmatically created content", "file.txt", "text/plain"));

Mail Addresses

For sending a mail, we need supply at least one recipient's address and the sender's address. Again, using placeholders makes it possible to create personalized e-mails.

// add to and from addresses
mmm.MailMergeAddresses.Add
    (new MailMergeAddress(MailAddressType.To, "<{Email}>", "{Nickname}"));
mmm.MailMergeAddresses.Add
    (new MailMergeAddress(MailAddressType.From, "<from@addr.com>", "From Name"));

Miscellaneous

If your data comes from a DataTable, it may well happen that you have recipients with empty e-mail fields. That's why you may want to set:

mmm.IgnoreEmptyRecipientAddr = true

This will then not throw an exception with empty addresses.

Want to change MailMergeLib's identification? Set...

mmm.Xmailer = "MailMergeLib 2.0"; 

... to anything you like.

MailMergeSender

In the beginning, MailMergeSender is much like System.Net.Mail.SmtpClient: Create instance of the class and provide some SMTP related settings.

SMTP Settings

Setup the mail sender:

MailMergeSender mailSender = new MailMergeSender();
mailSender.MessageOutput = MessageOutput.SmtpServer;

Set up SMTP server login details:

mailSender.SmtpHost = "smtp.server.com";
mailSender.SmtpPort = 25;
mailSender.SetSmtpAuthentification("username", "password");
mailSender.LocalHostName = "my.localhostname.com"; // used in SMTP Hello command

EventHandlers

Now here come some nice features that SmtpClient does not have. Add custom event handlers for OnBeforeSend, OnAfterSend, OnSendFailure, OnMergeBegin, OnMergeComplete, and OnMergeProgress:

mailSender.OnAfterSend += new EventHandler<MailSenderAfterSendEventArgs>(
         delegate(object obj, MailSenderAfterSendEventArgs args)
         {
                // do something useful here, like updating a progress bar
         });

Sending a Message

For the send job, there are two alternatives:

1. Start to send messages as an asynchronous operation, which will not block the calling thread:
   
   

   mailSender.SendAsync(mmm, myDataTable);

2. Start to send messages as a synchronous operation. In this case, you will loop through the rows of your DataTable, supply the row as variables to the MailMergeMessage and then call Send for each row.
   
   

   foreach (DataRow dr in myDataTable.Rows)
   {
      mmm.Variables = dr;
      mailSender.Send(mmm);
   } 

Cancelling a Send Operation

Asynchronous send operations can be cancelled at any time:

// cancel the pending mail merge immediately
mailSender.SendCancel();

Influencing Error Handling

Timeout in milliseconds:

mailSender.Timeout = 100000;

Maximum number of failures until sending a message will finally fail:

mailSender.MaxFailures = 3;

Retry delay time between failures:

mailSender.RetryDelayTime = 3000;

Delay time between each message:

mailSender.DelayBetweenMessages = 1000;

Conclusion

By fixing the bugs in System.Net.Mail, I learned a lot about its design, but also at least as much about System.Reflection. Although all the bugs mentioned were reported to Microsoft a very long time ago, they didn't remove them. Life could be so easy, I'd even pay them for using my code... Anyway, MailMergeLib works well (again, after .NET 2.0 SP1 broke it).

Special Thanks To

• .NET Reflector for helping to dive deeply into System.Net.Mail and to find out ways to fix its bugs
• Mike Bridge for his QPEncoder in DotNetOpenMail
• People working on Mono 1.2.3.1 for their AttachmentBase.MimeTypes
• All authors of inspiring articles on The Code Project that I have learned from

History

• 2007-07-10: Initial release
• 2007-07-11: Minor doc and code update
• 2007-10-08: SSL support added (thanks to WPKF), GetEncodedMailAddress fixed
• 2007-12-28: Re-designed bug fixes in BugFixer class that .NET 2.0 SP1 / .NET 3.5 broke:
  • CorrectSubjectEncodedWordRFC2047compliant
  • AddToAddressWithCorrectEncoding
  • ClearMessageHeaders
• 2008-01-01: Improvement of the Tools class
  • CalcMailSize(MailMessage msg) now gives accurate size instead of an estimation
  • Added GetMailAsMimeString (MailMessage msg) to retrieve the message content (same as in an EML file)
• 2008-01-12: Minor improvements
  • Tools.WrapLine(string input, int length)will now allow empty lines (thanks to woetertie)
  • QPEncoder from DotNetOpenMail might return a string 1 byte longer than RFC2027-compliant, fixed
• 2008-05-22: Minor improvement
  • Fixed potential problem with zip files
• 2008-08-30: Minor improvements
  • Verified: Bugs still exist in .NET 3.5 SP1, and bugfixing of MailMergeLib works with it
  • Updated documentation