MAPIMessages Control

The messaging application program interface (MAPI) controls allow you to create mail-enabled Visual Basic MAPI applications. There are two MAPI controls:

  • MAPISession

  • MAPIMessages

The MAPISession control signs on and establishes a MAPI session. It is also used to sign off from a MAPI session. The MAPIMessages control allows the user to perform a variety of messaging system functions.

The MAPI controls are invisible at run time. In addition, there are no events for the controls. To use them, you must specify the appropriate methods.

The MAPIMessages control performs a variety of messaging system functions after a messaging session is established with the MAPISession control.

For these controls to work, MAPI services must be present. MAPI services are provided in MAPI compliant electronic mail systems.

Note If you attempt to run a program that uses the MAPI controls, make sure that you have the 32-bit MAPI DLLs installed properly or you may not be able to perform simple MAPI functions such as SignOn. For example, on Windows 95, you must install Mail during the operating system setup, or install it separately from the control panel to correctly use MAPI functions or MAPI custom controls from Visual Basic.

Syntax

MAPIMessages

Remarks

With the MAPIMessages control, you can:

  • Access messages currently in the Inbox.

  • Compose a new message.

  • Add and delete message recipients and attachments.

  • Send messages (with or without a supporting user interface).

  • Save, copy, and delete messages.

  • Display the Address Book dialog box.

  • Display the Details dialog box.

  • Access attachments, including Object Linking and Embedding (OLE) attachments.

  • Resolve a recipient name during addressing.

  • Perform reply, reply-all, and forward actions on messages.

Most of the properties of the MAPIMessages control can be categorized into four functional areas: address book, file attachment, message, and recipient properties. The file attachment, message, and recipient properties are controlled by the AttachmentIndex, MsgIndex, and RecipIndex properties, respectively.

Message Buffers

When using the MAPIMessages control, you need to keep track of two buffers, the compose buffer and the read buffer. The read buffer is made up of an indexed set of messages fetched from a user's Inbox. The MsgIndex property is used to access individual messages within this set, starting with a value of 0 for the first message and incrementing by one for each message through the end of the set.

The message set is built using the Fetch method. The set includes all messages of type FetchMsgType and is sorted as specified by the FetchSorted property. Previously read messages can be included or left out of the message set with the FetchUnreadOnly property. Messages in the read buffer can't be altered by the user, but can be copied to the compose buffer for alteration.

Messages can be created or edited in the compose buffer. The compose buffer is the active buffer when the MsgIndex property is set to -1. Many of the messaging actions are valid only within the compose buffer, such as sending messages, sending messages with a dialog box, saving messages, or deleting recipients and attachments.

Refer to the object library in the Object Browser for property and error constants for the control.


MAPISession Control

The messaging application program interface (MAPI) controls allow you to create mail-enabled Visual Basic MAPI applications. There are two MAPI controls:

  • MAPISession

  • MAPIMessages

The MAPISession control signs on and establishes a MAPI session. It is also used to sign off from a MAPI session. The MAPIMessages control allows the user to perform a variety of messaging system functions.

Syntax

MAPISession

Remarks

After sign-on is successful, the SessionID property contains the handle to the MAPI session. The session handle must then be passed to the MAPIMessages control or an error results when using the MAPIMessages control.

The MAPISession control is invisible at run time. In addition, there are no events for the control. To use it, you must specify the appropriate properties and methods.

For these controls to work, MAPI services must be present. MAPI services are provided in MAPI compliant electronic mail systems.

Note If you attempt to run a program that uses the MAPI controls, make sure that you have the 32-bit MAPI DLLs installed properly or you may not be able to perform simple MAPI functions such as SignOn. For example, on Windows 95, you must install Exchange during the operating system setup, or install it separately from the control panel to correctly use MAPI functions or MAPI custom controls from Visual Basic.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Error Messages, MAPI Controls

The following table lists the trappable errors for the MAPI controls.

Constant | Value | Description
mapSuccessSuccess | 32000 | Action returned successfully
mapUserAbort | 32001 | User canceled process
 |  | The current action was not completed because the user canceled the process.
mapFailure | 32002 | Unspecified failure has occurred
 |  | An unspecified error occurred during the current action. For example, the action was unable to delete or address mail correctly.
mapLoginFail | 32003 | Login has failed
 |  | There was no default logon, and the user failed to log on correctly.
mapDiskFull | 32004 | Disk is full
 |  | The disk is full. The current action could not create a disk file.
mapInsufficientMem | 32005 | Insufficient memory
 |  | There is insufficient memory to proceed with the current action.
mapAccessDenied | 32006 | Access denied.
mapGeneralFailure | 32007 | General Failure.
 |  | This is an unspecified error.
mapTooManySessions | 32008 | Too many sessions
 |  | The user has too many sessions open at once.
mapTooManyFiles | 32009 | Too many files
 |  | Too many file attachments are contained in the message. The mail wasn't sent or read.
