MAPISendMail

Syntax

MAPISendMail(Session, UIParam, Subject$, NoteText$, Flags, Reserved)

Remarks

Sends a mail message, allowing greater flexibility than MapiSendDocuments
in message generation. This function sends the current outbound message as a standard mail message. It can, if you choose, prompt for user input with a dialog box or proceed without any user interaction.

You can optionally provide a list of subject or note text when you call MAPISendMail. The MAPISendMail function uses the recipients and file attachments that you previously specified with the MAPISetRecipient, MAPISetRecipientList, or MAPISetAttachment functions.

If you provide recipient names, file attachments, or note text, the function can send the files or note without prompting users. If the optional arguments are specified and a dialog box is requested with the MAPI_DIALOG flag, the arguments provide the initial values for the Send Note dialog box.

File attachments are copied to the message before the function returns; therefore, later changes to the files do not affect the contents of the message. The files must be closed when they are copied.

Argument

Explanation

Session

An opaque session handle whose value represents a session with the messaging system. If the value is 0 (zero), the messaging system sets up a session either from a system default session (if one exists) or by presenting a log-in dialog box. In all cases, the messaging system returns to its state before the call.

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. An empty string ("") indicates no subject text. Some implementations may truncate subject lines that are too long or contain carriage returns, linefeeds, or other control characters.

NoteText$

A string containing the text of the message. An empty string ("") indicates no text. The implementation wraps lines as appropriate. Implementations may place limits on the size of the text. A return
of MAPI_E_TEXT_TOO_LARGE is generated if this limit is exceeded.


Argument

Explanation

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
MAPI_DIALOG = 8

Set MAPI_LOGON_UI if the function should display a dialog box to prompt for log-in (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.

Set MAPI_DIALOG if the function should display a dialog box to prompt the user for recipients and other sending options. When you do not set this flag, the function does not display a dialog box, but at least one recipient must be specified.

Reserved

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


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

Value

Name

Meaning

–21

MAPI_E_AMBIGUOUS_RECIPIENT

A recipient matched more than one of the recipient descriptor types, and MAPI_DIALOG was not set. No mail was sent.

–11

MAPI_E_ATTACHMENT_
NOT_FOUND

The specified attachment was not found. No mail was sent.

–15

MAPI_E_BAD_RECIPTYPE

The type of a recipient was not MAPI_TO, MAPI_CC, or MAPI_BCC. No mail was sent.

–4

MAPI_E_DISK_FULL

The disk was full. No mail was sent.

–2

MAPI_E_FAILURE

One or more unspecified errors occurred while sending the mail. No mail was sent.


Value

Name

Meaning

–5

MAPI_E_INSUFFICIENT_MEMORY

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

–19

MAPI_E_INVALID_SESSION

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

–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 sent.

–18

MAPI_E_TEXT_TOO_LARGE

The text in the message was too large to be sent. No mail was sent.

–9

MAPI_E_TOO_MANY_FILES

There were too many file attachments. No mail was sent.

–10

MAPI_E_TOO_MANY_RECIPIENTS

There were too many message recipients specified. No mail was sent.

–8

MAPI_E_TOO_MANY_SESSIONS

The user had too many sessions open at once. No mail was sent.

–14

MAPI_E_UNKNOWN_RECIPIENT

The recipient did not appear in the address list. No mail was sent.

–1

MAPI_USER_ABORT

The user canceled the process from the send dialog box. No mail was sent.

0

SUCCESS_SUCCESS

The function returned successfully.


Examples

The following example sends a message to two unresolved recipients. MAPISendMail will return an error if the names cannot be resolved unambiguously.


Sub MAIN
MAPI_LOGON_UI = 1
Session = MAPILogon(0, "", "", MAPI_LOGON_UI, 0)
result = MAPISetRecipient(1, "Anne Gabor", "")
result = MAPISetRecipient(2, "Roger Selva", "")
result = MAPISendMail(Session, 0, "Monthly Summary",\
    "We will quickly satisfy all orders for clamps.", 0, 0)
result = MAPILogoff(Session, 0, 0, 0)
End Sub

The following example prepares a message for sending to two recipients, then displays the Send Note dialog box to allow the user to modify, cancel, or send the message.


Sub MAIN
MAPI_LOGON_UI = 1
Session = MAPILogon(0, "", "", MAPI_LOGON_UI, 0)
Dim MessageID$
result = MAPISetRecipient(1, "Phillipe Tran", "AF:TBU/WGAM/PHILT")
result = MAPISetRecipient(1, "Patricia Loren", "AF:TBU/WGAM/PATL")
MAPI_DIALOG = 8
result = MAPISendMail(Session, 0, "Monthly Summary",\
    "We will quickly satisfy all orders for clamps.", MAPI_DIALOG, 0)
result = MAPILogoff(Session, 0, 0, 0)
End Sub