CDO & MAPI Programming with Visual Basic:

Reading Mail

Reading mail is a two-step process. First, the MAPIMessages control’s Fetch method retrieves messages from the Inbox into the control’s read buffer. Then messages are read by setting and reading the control’s properties. These properties will be discussed shortly, after the Fetch method is described.

The Fetch method has no parameters. Rather, its behavior is modified by the settings of some of the properties of the MAPIMessages control.

The FetchUnreadOnly property is a Boolean flag that, if set to True, causes a subsequent call to Fetch to retrieve only those messages that haven’t been read (i.e., the MsgRead property is False). If the FetchUnreadOnly property is False, its default value, the next call to Fetch retrieves all messages from the Inbox.

The FetchSorted property is a Boolean flag that, if set to True, causes a subsequent call to Fetch to sort the retrieved messages according to the order in which they were received. If the FetchSorted property is False, its default value, the messages are sorted according to the order specified by the Inbox. The MAPI controls don’t provide a way to modify the Inbox sort order.

The FetchMessageType property is a string that allows you to fetch messages that belong to a certain message class. When this property contains a zero-length string (as it does by default), messages are retrieved without regard to their message class. However, when this property has some other value, a subsequent Fetch retrieves only those messages whose MsgType property matches the value in FetchMessageType. For more information on how to use message classes, see the discussion of the MsgType property and of message classes in Section 4.10 later in this chapter.

Tip

If there is mail on the mail server that hasn’t been downloaded to the Inbox, the Fetch method will not retrieve it. The purpose of the Fetch method is to retrieve a set of messages from the Inbox into the MAPIMessages control’s read buffer. This is not the same thing as downloading messages from the mail server to the Inbox. For users on a LAN, this distinction may be academic; messages are generally moved from the mail server to the user’s Inbox in real time, so the Fetch method always retrieves all current messages. However, users connecting over dialup networking are very aware of the difference. Messages sit on the mail server until the user explicitly dials in and retrieves them. In Microsoft Outlook, for example, this message transfer is accomplished by selecting “Send and Receive” from Outlook’s toolbar. Using the MAPI controls, the same effect is achieved by setting the MAPISession control’s DownLoadMail property to True prior to calling its SignOn method. This causes the sign-on process to connect to the mail server and download new messages to the Inbox.

After calling the Fetch method, and prior to reading any message-related properties, the MAPIMessages control must be told which message to access. As already mentioned, this is the purpose of the MsgIndex property. For a lengthier discussion of how the MsgIndex property works, see Section 4.3.1, earlier in this chapter.

Once the MsgIndex property has been set, the other message-related properties are read to retrieve the information for that specific message. These properties include:

MsgSubject

Contains the subject text.

MsgNoteText

Contains the body text.

MsgOrigDisplayName

Retrieves the display name of the message sender.

MsgOrigAddress

Retrieves the sender’s email address.

MsgRead

Indicates whether a message has been read. This property is set to True when MsgNoteText or any of the attachment properties is read. You might use this information to mark unread messages in the user interface of your application, allowing the user to see which messages remain unread. Unfortunately, this property is read-only, so you can’t provide the user with the nice feature of being able to change this flag.

MsgDateReceived

Contains the date on which the message was received. This property is a string in “YYYY/MM/DD HH:MM” format. You can easily convert it to a standard date type using Visual Basic’s CDate function:

Dim dtMsgReceived As Date
   
dtMsgReceived = CDate(MAPIMessages1.MsgDateReceived)

You can then use Visual Basic’s Format function to output the date in any format you like. Note that if an unsent message is saved in the Inbox, the MsgDateReceived property is blank, which causes CDate to raise a “Type mismatch” error (error number 13). Your code should explicitly trap and handle this error.

MsgReceiptRequested

A Boolean value that indicates whether the sender requested a return email to show that the message was received.

The mail system handles the return receipt for you—your code doesn’t need to do a thing, so you’re not likely to use this property.

MsgSent

Indicates whether the message has been sent to the mail server for distribution.

This property is set to True by the mail system when the message has been moved onto the mail server. When you’re reading messages, this property is likely to be True on virtually all of them. The only time you’ll find it to be False is when an unsent message has been saved in the Inbox. This can happen, for instance, by calling the MAPIMessages control’s Save method. It can also happen if another mail client is used to copy an unsent message from the Outbox to the Inbox. The Save method is discussed later in this chapter, under Section 4.11.

MsgConversationID

Helps track conversation threads. For more information and some caveats regarding conversation threads, see the discussion on conversation threads later in this chapter, under “Advanced Topics.”

MsgID

A 64-character string used by the mail system to identify the message in the message store. It’s not at all useful to your client application.

Once you’ve read a message, you may wish to delete it. This is accomplished by calling the MAPIMessages control’s Delete method with an argument of mapMessageDelete:

' Delete the currently-indexed message.
MAPIMessages1.Delete mapMessageDelete

Note that this does not move the message into the user’s Deleted Items folder—it really and truly deletes the message. The MAPI controls don’t provide the ability to move messages between folders.

Let’s turn our attention now to a message’s list of recipients. When reading received messages, read the recipient-related properties to find out to whom each message was sent. In addition, you can tell whether each recipient was a primary recipient (on the “To” list), or a copy recipient (on the “Cc” list). However, recipients that were on the sender’s blind copy list do not appear at all in the received message (that’s the point, after all).

Before reading recipient-related properties, first set the MsgIndex property to indicate which message to read, then set the RecipIndex property to indicate which recipient to access on that message. The RecipIndex property is a zero-based index that can range from to one less than the value contained in the RecipCount property. See Section 4.3.1, earlier in this chapter, for a more detailed discussion of how these properties work.

To discover whether a given recipient is a primary or copy recipient, check the setting of the RecipType property. This is an integer value that equals mapToList for primary recipients, and mapCcList for copy recipients.

The email address of the recipient is found in the RecipAddress property, and the friendly display name of the recipient is found in RecipDisplayName. See Section 4.10, later in this chapter, to learn how to display a properties dialog box for a given recipient.