mapTooManyRecipients | 32010 | Too many recipients
 |  | There are too many message recipients specified. Mail wasn't sent or read.
mapAttachmentNotFound | 32011 | Attachment not found
 |  | The specified attachment wasn't found, and mail wasn't sent.
mapAttachmentOpenFailure | 32012 | Failure on opening attachment
 |  | The attachment couldn't be located. Mail wasn't sent. Verify that the AttachmentPathName property is valid.
mapAttachmentWriteFailure | 32013 | Failure attempting to write an attachment
 |  | An attachment could not be written to a temporary file. Check directory permissions.
mapUnknownRecipient | 32014 | Unknown recipient
 |  | The recipient doesn't appear in the address list. Mail wasn't sent.
mapBadRecipType | 32015 | Invalid recipient type
 |  | The type of recipient was incorrect. Valid type values are 1 (primary recipient), 2 (copy recipient), and 3 (blind copy recipient).
mapNoMessages | 32016 | No messages
 |  | Unable to find the next message.
mapInvalidMessage | 32017 | Invalid message
 |  | An invalid message ID was used. The current action was not completed.
mapTextTooLarge | 32018 | Text is too large
 |  | The text in the message was too large to send. The mail wasn't sent. Text is limited to 32K.
mapInvalidSession | 32019 | Invalid session
 |  | An invalid session ID was used. To associate the MAPI messages control with a valid messaging session, set the SessionID property to the MAPI session control's SessionID.
mapTypeNotSupported | 32020 | Type not supported
mapAmbiguousRecipient | 32021 | Ambiguous recipient
 |  | One or more recipient addresses are invalid. Make sure the addresses for the RecipAddress property are valid.
mapMessageInUse | 32022 | Message in use
mapNetworkFailure | 32023 | Network failure
mapInvalidEditFields | 32024 | Invalid editfields
 |  | The value of the AddressEditFieldCount property is invalid. Valid values are from 0 to 4.
mapInvalidRecips | 32025 | Invalid Recipients
 |  | One or more recipient addresses are invalid. Make sure the addresses for the RecipAddress property are valid.
mapNotSupported | 32026 | Not supported
 |  | The current action is not supported by the underlying mail system.
mapSessionExist | 32050 | Logon failure: valid session ID already exists
 |  | The MAPI messages control is already using a valid session ID.
mapInvalidBuffer | 32051 | Property is read only when not using Compose Buffer. Set MsgIndex = –1
mapInvalidReadBufferAction | 32052 | Action only valid for Compose Buffer. Set MsgIndex = –1
mapNoSession | 32053 | MAPI Failure: valid session ID does not exist
 |  | The MAPI messages control does not have a valid session handle from the MAPI session control.
mapInvalidRecipient | 32054 | No originator in the Compose Buffer
 |  | You cannot see message originator information while in the Compose Buffer (MsgIndex set to –1).
mapInvalidComposeBufferAction | 32055 | Action not valid for Compose Buffer
 |  | The attempted action is not valid in the Compose Buffer (MsgIndex set to –1)
mapControlFailure | 32056 | Cannot perform action, no messages in list
mapNoRecipients | 32057 | Cannot perform action, no recipients
mapNoAttachment | 32058 | Cannot perform action, no attachments


MAPI Control Constants

MAPISession Action Constants

Constant | Value | Description
mapSignOn | 1 | Log user into account
mapSignOff | 2 | End messaging session

MAPIMESSAGES DELETE CONSTANTS

Constant | Value | Description
mapMessageDelete | 0 | Delete current message
mapRecipientDelete | 1 | Delete the currently indexed recipient
mapAttachmentDelete | 2 | Delete the currently indexed attachment

MAPI Controls' Error Constants

Constant | Value | Description
mapSuccessSuccess | 32000 | Action returned successfully
mapUserAbort | 32001 | User canceled process
mapFailure | 32002 | Unspecified failure
mapLoginFail | 32003 | Login failure
mapDiskFull | 32004 | Disk full
mapInsufficientMem | 32005 | Insufficient memory
mapAccessDenied | 32006 | Access denied
mapGeneralFailure | 32007 | General failure
mapTooManySessions | 32008 | Too many sessions
mapTooManyFiles | 32009 | Too many files
mapTooManyRecipients | 32010 | Too many recipients
mapAttachmentNotFound | 32011 | Attachment not found
mapAttachmentOpenFailure | 32012 | Attachment open failure
mapAttachmentWriteFailure | 32013 | Attachment write failure
mapUnknownRecipient | 32014 | Unknown recipient
mapBadRecipType | 32015 | Invalid recipient type
mapNoMessages | 32016 | No message
mapInvalidMessage | 32017 | Invalid message
mapTextTooLarge | 32018 | Text too large
mapInvalidSession | 32019 | Invalid session
mapTypeNotSupported | 32020 | Type not supported
mapAmbiguousRecipient | 32021 | Ambiguous recipient
mapMessageInUse | 32022 | Message in use
mapNetworkFailure | 32023 | Network failure
mapInvalidEditFields | 32024 | Invalid editfields
mapInvalidRecips | 32025 | Invalid Recipients
mapNotSupported | 32026 | Current action not supported
mapSessionExist | 32050 | Session ID already exists
mapInvalidBuffer | 32051 | Read-only in read buffer
mapInvalidReadBufferAction | 32052 | Valid in compose buffer only
mapNoSession | 32053 | No valid session ID
mapInvalidRecipient | 32054 | Originator information not available
mapInvalidComposeBufferAction | 32055 | Action not valid for Compose Buffer
mapControlFailure | 32056 | No messages in list
mapNoRecipients | 32057 | No recipients
mapNoAttachment | 32058 | No attachments

