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.
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.
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.
Contains the subject text.
Contains the body text.
Retrieves the display name of the message sender.
Retrieves the sender’s email address.
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.
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
Dim dtMsgReceived As Date dtMsgReceived = CDate(MAPIMessages1.MsgDateReceived)
You can then use Visual Basic’s
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.
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.
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.
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.”
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
' 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
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.