ClassAct
LANGUAGES: VB
TECHNOLOGIES: E-mail | System.Web.Mail
Send Mail the .NET Way
Adding e-mail functionality to apps doesn't get much simpler.
By Ken Getz
It seems every Web application needs to send e-mail sooner or later. Whether your site is sending a confirmation e-mail or the dreaded spam (not that you would do that, of course), sending e-mail is a vital function of most Web sites. Although sending e-mail programmatically was never terribly difficult, tackling the task is amazingly simple using the .NET Framework. In this article, you'll learn about the objects the System.Web.Mail namespace provides. You'll also see how to send mail, how to add attachments, and how to take advantage of all the members of the various objects. To demonstrate the various techniques, you can try out the sample project, WebMail.sln, which accompanies this article (see the Download box for details on downloading this project).
Two things to note: Sending e-mail requires an SMTP server. That is, unless you can send e-mail from the computer hosting your Web site, your site won't be able to send e-mail. You might need to set up and configure the SMTP server that's installed by default on your computer in order to get this to work. In general, if your machine can send e-mail by any means, you should be able to use the code shown in this article. (Installing and configuring SMTP is beyond the scope of this article. I'll assume you're able to send e-mail already and that you simply want to automate the process for your site by using the code in the article.) In addition, the SmtpMail class uses Collaborative Data Objects (CDO) and COM under the covers. This means CDO must be installed on the Web Server where you're hosting the page. (The easiest way I know to ensure CDO is installed is to install Outlook 98 or later, but that might not be practical on your server.)
To start sending mail, try out the sample page from the sample project shown in Figure 1. You can load this page directly or by clicking on the Work with SmtpMail.Send link on Default.aspx. If you fill in fields as shown in Figure 1 and click on the Send button, you'll end up running this code:
' At the top of the file:
Imports System.Web.Mail
' In the event procedure:
SmtpMail.Send( _
txtFrom.Text, txtTo.Text, txtSubject.Text, txtBody.Text)
Figure 1. The SmtpMail.Send method is really simple. You supply four
details and you're on your way. If you need more control, use the second
overloaded version of the method, which allows you to pass a MailMessage
object.
As you can see, the simple, static (shared) Send method requires four parameters. That's pretty much all there is to it. Of course, you have other options. The Send method allows you to specify a MailMessage object (also provided by the System.Web.Mail namespace). Using the MailMessage object provides much more flexibility, such as the option to include attachments. (The SmtpMail object also provides a static (shared) property named SmtpServer, which allows you to specify an SMTP server to use for sending mail. If you need to use an SMTP server other than the current machine, you can set this property before sending mail.)
Get the MailMessage
If you want to control your messages in greater detail, you should investigate the MailMessage class. Besides sending e-mail using four string parameters, the SmtpMail.Send method can accept a single MailMessage object as its parameter. The MailMessage class provides a number of useful properties (but no specific methods). Try the page shown in Figure 2 to test out most of the members of the MailMessage class. (Select the Mail Using MailMessage link on Default.aspx.)
Figure 2. If you need complete control over your mail message, use the
MailMessage class. You can specify attachments, text format, Cc and Bcc
recipients, priority levels, and more.
The MailMessage class provides many simple properties. See the online documentation for a full listing, but I've listed the items you're most likely to use:
- Cc and Bcc: These get or set a string containing a semicolon-delimited list of e-mail addresses for carbon copies (or blind carbon copies, in the case of Bcc).
- From and To: These get or set a string containing the e-mail addresses of the sender and recipient.
- Subject: This gets or sets the subject, as a string.
At its simplest, you're likely to use the MailMessage class as it is in this code from the sample page:
Dim msg As New MailMessage()
msg.From = txtFrom.Text
msg.To = txtTo.Text
msg.Cc = txtCC.Text
msg.Bcc = txtBCC.Text
msg.Subject = txtSubject.Text
msg.Body = txtBody.Text
SmtpMail.Send(msg)
Other properties aren't quite so simple. If you need to add attachments, you can use the Attachments property - an IList containing a list of attachment names. Note that the Attachments property is read-only. You won't be able to assign an IList object to the property. You only can add items individually to the property's list of items.
In the example page, you can add file names to the list of attachments by typing the names into the text box to the right of the Add button.
Although it's not demonstrated in the sample page, you also can set the Encoding property of the MailMessage you're sending. This property can be one of the encoding types the System.Text namespace provides, including ASCIIEncoding, UnicodeEncoding, UTF7Encoding, and UTF8Encoding.
In order to add an attachment to the Attachments property, you'll generally want to create a new MailAttachment object, passing in the filename and optionally the file encoding of the file you're attaching. (The file encoding is one of the values from the Mail.MailEncoding enumeration - Base64 or the default, UUEncode.)
The sample page uses this code to copy items from the list box containing the selected attachments into a MailMessage's Attachments property:
Dim msg As New MailMessage()
Dim li As ListItem
For Each li In lstAttachments.Items
msg.Attachments.Add(New MailAttachment(li.Text))
Next
In addition, the MailMessage class provides two properties that accept enumerated values. The BodyFormat property can be one of the MailFormat values (Html or Text). The Priority property can be one of the MailPriority values (High, Low, or Normal). For example:
msg.BodyFormat = MailFormat.Text
msg.Priority = MailPriority.High
This article's sample application retrieves its BodyFormat and Priority values from drop-down-list controls, filled with the values of the enumerations. As I described in Enumerating the Possibilities, you can write code like this to fill a list-box control or drop-down-list control with values from an enumeration:
Private Sub FillListWithEnum( _
ByVal lc As ListControl, ByVal typ As Type)
If typ.IsEnum Then
lc.Items.Clear()
Dim obj As Object
Dim li As ListItem
For Each obj In System.Enum.GetValues(typ)
li = New ListItem( _
System.Enum.GetName(typ, obj), CStr(obj))
lc.Items.Add(li)
Next
End If
End Sub
When the sample page loads, it fills the two drop-down-list controls (ddlPriority and ddlFormat), using this code:
If Not Page.IsPostBack Then
FillListWithEnum( _
ddlPriority, GetType(Mail.MailPriority))
FillListWithEnum( _
ddlFormat, GetType(Mail.MailFormat))
End If
The sample code that sends the mail message retrieves the selected values by using this code:
msg.BodyFormat = _
CType(ddlFormat.SelectedItem.Value, Mail.MailFormat)
msg.Priority = _
CType(ddlPriority.SelectedItem.Value, Mail.MailPriority)
Try the sample page and see how it works. Send an e-mail to yourself or a friend to test the various properties of the MailMessage class. For fun, try sending a message without specifying a sender or recipient. You'll receive an exception, but it's not a .NET exception. You'll trigger a COMException exception because the Send method uses COM and CDO to do its work. You'll want to add some exception handling to the code for this situation, of course.
The files referenced in this article are available for download.
Ken Getz is a senior consultant with MCW Technologies and splits his time between programming, writing, and training. He specializes in tools and applications written in Visual Studio .NET and Visual Basic, and he is co-author of Access 2002 Desktop Developer's Handbook as well as the training materials for AppDev's ASP.NET, Access 97 and 2000, Visual Basic 5.0, and Visual Basic 6.0 classes. He frequently speaks at technical conferences and is a contributing editor for asp.netPRO. E-mail Ken at mailto:[email protected].
Tell us what you think! Please send any comments about this article to [email protected]. Please include the article title and author.