MAPIMessages Reciptype Constants

Constant | Value | Description
mapOrigList | 0 | Message originator
mapToList | 1 | Recipient is a primary recipient
mapCcList | 2 | Recipient is a copy recipient
mapBccList | 3 | Recipient is a blind copy recipient

MAPIMessages Attachtype Constants

Constant | Value | Description
mapData | 0 | Attachment is a data file
mapEOLE | 1 | Attachment is an embedded OLE object
mapSOLE | 2 | Attachment is a static OLE object


Compose Method

Composes a message.

Syntax

object.Compose

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

This method clears all the components of the compose buffer, and sets the MsgIndex property to -1.


Copy Method (MAPIMessages Control)

Copies the currently indexed message to the compose buffer.

Syntax

object.Copy

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

This method sets the MsgIndex property to -1.


Delete Method (MAPIMessages Control)

Deletes a message, recipient, or attachment.

Syntax

object.Delete [ value ]

The Delete method syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | An integer expression specifying the item to delete, as described in Settings.

Settings

The settings for value are:

Constant | Value | Description
mapMessageDelete | 0 | Deletes all components of the currently indexed message, reduces the MsgCount property by 1, and decrements the index number by 1 for each message that follows the deleted message.
 |  | If the deleted message was the last message in the set, this method decrements the MsgIndex property by 1.
mapRecipientDelete | 1 | Deletes the currently indexed recipient. Automatically reduces the RecipCount property by 1, and decrements the index number by 1 for each recipient that follows the deleted recipient.
 |  | If the deleted recipient was the last recipient in the set, this method decrements the RecipIndex property by 1.
mapAttachmentDelete | 2 | Deletes the currently indexed attachment. Automatically reduces the AttachmentCount property by 1, and decrements the index by 1 for each attachment that follows the deleted attachment.
 |  | If the deleted attachment was the last attachment in the set, this method decrements the AttachmentIndex by 1.


Fetch Method

Creates a message set from selected messages in the Inbox.

Syntax

object.Fetch

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

The message set includes all messages in the Inbox which are of the types specified by the FetchMsgType property. They are sorted as specified by the FetchSorted property. If the FetchUnreadOnly property is set to True, only unread messages are included in the message set.

Any attachment files in the read buffer are deleted when a subsequent fetch action occurs.


Forward Method

Forwards a message.

Syntax

object.Forward

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

This method copies the currently indexed message to the compose buffer as a forwarded message and adds FW: to the beginning of the Subject line. It also sets the MsgIndex property to -1.


Reply Method

Replies to a message.

Syntax

object.Reply

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

This method copies the currently indexed message to the compose buffer and adds RE: to the beginning of the Subject line. It also sets the MsgIndex property to -1.

The currently indexed message originator becomes the outgoing message recipient.


ReplyAll Method

Replies to all message recipients.

Syntax

object.ReplyAll

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

This method copies the currently indexed message to the compose buffer and adds RE: to the beginning of the Subject line. It also sets the MsgIndex property to -1.

The message is sent to the currently indexed message originator and to all To: and CC: recipients.


ResolveName Method

Resolves the name of the currently indexed recipient.

Syntax

object.ResolveName

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

This method searches the address book for a match on the currently indexed recipient name. If no match is found, an error is returned. It does not provide additional resolution of the message originator's name or address.

The AddressResolveUI property determines whether to display a dialog box to resolve ambiguous names.

This method may cause the RecipType property to change.


Save Method

Saves the message currently in the compose buffer (with MsgIndex = -1).

Syntax

object.Save

The object placeholder represents an object expression that evaluates to an object in the Applies To list.


Send Method

Sends a message.

Syntax

object.Send [ value ]

The Send method syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying whether to show a dialog box, as described in settings.

Settings

The settings for value are:

Setting | Description
True | Sends a message inside a dialog box. Prompts the user for the various components of the message and submits the message to the mail server for delivery.
 | All message properties associated with the message being built in the compose buffer form the basis for the message dialog box. However, changes made in the dialog box do not alter information in the compose buffer.
