Aug. 3, 2008, 7:43 a.m.
posted by vendetta
Using Expanded Mail Message Formats
With the popularity of e-mail came compatibility problems. Many e-mail systems had their own way of formatting mail messages. It wasn’t long before a standard e-mail message format was created, allowing the various e-mail systems to communicate and interpret each other’s mail messages. RFC 2822 defines the standard formatting of an e-mail message. The .NET MailMessage class offers a standard way for you to create RFC2882 messages to send to remote customers.
The RFC2822 Mail Format
RFC 2822 specifies that each message should consist of two separate sections:
-
A header that contains message information
-
A body that contains the text of the message
The header of an RFC2822 standard mail message contains separate data fields that supply additional information in the message (see Figure). Each header field is on a separate line in the message and contains data in text format. The format of each header line is as follows (note the colon separating the header tag from the data value):
header: text data
Individual header fields do not need to be specified in any particular order in the message. The header fields must also appear before the body of the message and must be separated by a single blank line.
The Origination Date Field
The origination date field identifies the date and time the message was originally sent. It consists of the keyword Date:, followed by the appropriate date and time value:
Date: Wed, 21 Aug 2002 18:30:00 -0500
It is important that the origination date identify the time zone of the sending host so the receiving customer can determine the actual time the message was sent.
The Originator Fields
Three separate originator fields identify where the message originated:
From: mailbox-list Sender: mailbox Reply-To: mailbox-list
At least one of the three originator fields must be present in a mail message. The mailbox-list value can contain either a single mail address or multiple mail addresses separated by commas.
The From field identifies the specific person who originated the message, while the Sender field identifies the person who actually sent the message (the two don’t necessarily have to be the same). If the Reply-To field is present, it represents the return address where the message originator intends replies to be sent.
The Destination Address Fields
Three destination address fields identify where the message should be sent:
To: address-list Cc: address-list Bcc: address-list
The destination address fields can each specify one or more addresses in the address-list fields, using commas to separate multiple addresses.
The To field identifies primary recipients of the mail message, and the Cc field contains addresses of others who are to receive the message though it wasn’t directed toward them.
The Bcc field contains addresses of recipients who are not disclosed in the mail message. The Bcc field is different from the other destination address fields; although the sending message may contain a Bcc field, it must be stripped off before sending to the intended destination addresses.
The Identification Fields
The identification fields help uniquely identify the message, both to the mail system and to the recipients. There are quite a few identification fields available, but these are the most common:
Message-ID: msg-id In-Reply-To: msg-id References: msg-id
The Message-ID field provides a unique tracking number to the mail message. Each message sent by an MTA should contain a Message-ID field, assigned by the MTA, that uniquely identifies the message from all others. The msg-id value can contain any combination of letters and numbers to uniquely identify the message.
The In-Reply-To and References fields are used to relate one message to a previous message. Often, a message sent in reply to a previous message will contain the Message-ID field of the previous message in the In-Reply-To field.
The Informational Fields
The informational fields are optional; they help recipients identify and possibly filter mail messages. The informational fields are as follows:
Subject: subject-text Comments: comment-text Keywords: phrase-text
The Subject field is the most common field. It identifies the message with a short string describing the topic of the message. The Comments field can present a longer string further describing the body of the message. The Keywords field specifies short phrases, separated by commas, that identify the message content. The Keywords field can be used in MDA filtering software to sort incoming messages.
The MailMessage Class Properties
The .NET MailMessage class easily creates RFC2822-formatted messages to send using the SmtpMail class. This allows you to add more useful header field information than what the generic SmtpMail.Send() method allows. You construct the e-mail message piece by piece and specify formatting options for the message.
The default constructor for the MailMessage class is not very difficult:
MailMessage newmessage = new MailMessage();
That’s it—no fancy parameters to remember. All of the work is done in the properties of the class. Figure lists the properties that can be used.
|
Property |
Description |
|---|---|
|
Attachments |
Specifies a list of file attachments to add to the message |
|
Bcc |
Gets or sets a semicolon-delimited list of addresses to use in the Bcc: header field |
|
Body |
Gets or sets the body of the e-mail message |
|
BodyEncoding |
Gets or sets the encoding type of the message body |
|
BodyFormat |
Gets or sets the content type of the message body |
|
Cc |
Gets or sets a semicolon-delimited list of addresses to use in the Cc: header field |
|
From |
Gets or sets the address to use in the From: header field |
|
Headers |
Sets custom header fields and values for the message |
|
Priority |
Gets or sets the priority of the message |
|
Subject |
Gets or sets the text string used in the Subject: header field |
|
To |
Gets or sets the semicolon-delimited list of addresses used in the To: header field |
|
UrlContentBase |
Gets or sets the Content-Base HTTP header value |
|
UrlContentLocation |
Gets or sets the Content-Location HTTP header value |
The easy properties to use are the typical To, From, Cc, and Bcc values. You can specify additional header fields using the Header property, although this is done a little differently.
The Header Property
The Header property uses the IDictionary class to store the header field and value pair. The easiest way to do this is to use the Add() method:
newmessage.Header.Add("Reply-To", "testing@myisp.net");
You can specify any valid RFC2822 header field using the Header property and it will be included in the message header fields. You can easily add a Date field to your messages using the format:
DateTime mydate = DateTime.Now;
newmessage.Header.Add("Date", mydate.ToString());
The Body Properties
The Body property, the BodyEncoding, and BodyFormat properties specify both the content and the format of the message body. The text of the message is assigned to the Body property. How it looks to the remote mail server is controlled by the BodyEncoding and BodyFormat properties.
The BodyEncoding property uses the System.Text.Encoding classes to specify the type of text used for the message. The possible values are ASCII, Unicode, UTF-7, and UTF-8. The default is the default system encoding type (which is ASCII in the United States).
In contrast to the text encoding, the BodyFormat property specifies how the text will be presented in the mail message. The possible values are defined in the MailFormat enumeration:
MailFormat.Html Uses hypertext markup language formatting
MailFormat.Text Uses plain text formatting
By default, the Text value is used. This ensures that any e-mail client can read the message. Alternatively, you can use the Html value to incorporate special text formatting within the message.
The Priority Property
The Priority property allows you to set the Priority header field. Though it’s not a standard header field, many mail clients recognize the Priority field as indicating the importance of a mail message. The System.Web.Mail namespace includes the MailPriority enumeration that specifies this value. The possible values are as follows:
MailPriority.High Important messages that require immediate attention
MailPriority.Normal Regular mail messages
MailPriority.Low Extraneous mail messages, such as advertisements
To set the priority of a message, just assign the appropriate value to the Priority property:
newmessage.Priority = MailPriority.High;
The Attachment Property
The Attachment property specifies files you want to include as attachments to the mail message. You can specify one or more MailAttachment class objects as attachments using the following format:
MailAttachment ma = new MailAttachment("c:\\tempfile.bmp");
newmessage.Attachment.Add(ma);
The file specified in the MailAttachment object is encoded and added to the message, as explained in the later section "Mail Attachments."
Using the MailMessage Class
The FancyMailTest.cs program in Listing 13.2 uses the MailMessage class to produce a fancier mail message to send to the recipient.
 |
