12.4 Sending e-mail | Microsoft Office Automation with Visual FoxPro

Sending e-mail

The first thing everyone seems to want to automate with Outlook is sending e-mail messages, whether it s to send bug reports to developers, saturate potential customers with solicitations, or just communicate between different sites running an application.

The key object for sending and receiving messages is MailItem, which represents a single mail message. To create a new MailItem object, call CreateItem, passing olMailItem (0) as the parameter:

#DEFINE olMailItem 0

oMailItem = oOutlook.CreateItem( olMailItem )

Table 3 lists key properties of MailItem.

This code creates a simple message to one person:

#DEFINE CR CHR(13)

WITH oMailItem

.Subject = "Meeting next week"

.Body = "Just confirming our meeting on Tuesday at 3." + CR + ;

"Please bring ideas, as well as your notes from last year's event."

.Recipients.Add("Bill Gates")

ENDWITH
Table 3. What s in a message? Here are the properties of MailItem you re most likely to work with.

Property	Type	Description
Subject	Character	The description of the message. This can be used as an index into the Items collection.
Body	Character	The content of the message.
Recipients	Object	Reference to a collection of Recipient objects, with one entry for each person to receive this message. (See the next section, "Recipients and contacts.")
To	Character	A semi-colon-separated list of recipients. Although you can specify the list of recipients by filling in this property, it s not recommended. Use .Recipients.Add() instead. (See the next section, "Recipients and contacts.")
CC	Character	A semi-colon-separated list of people receiving copies of the message (the cc: list). The caution in the To property applies to CC as well.
BCC	Character	A semi-colon-separated list of people receiving blind copies of the message (the bcc: list). The caution in the To property applies to BCC as well.
Importance	Numeric	The priority of the message (corresponding to the Importance field in the Options dialog). Uses these constants: olImportanceLow 0 olImportanceNormal 1 olImportanceHigh 2
Sensitivity	Numeric	The privacy level of the message (corresponding to the Sensitivity field in the Options dialog). Uses these constants: olNormal 0 olPersonal 1 olPrivate 2 olConfidential 3
Attachments	Object	Reference to a collection of Attachment objects, with one for each attached file. (See "Attaching files" later in this chapter.)

As with other items, once you ve filled in the properties, you can call the Save method to store the new message. However, the new message isn t automatically stored in the Outbox. The folder where unsent messages are stored is determined by a setting in Outlook s Options dialog. Figure 2 shows the Advanced E-mail Options dialog, where users make this choice. This dialog is accessed by choosing Tools|Options from the menu, then choosing E-mail Options on the Preference tab, then choosing Advanced E-mail Options on the dialog that appears.

Saving a message isn t enough to have it sent to the recipients, though. You have to call the Send method, as well. (In fact, you can just call Send and skip Save altogether.) That method, as its name suggests, sends the message immediately, routing it to the Sent Messages folder.

oMailItem.Save()

oMailItem.Send()

Figure 2. Specifying e-mail options. This dialog lets you specify where the Save method stores new mail messages. They can be placed in any of several folders, including Drafts and Outbox.

If Outlook isn t connected to the mail server, a send error occurs (though you don t get any indication of the error in VFP), and the message lands in the Outbox, ready to be sent the next time there s a connection. (Actually, it may land in your Drafts folder see the next paragraph for the reason why.) However, at that time, depending on Outlook s configuration, the message isn t necessarily sent automatically the user may have to take some action to start the process of sending and receiving messages. (None of this really has much to do with Outlook itself so much as the way Outlook is configured to send and receive mail, and none of it affects the code you write in VFP to send the mail.)

If you ve been following along with the examples and, for some reason, don t have Bill Gates in your Outlook address book, that Send command resulted in another error, one that was displayed in VFP: "OLE IDispatch exception code 4096 from Microsoft Outlook: Outlook does not recognize one or more names." (Of course, if you do have Bill Gates in your Outlook address book, you probably shouldn t have sent the message, unless you happen to have a meeting with him scheduled for Tuesday at 3.) The second part of the message is actually pretty clear. It means that Outlook was asked to send a message to someone, but doesn t have that person in its Contacts folder. Fortunately, there s a way to prevent this error before it occurs. The next section shows you how.

Recipients and contacts

As Table 3 indicates, a message can be sent to more than one person, and any given person can be on any of three lists: the main list, the CC ("carbon copy") list, or the BCC ("blind carbon copy") list. All of them are managed through a single collection called Recipients, however. The Type property of the Recipient object indicates, for each recipient, to which list he or she belongs. The choices are olTo (1), olCC (2), and olBCC (3).

To add a person to the list of recipients for a message, use the Add method of the Recipients collection. It expects a single parameter, the name or e-mail address of the person to be added. Outlook has a lot of smarts built in for matching this information up to the Contacts folder. Given half a chance, it ll do the job right. The Resolve and ResolveAll methods are used for this process. Resolve belongs to the Recipient object, while ResolveAll is a collection method. Both attempt to match the current name/address information with the Contacts folder and fill in the Name and Address properties, as well as create an AddressEntry object for the Recipient when a match is found. Resolve can work with as little as a partial first or last name, if it s unique.

#DEFINE olMailItem 0

#DEFINE CR CHR(13)

#DEFINE olCC 2

oMailItem = oOutlook.CreateItem( olMailItem )

WITH oMailItem

.Subject = "Send ideas now!"

.Body = "If you have any ideas on how to proceed with " + CR + ;

"this project, please send them to the whole group now. "

* Add recipients

WITH .Recipients

.Add("Fred Smith")

.Add("Mary Louise McGillicuddy")

.Add("Darth") && surely the only Darth, so no last name needed

.Add("Basil Rathbone")

* Copy the boss

oRecip = .Add("Ruth Less")

oRecip.Type = olCC

* Get Outlook to add all the e-mail addresses

lResolved = .ResolveAll()

ENDWITH

* Save and send

.Save()

.Send()

ENDWITH

Of course, you can t run this example as is. You ll need to substitute people who are actually in your Outlook address book (to avoid the error message described previously). Even so, you may not want to run the whole example, since they ll wonder why you re sending them such a strange message. Fortunately, you can stop short of sending the message (that is, don t execute the Send method) and just examine it in the Drafts folder or Outbox (or whichever folder you have Outlook saving unsent messages in), then delete it before you send it.

We ran into a problem with the ResolveAll method in situations where not every recipient was found. What should happen is that the e-mail address gets filled for those Recipients with matching records in Contacts, and their Resolved property is set to .T. We found that, in some cases, Resolved is not set to .T., yet calling the Resolve method for the individual Recipient record does return .T. Therefore, we recommend using Resolve rather than ResolveAll if there s any chance some Recipients may not be able to be resolved. See the example in "Putting it all together" at the end of this chapter.
Attaching files

In addition to text, you may want to send files along with a message. The Attachments collection lets you do this. Use the Add method to attach each file doing so creates a new Attachment object in the collection. Pass the name of the file, including the path where it can be found, to Add.

oMailItem.Attachments.Add( "C:\My Documents\QuarterlyReport.DOC" )

If you re adding attachments to a message you ve already saved (but not sent), remember to save the message again. If you attempt to add an attachment to an existing message and the file doesn t exist, a member is added to the Attachments collection anyway. (If you check .Attachments.Count, you ll see that it s gone up.) Be sure to use the Delete or Remove method to get rid of the spurious attachment before you go on.