False | (Default) Submits the outgoing message to the mail server without displaying a dialog box. An error occurs if you attempt to send a message with no recipients or with missing attachment path names.


Show Method (MAPIMessages Control)

Displays the mail Address Book dialog box or the details of the currently indexed recipient.

Syntax

object.Show [ value ]

The Show method syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying the type of dialog box to show, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | Displays a dialog box that shows the details of the currently indexed recipient. The amount of information presented in the dialog box is determined by the message system. At a minimum, it contains the display name and address of the recipient.
False | (Default) Displays the mail Address Book dialog box. You can use the address book to create or modify a recipient set. Any changes to the address book outside of the compose buffer are not saved.


SignOff Method

Ends the messaging session and signs the user off from the account specified by the UserName and Password properties.

Syntax

object.SignOff

The object placeholder represents an object expression that evaluates to an object in the Applies To list.


SignOn Method

Logs the user into the account specified by the UserName and Password properties, and provides a session handle to the underlying message subsystem.

Syntax

object.SignOn

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

The session handle is stored in the SessionID property. Depending on the value of the NewSession property, the session handle may refer to a newly created session or an existing session.


Action Property (MAPIMessage Control)

Action Property (MAPIMessages Control)

Determines what action is performed when the MAPIMessages control is invoked. This property is not available at design time. Setting the Action property at run time invokes the control. This property is write-only at run time.

Note The Action property is included for compatibility with earlier versions of Visual Basic. For additional functionality, use the new methods listed in the Methods table for the MAPIMessages control.

Syntax

object.Action [ = value ]

The Action property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | An integer expression specifying the action to perform.

Remarks

The following table lists the Action property settings used for backwards compatibility and the corresponding new methods.

Action property setting | Corresponding method
MESSAGE_FETCH | Fetch method
MESSAGE_SENDDLG | Send method
MESSAGE_SEND | Send method
MESSAGE_SAVEMSG | Save method
MESSAGE_COPY | Copy method
MESSAGE_COMPOSE | Compose method
MESSAGE_REPLY | Reply method
MESSAGE_REPLYALL | ReplyAll method
MESSAGE_FORWARD | Forward method
MESSAGE_DELETE | Delete method
MESSAGE_SHOWADBOOK | Show method
MESSAGE_SHOWDETAILS | Show method
MESSAGE_RESOLVENAME | ResolveName method
RECIPIENT_DELETE | Delete method
ATTACHMENT_DELETE | Delete method

Data Type

Integer


Action Property (MAPISession Control)

Determines what action is performed when the MAPISession control is invoked. This property is not available at design time. Setting the Action property at run time invokes the control. The Action property is write-only at run time.

Note The Action property is included for compatibility with earlier versions of Visual Basic. For additional functionality, use the new methods listed in the Methods list for the MAPISession control.

Syntax

object.Action [ = value ]

The Action property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | An integer expression specifying the action to perform, as described in Settings.

Settings

The settings for value are:

Constant | Value | Description
mapSignOn | 1 | Logs user into the account specified by the UserName and Password properties and provides a session handle to the underlying message subsystem. The session handle is stored in the SessionID property. Depending on the value of the NewSession property, the session handle may refer to a newly created session or an existing session.
mapSignOff | 2 | Ends the messaging session and signs the user off the specified account.

Remarks

This property is used to select between signing on and signing off from a messaging session. When signing on, a session handle is returned in the SessionID property.

Data Type

Integer


AddressCaption Property

Specifies the caption appearing at the top of the Address Book dialog box when the Show method is specified with the value argument missing or set to False.

Syntax

object.AddressCaption [ = value ]

The AddressCaption property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the address book dialog box caption.

Remarks

If this property is a null or empty string, the default value of the Address Book is used.

Data Type

String


AddressEditFieldCount Property

Specifies which edit controls to display to the user in the Address Book dialog box when the Show method is specified with the value argument missing or set to False.

Syntax

object.AddressEditFieldCount [ = value ]

The AddressEditFieldCount property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | An integer expression specifying which edit controls to display, as described in Settings.

Settings

The settings for value are:

Setting | Description
0 | No edit controls; only browsing is allowed.
1 | (Default) Only the To edit control should be present in the dialog box.
2 | The To and CC (copy) edit controls should be present in the dialog box.
3 | The To, CC (copy), and BCC (blind copy) edit controls should be present in the dialog box.
4 | Only those edit controls supported by the messaging system should be present in the dialog box.

Remarks

For example, if AddressEditFieldCount is 3, the user can select from the To, CC, and BCC edit controls in the Address Book dialog box. The AddressEditFieldCount is adjusted so that it is equal to at least the minimum number of edit controls required by the recipient set.

Data Type

Integer


AddressLabel Property

Specifies the appearance of the To edit control in the Address Book when the Show method is specified with the value argument missing or set to False.