using System;
using System.Web.Mail;
class FancyMailTest
{
public static void Main()
{
MailMessage mm = new MailMessage();
mm.From = "haley@myisp.net";
mm.To = "riley@yourisp.net;rich@shadrach.ispnet1.net";
mm.Cc = "matthew@anotherisp.net;chris@hisisp.net
mm.Bcc = "katie@herisp.net;jessica@herisp.net";
mm.Subject = "This is a fancy test message";
mm.Headers.Add("Reply-To", "haley@myisp.net");
mm.Headers.Add("Comments", "This is a test HTML message");
mm.Priority = MailPriority.High;
mm.BodyFormat = MailFormat.Html;
mm.Body = "<html><body><h1>This is a test message</h1><h2>This message Â
should have HTML-type formatting</h2>Please use an HTML-capable viewer.";
try
{
SmtpMail.Send(mm);
} catch (System.Web.HttpException)
{
Console.WriteLine("This device is unable to send Internet messages");
}
}
}
|
The FancyMailtest program creates a MailMessage object and assigns values to the various properties. Multiple recipients are added to the To, Cc, and Bcc properties, each one separated by a semicolon. Message priority is set to High, and two additional header lines are added to the mail message.
Because the BodyFormat type is set to Html, you can use any valid HTML syntax in the body text to format the message. Figure demonstrates how this message looks when viewed with a Microsoft Outlook Express mail client.
