MAPISaveMail

Syntax

MAPISaveMail(Session, UIParam, Subject$, NoteText$, Flags, Reserved, MessageID$)

Remarks

Saves the current outbound message in the Mail Inbox, optionally replacing an existing message. Before calling MAPISaveMail, use MAPIFindNext to verify that the correct message will be saved. MessageID$ must be a variable-length string. The elements of the message identified by the MessageID$ argument are replaced by the elements of the current outbound message. If the MessageID$ argument is empty, a new message is created. The new message ID is returned
in the MessageID$ argument on completion of the call. All replaced messages
are saved in their appropriate folders. New messages are saved in the folder appropriate for incoming messages of that class.

The MAPISaveMail function uses the recipients and file attachments that you previously specified with the MAPISetRecipient, MAPISetRecipientList, MAPISetMessageType and MAPISetAttachment functions.

Argument	Explanation

Session	An opaque session handle whose value represents a session with the messaging system. Session handles are returned by MAPILogon and invalidated by MAPILogoff. If the value is 0 (zero) and MessageID is an empty string (""), the messaging system establishes a session from a system default session (if one exists) or presents a log-in dialog box. Otherwise, calls with Session equal to 0 (zero) return 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.
Subject$	The subject text, limited to 256 characters. (Messages saved with MAPISaveMail are not limited to 256 characters.) An empty string ("") indicates no subject text.
NoteText$	A string containing the text of the message.
Flags	A bitmask of flags. Unspecified flags should always be set to 0 (zero). Undocumented flags are reserved. The following flags are defined: MAPI_LOGON_UI = 1 MAPI_NEW_SESSION = 2 Set MAPI_LOGON_UI if the function should display a log-in dialog box (if required). When this flag is not set, the function does not display a dialog box and returns an error if the user is not logged in. Set MAPI_NEW_SESSION if you want to establish a session other than the current one. For instance, if a mail client is already running, another MAPI e-mail client can piggyback on the session created by the mail client application. Do not set this flag if you want the default session (if it still exists). If the session passed in Session is not 0 (zero), this flag is ignored.
Reserved	Reserved for future use. This argument must be 0 (zero).
MessageID$	The variable-length string identifier for this message. It is returned by the MAPIFindNext function or a previous call to MAPISaveMail. If a new message is to be created, this argument should be an empty string (""). Message ID strings must be dynamic strings.

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

Value	Name	Meaning

–4	MAPI_E_DISK_FULL	The disk was full.
–2	MAPI_E_FAILURE	One or more unspecified errors occurred while saving the mail. No mail was saved.
–5	MAPI_E_INSUFFICIENT_MEMORY	There was insufficient memory to proceed. No mail was saved.
–17	MAPI_E_INVALID_MESSAGE	An invalid message ID was used for the MessageID$ argument. No mail was saved.
–19	MAPI_E_INVALID_SESSION	An invalid session handle was used for the Session argument. No mail was saved.
–3	MAPI_E_LOGIN_FAILURE	There was no default log-in, and the user failed to log in successfully when the log-in dialog box was displayed. No mail was saved.
–26	MAPI_E_NOT_SUPPORTED	The operation was not supported by the underlying messaging system.
–1	MAPI_USER_ABORT	The user canceled the process. No mail was saved.
0	SUCCESS_SUCCESS	The function returned successfully.

Example

The following example saves a message in the Inbox with two unresolved recipients.

Sub MAIN
MAPI_LOGON_UI = 1
Session = MAPILogon(0, "", "", MAPI_LOGON_UI, 0)
Dim MessageID$
result= MAPISetRecipient(1,"Anita Kopf","")
result= MAPISetRecipient(2,"Roger Selva","")
result = MAPISaveMail(Session, 0, "Monthly Summary",\
    "We will quickly satisfy all orders for clamps.", 0, 0, MessageID$)
result = MAPILogoff(Session, 0, 0, 0)
End Sub