Syntax

object.AddressLabel [ = value ]

The AddressLabel property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying an address label.

Remarks

This property is normally ignored and should contain an empty string to use the default label "To." However, when the AddressEditFieldCount property is set to 1, the user has the option of explicitly specifying another label (providing the number of editing controls required by the recipient set equals 1).

Data Type

String


AddressModifiable Property

Specifies whether the Address Book can be modified.

Syntax

object.AddressModifiable [ = value ]

The AddressModifiable property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying whether the Address Book can be modified, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | The user is allowed to modify their personal address book.
False | (Default) The user is not allowed to modify their personal address book.

Data Type

Boolean


AddressResolveUI Property

Specifies whether a dialog box is displayed for recipient name resolution during addressing when the ResolveName method is specified.

Syntax

object.AddressResolveUI [ = value ]

The AddressResolveUI property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying whether a dialog box is displayed, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | A dialog box is displayed with names that closely match the intended recipient's name.
False | (Default) No dialog box is displayed for ambiguous names. An error occurs if no potential matches are found (no matches is not an ambiguous situation).

Data Type

Boolean


AttachmentCount Property

Returns the total number of attachments associated with the currently indexed message. This property is not available at design time, and is read-only at run time.

Syntax

object.AttachmentCount

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

The default value is 0. The value of AttachmentCount depends on the number of attachments in the current indexed message.

Data Type

Long


AttachmentIndex Property

Sets the currently indexed attachment. This property is not available at design time.

Syntax

object.AttachmentIndex [ = value ]

The AttachmentIndex property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A long expression specifying the currently indexed attachment.

Remarks

Specifies an index number to identify a particular message attachment. The index number in this property determines the values in the AttachmentName, AttachmentPathName, AttachmentPosition, and AttachmentType properties. The attachment identified by the AttachmentIndex property is called the currently indexed attachment. The value of AttachmentIndex can range from 0 (the default) to AttachmentCount -1.

To add a new attachment, set the AttachmentIndex to a value greater than or equal to the current attachment count while in the compose buffer (MsgIndex = -1). The AttachmentCount property is updated automatically to reflect the implied new number of attachments.

For example, if the current AttachmentCount property has the value 3, setting the AttachmentIndex property to 4 adds 2 new attachments and increases the AttachmentCount property to 5.

To delete an existing attachment, specify the Delete method with the value parameter set to 2. Attachments can be added or deleted only when the MsgIndex property is set to -1.

Data Type

Long


AttachmentName Property

Specifies the name of the currently indexed attachment file. This property is not available at design time. It is read-only unless MsgIndex is set to -1.

Syntax

object.AttachmentName [ = value ]

The AttachmentName property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the name of the currently indexed attachment file.

Remarks

The file name specified is the file name seen by the recipients of the currently indexed message. If AttachmentName is an empty string, the file name from the AttachmentPathName property is used.

If the attachment is an OLE object, AttachmentName contains the class name of the object, for example, "Microsoft Excel Worksheet."

Attachments in the read buffer are deleted when a subsequent fetch occurs. The value of AttachmentName depends on the currently indexed message as selected by the AttachmentIndex property.

Data Type

String


AttachmentPathName Property

Specifies the full path name of the currently indexed attachment. This property is not available at design time. It is read-only unless MsgIndex is set to -1.

Syntax

object.AttachmentPathName [ = value ]

The AttachmentPathName property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the full path name of the currently indexed attachment.

Remarks

If you attempt to send a message with an empty string for a path name, an error results. Attachments in the read buffer are deleted when a subsequent fetch occurs. Attachments in the compose buffer need to be manually deleted. The value of AttachmentPathName depends on the currently indexed message, as selected by the AttachmentIndex property.

Data Type

String


AttachmentPosition Property

Specifies the position of the currently indexed attachment within the message body. This property is not available at design time. It is read-only unless MsgIndex is set to 1.

Syntax

object.AttachmentPosition [ = value ]

The AttachmentPosition property syntax these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A long expression specifying the position of the currently indexed attachment.

Remarks

To determine where an attachment is placed, count the characters in the message body and decide which character position you wish to replace with the attachment. The character count at that position should be used for the AttachmentPosition value.

For example, in a message body that is five-characters long, you could place an attachment at the end of the message by setting AttachmentPosition equal to 4. (The message body occupies character positions 0 to 4.)

You can't place two attachments in the same position within the same message. In addition, you can't place an attachment beyond the end of the message body.

The value of AttachmentPosition depends on the currently indexed attachment, as selected by the AttachmentIndex property.

Data Type

Long


AttachmentType Property

Specifies the type of the currently indexed file attachment. This property is not available at design time. It is read-only unless MsgIndex is set to -1.

Syntax

object.AttachmentType [ = value ]

The AttachmentType property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | An integer expression specifying the type of the currently indexed file attachment, as described in Settings.

