Reprinted with permission from Visual Basic Programmer's Journal, March 2001, Volume 11, Issue 3, Copyright 2001, Fawcette Technical Publications, Palo Alto, CA, USA. To subscribe, call 1-800-848-5523, 650-833-7100, visit www.vbpj.com, or visit The Development Exchange.
Learn what your choices are for sending e-mail from your VB apps, and learn how to manage e-mail distribution lists.
by Stan Schultes
You often want to send the output to a distribution list if your app generates reports. If you distribute your app to others, you might want your users to have the option to provide feedback if they have problems or suggestions. An app that runs unattended can send e-mail to an administrator when a problem occurs, and a maintenance app can send you program log files or summary information.
You send e-mail in VB using the Messaging Application Programming Interface (MAPI). The MAPI model describes virtually everything about creating and managing e-mail messages, folders, and services. The full MAPI model is available only to C++ programmers, but most of the e-mail functionality in MAPI is available to VB programmers. Active Messaging has now become Collaborative Data Objects (CDO), and you might also find other e-mail choices useful (see Resources for Active Messaging information).I'll demonstrate three MAPI e-mail send mechanisms in this column: VB's MAPI controls, the CDO library, and the Microsoft Outlook object model. Each has similarities and differences to the others; which you choose is based largely on your own preferences (find more information about the differences in Resources). All three mechanisms require you to connect to a MAPI-compliant e-mail server such as Microsoft Exchange to send e-mail with the sample code. You must also have a MAPI-compliant e-mail client program installed on the machine your VB app sends mail from. Developers commonly use Microsoft Outlook or Exchange clients, but any MAPI-compliant e-mail client program should work.
|Figure 1 | Test Your E-Mail Send Mechanisms Click here.|
Find the E-Mail Controls and Libraries
VB versions from VB3 on have come with a pair of MAPI controls: MAPISession and MAPIMessages. The MAPI controls are the easiest to use of the three choices, but are also the least capable. For example, you can only access the mail Inbox, not the Calendar or other folders, and you can't set the message priority (high, normal, or low). Some advantages of MAPI controls are that everything you need to send e-mail comes in the box with VB, and the controls are small in size. You don't have to install an extra library as with CDO, or install and configure Outlook. The MAPI controls are easiest to use for simple e-mail applications.
You must load the MAPI controls into the VB toolbox by right-clicking on the toolbox and choosing Components from the popup menu. Scroll down the list and click on the checkbox in front of Microsoft MAPI Controls, then click on the OK button (the MAPI controls are in the MSMAPI32.ocx file in the Windows system directory). Drag both a MAPISession and a MAPIMessages control to a form. Right-click on the MAPISession control, and choose Properties from the popup menu. Uncheck the DownloadMail and LogonUI checkboxes. You set the LogonUI property in the code based on the Client Active flag.
The CDO library started life as OLE Messaging, then was called Active Messaging before being named CDO. The CDO library is a full-featured scripting interface to the MAPI model. It lets you create ActiveX components in VB using CDO that you can call from Active Server Pages (ASP) for your Web applications. Microsoft also has a separate CDONTS library you can use to send e-mail from Web servers using Simple Mail Transport Protocol (SMTP) instead of MAPI. CDO's main disadvantage, when compared to MAPI controls, is that the CDO library files are about five times larger, which is significant if you're trying to minimize your setup kit's size. Overall, CDO supports most MAPI e-mail programming features, but is more complex to use than the MAPI controls.
You must add a reference to the project (Project | References menu) to use the CDO library from VB. Scroll down the list and put a checkbox in front of the Microsoft CDO 1.21 Library. Implement the library using CDO.dll, found in the c:\program files\common files\system\mapi\ directory structure. With CDO, you declare and manipulate objects of types MAPI.Session, .Message, .Recipient, and .Attachment to control the e-mail process. See the sample code's ReadMe.txt file for more information or if you have any intermittent problems with CDO.
The Outlook object model uses Outlook itself to provide e-mail services to your app. Virtually anything Outlook 2000 can do, so can your VB program, including access to any of your private folders (E-mail, Calendar, Contacts, or Notes) and the public folders on the Exchange Server. Outlook 97, 98, and 2000 all work for sending e-mail, but Outlook 2000 adds significant functionality for you as the programmer (see the What's New information in Outlook 2000 for more information). The drawback to using the Outlook object model is that you must own a license for Microsoft Office on any machine you use to send e-mail (you can also license Outlook separately from Office).
You add a reference to the project that uses the Outlook object model from VB (Project | References menu). Scroll down the list and place a check in the checkbox in front of the Microsoft Outlook 9.0 Object Library (for Outlook 2000) or the 8.0 Object Library (for Outlook 98). You declare and manipulate objects of types Outlook.Application and Outlook.MailItem to control the e-mail process. You can find the object library by default in the file c:\program files\microsoft office\office\msoutl9.olb.
Manage E-Mail List Settings
You might want to define several e-mail lists for different purposes, especially in an app that sends e-mail. For example, in a reporting application, different reports might go to different lists of users. Saving settings in the Registry gives you flexibility in how your program operates without having to change code. The e-mail Registry structure is designed with this in mind, and the CEmailReg class handles this interface for you. Given the program name and an e-mail list name, you store the keys for the SendTo list (a semicolon-delimited list of e-mail addresses), message importance, and an Enabled flag for that list (download Listing A ).
You save the e-mail list settings under VB's default Registry key \HKEY_CURRENT_USER\Software\VB and VBA Program Settings. You can store settings for any number of program names, each having any number of e-mail list entries, by using the GetSetting and SaveSetting VB functions within CEmailReg. For example, you can keep settings for e-mail lists named DistList, Support, and DailyReports under the EmailTest program name key.
The EmailTest application demonstrates how to read and write the Registry keys in code, so you don't have to run the Registry editor to change settings manually (download Listing B). The application creates a default e-mail list name called DistList the first time you run EmailTest. Fill in your own e-mail address and click on the Save List Info button for testing purposes.
Start your e-mail client and log on before running the EmailTest app. You don't need to start your e-mail client first, but the initial message you send goes through much more quickly if you do, because the MAPI logon takes a while based on the connection speed to your e-mail server. Logging on in advance puts the initial MAPI logon time outside your application's startup time. Once you send one e-mail, subsequent messages send quickly as long as you don't destroy your mail objects between uses (see Table 1).
You can use the EmailTest code in your own applications easily. Choose one of the three e-mail class modules for sending e-mail: MAPI controls, CDO, or the Outlook object model. Include the CEmailReg class for the Registry interface, and the EmailTestBas module for object variable definitions and general-purpose functions. You might want to send e-mail either through a menu item or through some automated process. For this, create a form that includes the information you want to send, along with a way to save your settings. For an unattended app, you want to have your e-mail client start at boot time to avoid showing a MAPI logon dialog when your app first sends e-mail.
You can send e-mail from your Web app in several ways. Each shares similarities with the others, so the best choice for you depends on what you're most comfortable with. Use the EmailTest sample app to explore the possibilities and examine the how-to details. I'd be interested in hearing about any cool applications you come up with after experimenting with the sample app. Just have your app send me an e-mail.