Skip to main content
Email Password   helpLost your password?
Screenshot - OutlookExpressView.png

Introduction

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

After moving to .NET 2.0, I thought that DotNetOpenMail had become obsolete because Microsoft had introduced their System.Net.Mail library. Generally speaking, this works quite nice, 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. At the same time, the mail merge library grew and became quite comfortable to use.

Background

Sure, with System.Net.Mail, you can send mail 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 even show parts as garbage. Besides providing mail merge capabilities, MailMergeLib addresses the following issues:

Bugs fixed in .NET 3.5 SP1:

  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"))
  2. 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.
  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. 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.

Bugs not fixed up to .NET 4.0:

  1. 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.
  2. Spaces in display names of a MailAddress must be encoded.
  3. 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.
  4. Attachments to a mail message must not have white space in the file name, which is neglected by System.Net.Mail.
  5. If the display name of an attachment contains non-ASCII characters System.Net.Mail throws an exception instead on encoding them. Anyway: The display name of an attachment must be encoded if it contains non-ASCII characters (e.g. Chinese, German Umlaut, etc.)

So although Microsoft has supplied some bug fixes, quite a few can be considered as persistent bugs without too much hope for getting them fixed. 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 one of the glorious 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 to 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 an 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

With SmtpClient, you cannot add custom event handlers. MailMergeSender will raise events 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 several 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);
}

    Or just send a single message providing a Dictionary with name/value pairs:

    Dictionary<string, string> nameValuePairs = new Dictionary<string, string>();
nameValuePairs.Add("Email", "to@addr.com");
nameValuePairs.Add("Nickname", "Bill");
mmm.SetVariables(nameValuePairs);
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, it was interesting to dig into its design and to supply modifications using 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... Anyway, MailMergeLib works well (again, after .NET 3.5 SP1 and .NET 4.0 partly broke it).

Special Thanks To

History

You must Sign In to use this message board.
 
 
Per page   
 FirstPrevNext
GeneralPeriod(dot) in the very first position of the line Pin
Member 727407		7:40 26 Oct '09  
GeneralRe: Period(dot) in the very first position of the line Pin
Member 727407		18:11 26 Oct '09  
AnswerRe: Period(dot) in the very first position of the line [modified] Pin
Norbert Bietsch		15:03 30 Oct '09  
GeneralGetting exception: "Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
jwhurst		8:29 13 Jul '09  
AnswerRe: Getting exception: "Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
Norbert Bietsch		9:55 13 Jul '09  
GeneralRe: Getting exception: "Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
jwhurst		10:39 13 Jul '09  
AnswerFixed: Getting exception: "Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
Norbert Bietsch		11:12 13 Jul '09  
GeneralRe: Getting exception: "Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
fsifabio		9:57 13 Jul '09  
GeneralField 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
fsifabio		7:53 13 Jul '09  
AnswerRe: Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
Norbert Bietsch		8:25 13 Jul '09  
GeneralRe: Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
fsifabio		9:58 13 Jul '09  
AnswerFixed: Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
Norbert Bietsch		11:09 13 Jul '09  
GeneralRe: Fixed: Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
Joe Gershgorin		14:10 17 Oct '09  
GeneralRe: Fixed: Field 'System.Net.Mail.SmtpClient.localHostName' not found. Pin
ncsol		3:00 16 Nov '09  
GeneralA question about ShouldUseBase64Encoding. Pin
xrascal		20:58 12 Jul '09  
AnswerRe: A question about ShouldUseBase64Encoding. Pin
Norbert Bietsch		7:53 13 Jul '09  
GeneralRe: A question about ShouldUseBase64Encoding. Pin
xrascal		17:06 13 Jul '09  
GeneralA bug should be fixed - System.Net.Mail.Attachment Pin
xrascal		19:11 11 Jul '09  
GeneralRe: A bug should be fixed - System.Net.Mail.Attachment Pin
xrascal		23:25 15 Jul '09  
JokeRe: A bug should be fixed - System.Net.Mail.Attachment Pin
Norbert Bietsch		7:38 20 Jul '09  
GeneralProblems on some SMTP servers Pin
Jerk_ua		1:06 4 Mar '09  
AnswerHacking System.Net.Mail.SmtpClient to enforce a certain type of authentification Pin
Norbert Bietsch		12:36 4 Mar '09  
GeneralUsing MailMergeLib in Web Service Pin
Member 727407		6:31 1 Mar '09  
AnswerRe: Using MailMergeLib in Web Service Pin
Norbert Bietsch		12:31 3 Mar '09  
GeneralRe: Using MailMergeLib in Web Service Pin
Member 727407		3:32 7 Mar '09  
Last Visit: 3:12 21 Nov '09     Last Update: 3:12 21 Nov '09 123 Next »


Last Updated 7 Aug 2009 | Advertise | Privacy | Terms of Use | Copyright © CodeProject, 1999-2009