Settings

The settings for value are:

Constant | Value | Description
mapData | 0 | The attachment is a data file.
mapEOLE | 1 | The attachment is an embedded OLE object.
mapSOLE | 2 | The attachment is a static OLE object.

Remarks

The value of AttachmentType depends on the currently indexed attachment, as selected by the AttachmentIndex property.

Data Type

Integer


DownloadMail Property

Specifies when new messages are downloaded from the mail server for the designated user.

Syntax

object.DownloadMail [ = value ]

The DownloadMail property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying when new mail is downloaded, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | (Default) All new messages from the mail server are forced to the user's Inbox during the sign-on process.
False | New messages on the server are not forced to the user's Inbox immediately, but are downloaded at the time interval set by the user.

Remarks

This property can be set to True when you want to access the user's complete set of messages when signing on. However, processing time may increase as a result.

Data Type

Boolean


FetchMsgType Property

Specifies the message type to populate the message set.

Syntax

object.FetchMsgType [ = value ]

The FetchMsgType property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the message type.

Remarks

This property determines which message types are added to the message set when the Fetch method is specified. A null or empty string in this property specifies an interpersonal message type (IPM), which is the default.

Note The availability of message types other than IPM is dependent on your mail system. Refer to it's documentation for more details.

Data Type

String


FetchSorted Property

Specifies the message order when populating the message set with messages from the Inbox.

Syntax

object.FetchSorted [ = value ]

The FetchSorted property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying the message order, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | Messages are added to the message set in the order they were received (first in, first out).
False | (Default) Messages are added in the sort order as specified by the user's Inbox.

Data Type

Boolean


FetchUnreadOnly Property

Determines whether to restrict the messages in the message set to unread messages only.

Syntax

object.FetchUnreadOnly [ = value ]

The FetchUnreadOnly property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying whether to restrict messages in the message set, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | (Default) Only unread messages of the type specified in the FetchMsgType property are added to the message set.
False | All messages of the proper type in the Inbox are added.

Data Type

Boolean


LogonUI Property

Specifies whether or not a dialog box is provided for sign-on.

Syntax

object.LogonUI [ = value ]

The LogonUI property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying whether a logon dialog box is displayed, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | (Default) A dialog box prompts new users for their user name and password (unless a valid messaging session already exists. See the NewSession property for more information).
False | No dialog box is displayed.

Remarks

The False setting is useful when you want to begin a mail session without user intervention, and you already have the account name and password for the user. If insufficient or incorrect values are provided, however, an error is generated.

Data Type

Boolean


MsgCount Property

Returns the total number of messages present in the message set during the current messaging session. This property is not available at design time, and is read-only at run time.

Syntax

object.MsgCount

The MsgCount property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Remarks

This property is used to get a current count of the messages in the message set. The default value is 0. This property is reset each time a fetch is performed.

Data Type

Long


MsgConversationID Property

Specifies the conversation thread identification value for the currently indexed message. It is read-only unless MsgIndex is set to –1.

Syntax

object.MsgConversationID [ = value ]

The MsgConversationID property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the conversation identification value.

Remarks

A conversation thread is used to identify a set of messages beginning with the original message and including all the subsequent replies. Identical conversation IDs indicate that the messages are part of the same thread. New messages are assigned an ID by the message system. The value of MsgConversationID depends on the currently indexed message, as selected by the MsgIndex property.

Data Type

String


MsgDateReceived Property

Returns the date on which the currently indexed message was received. This property is not available at design time and is read-only at run time.

Syntax

object.MsgDateReceived

The MsgDateReceived property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Remarks

The format for this property is YYYY/MM/DD HH:MM. Hours are measured on a standard 24-hour base. The value of MsgDateReceived is set by the message system and depends on the currently indexed message, as selected by the MsgIndex property.

Data Type

String


MsgID Property

Returns the string identifier of the currently indexed message. This property is not available at design time and is read-only at run time.

Syntax

object.MsgID

The MsgID property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Remarks

The message-identifier string is a system-specific, 64-character string used to uniquely identify a message. The value of MsgID depends on the currently indexed message, as selected by the MsgIndex property.

Data Type

String


MsgIndex Property

Specifies the index number of the currently indexed message. This property is not available at design time.

Syntax

object.MsgIndex [ = value ]

The MsgIndex property syntax these parts:

Part | Description
Object | An object expression that evaluates to an object in the Applies To list.
Value | A long expression specifying the index number of the currently indexed message.

Remarks

The MsgIndex property determines the values of all the other message-related properties of the MAPI Messages control. The index number can range from -1 to MsgCount -1.

Note Changing the MsgIndex property also changes the entire set of attachments and recipients.

The message identified by the MsgIndex property is called the currently indexed message. When this index is changed, all of the other message properties change to reflect the characteristics of the indexed message. A value of -1 signifies a message being built in the compose buffer — in other words, an outgoing message.

