MAPIReadMail

Syntax

MAPIReadMail(Session, UIParam, MessageID$, Flags, Reserved)

Remarks

Reads a mail message and makes it the current inbound message. Before calling MAPIReadMail, use MAPIFindNext to verify that the correct message will be read. Use the MAPIQuery helper functions to retrieve information about the message. Use the MAPISet helper functions and MAPISaveMail to change the message. Use the MAPISet helper functions and MAPISendMail to forward or reply to the message.

MAPIReadMail automatically creates a temporary file for every attachment unless you call MAPIReadMail with the MAPI_ENVELOPE_ONLY or MAPI_SUPPRESS_ATTACH flag. The temporary files are not deleted automatically by the workgroup extensions. You must use MAPIQueryAttachments to enumerate the attachments and delete the
temporary files.

Recipients, attachments, and contents are copied from the message before the function returns to the caller, so later changes to these elements do not affect the contents of the message unless changes are explicitly saved with MAPISaveMail or MAPISendMail.

Argument

Explanation

Session

An opaque session handle whose value represents a session with the messaging system. If the value is 0 (zero), MAPIReadMail returns MAPI_E_INVALID_SESSION.

UIParam

The parent window handle for the dialog box. A value of 0 (zero) specifies that any dialog box displayed is application modal.

MessageID$

A variable-length string that is the message identifier of the message to be read. Message IDs are system specific, nonprintable, and opaque. Message IDs can be obtained from the MAPIFindNext and MAPISaveMail functions.

Flags

A bitmask of flags. Unspecified flags should always be set to
0 (zero). Undocumented flags are reserved. The following flags
are defined:

MAPI_ENVELOPE_ONLY = 64
MAPI_SUPPRESS_ATTACH = 2048
MAPI_BODY_AS_FILE = 512
MAPI_PEEK = 128

Set MAPI_ENVELOPE_ONLY if you don't want the function to copy attachments to temporary files or return the note text. All other message information (except temporary filenames) is returned. Setting this flag usually reduces the processing time required for
the function.

Set MAPI_SUPPRESS_ATTACH if you don't want MAPIReadMail to copy attachments but just to return note text.
If MAPI_ENVELOPE_ONLY is set, this flag is ignored. The flag should reduce the time required by the MAPIReadMail function.

Set MAPI_BODY_AS_FILE if you want the message body written to a temporary file and added to the attachment list as the first attachment, instead of using MAPIQueryNoteText to retrieve the message body (the default behavior). The Position argument of a body attachment is –1.

Set MAPI_PEEK if you don't want MAPIReadMail to mark the message as read. Any unsuccessful return leaves the message unread.

Reserved

Reserved for future use. This argument must be 0 (zero).


The following table lists the possible return values of the MAPIReadMail function and their meanings.

Value

Name

Meaning

–13

MAPI_E_ATTACHMENT_
WRITE_FAILURE

An attachment could not be written to a temporary file. Check folder permissions.

–4

MAPI_E_DISK_FULL

The disk was full.

–2

MAPI_E_FAILURE

One or more unspecified errors occurred while reading the mail. No mail was read.

–5

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory
to proceed. No mail was read.

–17

MAPI_E_INVALID_MESSAGE

The message ID was invalid. It may have been deleted or changed by another process.

–19

MAPI_E_INVALID_SESSION

An invalid session handle was used for the Session argument. No mail was read.

–26

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

–9

MAPI_E_TOO_MANY_FILES

Too many file attachments were contained in the message. No mail was read.

–10

MAPI_E_TOO_MANY_RECIPIENTS

There were too many recipients of the message. No mail was read.

0

SUCCESS_SUCCESS

The function returned successfully.


Example

The following example displays the subject of the first message in the Inbox. The MAPIReadMail function in the example does not retrieve the note text or attachments of the message, and it does not mark the message as read.


Sub MAIN
MAPI_LOGON_UI = 1
Session = MAPILogon(0, "", "", MAPI_LOGON_UI, 0)
Dim MessageID$, Subject$
result = MAPIFindNext(Session, 0, "", "", 0, 0, MessageID$)
MAPI_ENVELOPE_ONLY = 64
MAPI_PEEK = 128
Flags = MAPI_ENVELOPE_ONLY + MAPI_PEEK
result = MAPIReadMail(Session, 0, MessageID$, Flags, 0)
result = MAPIQuerySubject(Subject$)
MsgBox Subject$
result = MAPILogoff(Session, 0, 0, 0)
End Sub