Data Type

Long


MsgNoteText Property

Specifies the text body of the message. This property is not available at design time. It is read-only unless MsgIndex is set to –1.

Syntax

object.MsgNoteText [ = value ]

The MsgNoteText property syntax has these parts:

Part | Description
Object | An object expression that evaluates to an object in the Applies To list.
Value | A string expression specifying message text.

Remarks

This property consists of the entire textual portion of the message body (minus any attachments). An empty string indicates no text.

For inbound messages, each paragraph is terminated with a carriage return-line feed pair (0x0d0a). For outbound messages, paragraphs can be delimited with a carriage return (0x0d), line feed (0x0a), or a carriage return-line feed pair (0x0d0a). The value of MsgNoteText depends on the currently indexed message, as selected by the MsgIndex property.

Data Type

String


MsgOrigAddress Property

Returns the mail address of the originator of the currently indexed message. This property is not available at design time and is read-only at run time. The messaging system sets this property for you when sending a message.

Syntax

object.MsgOrigAddress

The MsgOrigAddress property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Remarks

The value of MsgOrigAddress depends on the currently indexed message as selected by the MsgIndex property. The value is null in the compose buffer.

Data Type

String


MsgOrigDisplayName Property

Returns the originator's name for the currently indexed message. This property is not available at design time and is read-only at run time. The messaging system sets this property for you.

Syntax

object.MsgOrigDisplayName

The MsgOrigDisplayName property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Remarks

The name in this property is the originator's name, as displayed in the message header. The value of MsgOrigDisplayName depends on the currently indexed message, as selected by the MsgIndex property. The value is null in the compose buffer.

Data Type

String


MsgRead Property

Returns a boolean expression indicating whether the message has already been read. This property is not available at design time and is read-only at run time.

Syntax

object.MsgRead

The MsgRead property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Settings

The settings for the MsgRead property are:

Setting | Description
True | The currently indexed message has already been read by the user.
False | (Default) The message remains unread.

Remarks

The value of MsgRead depends on the currently indexed message, as selected by the MsgIndex property. The message is marked as read when the note text or any of the attachment information is accessed. However, accessing header information does not mark the message as read.

Data Type

Boolean


MsgReceiptRequested Property

Specifies whether a return receipt is requested for the currently indexed message. This property is not available at design time.

Syntax

object.MsgReceiptRequested [ = value ]

The MsgReceiptRequested property syntax has these parts:

Part | Description
Object | An object expression that evaluates to an object in the Applies To list.
Value | A boolean expression specifying whether a return receipt is requested, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | A receipt notification is returned to the sender when the recipient opens the message.
False | (Default) No return receipt is generated.

Remarks

The value of MsgReceiptRequested depends on the currently indexed message, as selected by the MsgIndex property.

Data Type

Boolean


MsgSent Property

Specifies whether the currently indexed message has already been sent to the mail server for distribution. This property is not available at design time and is read-only at run time. The messaging system sets this property for you when sending a message.

Syntax

object.MsgSent

The MsgSent property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Settings

The settings for the MsgSent property are:

Setting | Description
True | The currently indexed message has already been submitted to the mail server as an outgoing message.
False | The currently indexed message has not yet been delivered to the server.

Remarks

The value of MsgSent depends on the currently indexed message, as selected by the MsgIndex property.

Data Type

Boolean


MsgSubject Property

Specifies the subject line for the currently indexed message as displayed in the message header. This property is not available at design time. It is read-only unless MsgIndex is set to -1.

Syntax

object.MsgSubject [ = value ]

The MsgSubject property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the subject line.

Remarks

The value of MsgSubject depends on the currently indexed message, as selected by the MsgIndex property. MsgSubject is limited to 64 characters, including the Null character.

Data Type

String


MsgType Property

Specifies the type of the currently indexed message. This property is not available at design time. It is read-only unless MsgIndex is set to -1.

Syntax

object.MsgType [ = value ]

The MsgType property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the type of message.

Remarks

The MsgType property is for use by applications other than interpersonal mail (IPM message type). Not all mail systems support message types that are not IPM and may not provide (or may ignore) this parameter.

A null or empty string indicates an IPM message type. The value of MsgType depends on the currently indexed message, as selected by the MsgIndex property. This property is not meant for use as a filter to isolate messages by sender, receipt time, and other categories.

Data Type

String


NewSession Property

Specifies whether a new mail session should be established, even if a valid session currently exists.

Syntax

object.NewSession[ = value]

The NewSession property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A boolean expression specifying whether a new mail session should be established, as described in Settings.

Settings

The settings for value are:

Setting | Description
True | A new messaging session is established, regardless of whether a valid session already exists.
False | (Default) Use the existing session established by the user.

Data Type

Boolean


Password Property (MAPISession Control)

Specifies the account password associated with the UserName property.

Syntax

object.Password[ = value]

The Password property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the account password

Remarks

On computers that have Microsoft Exchange or Microsoft Outlook installed, the UserName property sets the Profile to be used when establishing a session. Profiles include the actual user name and password to be used, making the Password property unused. New profiles are set up by clicking on the Mail and Fax icon in the Windows Control Panel.

On computers that have Microsoft Mail installed, an empty string in this property indicates that a sign-on dialog box with an empty password field should be generated. The default is an empty string.

Data Type

String


RecipAddress Property

Specifies the electronic mail address of the currently indexed recipient. This property is not available at design time. It is read-only unless MsgIndex is set to -1.

Syntax

object.RecipAddress [ = value ]

The RecipAddress property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying mail address.

Remarks

The value of RecipAddress depends on the currently indexed recipient, as selected by the RecipIndex property.

Data Type

String


RecipCount Property

Returns the total number of recipients for the currently indexed message in a long integer. This property is not available at design time, and is read-only at run time.

Syntax

object.RecipCount

The RecipCount property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Remarks

The default value is 0. The value of RecipCount depends on the currently indexed message, as selected by the MsgIndex property.

Data Type

Long


RecipDisplayName Property

Specifies the name of the currently indexed recipient. This property is not available at design time. It is read-only unless MsgIndex is set to -1.

Syntax

object.RecipDisplayName [ = value ]

The RecipDisplayName property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the name of the recipient.

Remarks

The name in this property is the recipient's name, as displayed in the message header. The value of RecipDisplayName depends on the currently indexed message, as selected by the RecipIndex property. The ResolveName method uses the recipient name as it is stored here.

Data Type

String


RecipIndex Property

Sets the currently indexed recipient. This property is not available at design time.

Syntax

object.RecipIndex [ = value ]

The RecipIndex property syntax these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A long expression specifying the currently indexed recipient.

Remarks

Specifies an index number to identify a particular message recipient. The index number in this property determines the values in the RecipAddress, RecipCount, RecipDisplayName, and RecipType properties.

The recipient identified by the RecipIndex property is called the currently indexed recipient. The value of RecipIndex can range from 0 (the default) to RecipCount -1. When in the read buffer with RecipIndex set to -1, values of the other recipient properties show message originator information. The default setting is 0.

To add a new recipient, set the RecipIndex to a value greater than or equal to the current recipient count while in the compose buffer. The RecipCount property is updated automatically to reflect the implied new number of recipients. For example, if the current RecipCount property has the value 3, setting the RecipIndex property to 4 adds 2 new recipients and increases the RecipCount property to 5.

To delete an existing recipient, specify the Delete method with the value parameter set to 1. Recipients can be added or deleted only when the MsgIndex property is set to -1.

Data Type

Long


RecipType Property

Specifies the type of the currently indexed recipient. This property is not available at design time. It is read-only unless MsgIndex is set to -1.

Syntax

object.RecipType [ = value ]

The RecipType property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | An integer expression specifying the type of recipient, as described in Settings.

Settings

The settings for value are:

Constant | Value | Description
mapOrigList | 0 | The message originator.
mapToList | 1 | The recipient is a primary recipient.
mapCcList | 2 | The recipient is a copy recipient.
map BccList | 3 | The recipient is a blind copy recipient.

Remarks

The value of RecipType depends on the currently indexed message, as selected by the RecipIndex property. You cannot set the recipient type to 0 (the message system uses a value of 0 to indicate the message originator.)

Data Type

Integer


SessionID Property (MAPIMessages Control)

Stores the current messaging session handle. This property is not available at design time.

Syntax

object.SessionID [ = value ]

The SessionID property syntax these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A long expression specifying the current session handle.

Remarks

This property contains the messaging session handle returned by the SessionID property of the MAPISession control. To associate the MAPIMessages control with a valid messaging session, set this property to the SessionID of a MAPISession control that was successfully signed on.


SessionID Property (MAPISession Control)

Returns the current messaging session handle. This property is not available at design time, and is read only at run time.

Syntax

object.SessionID

The SessionID property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.

Remarks

This property is set when you specify the SignOn method. The SessionID property contains the unique messaging session handle. The default is 0.

Use this property to set the SessionID property of the MAPIMessages control.

Data Type

Long


UserName Property

Specifies the account user name, or the Profile to be used to establish a session.

Syntax

object.UserName [ = value ]

The UserName property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression specifying the user account.

Remarks

On computers that have Microsoft Exchange or Microsoft Outlook installed, this property sets the Profile to be used when establishing a session. Profiles include the actual user name and password to be used. New profiles are set up by clicking on the Mail and Fax icon in the Windows Control Panel.

On computers that use Microsoft Mail, this property contains the name of the user account desired for sign-on or sign-off. If the LogonUI property is True, an empty string in the UserName property indicates that a sign-on dialog box with an empty name field should be generated. The default is an empty string.

Data Type

String