MAPISendMail

The MAPISendMail function sends a message. This function differs from the MAPISendDocuments function in that it allows greater flexibility in message generation.

Quick Info

ULONG FAR PASCAL MAPISendMail(
  LHANDLE lhSession,         
  ULONG ulUIParam,           
  lpMapiMessage lpMessage,   
  FLAGS flFlags,             
  ULONG ulReserved           
)
 

Parameters

lhSession

[in] Handle to a Simple MAPI session or zero. If the value of the lhSession parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, the logon dialog box is displayed.

ulUIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpMessage

[in] Pointer to a MapiMessage structure containing the message to be sent. If the MAPI_DIALOG flag is not set, the nRecipCount and lpRecips members must be valid for successful message delivery. Client applications can set the flFlags member to MAPI_RECEIPT_REQUESTED to request a read report. All other members are ignored and unused pointers should be NULL.

flFlags

[in] Bitmask of option flags. The following flags can be set:

MAPI_DIALOG

A dialog box should be displayed to prompt the user for recipients and other sending options. When MAPI_DIALOG is not set, at least one recipient must be specified.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on. MAPISendMail ignores this flag if the lpszMessageID parameter is empty.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment's shared session. If the MAPI_NEW_SESSION flag is not set, MAPISendMail uses an existing shared session.

ulReserved

Reserved; must be zero.

Return Values

MAPI_E_AMBIGUOUS_RECIPIENT

A recipient matched more than one of the recipient descriptor structures and MAPI_DIALOG was not set. No message was sent.

MAPI_E_ATTACHMENT_NOT_FOUND

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

MAPI_E_ATTACHMENT_OPEN_FAILURE

The specified attachment could not be opened. No message was sent.

MAPI_E_BAD_RECIPTYPE

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

MAPI_E_FAILURE

One or more unspecified errors occurred. No message was sent.

MAPI_E_INSUFFICIENT_MEMORY

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

MAPI_E_INVALID_RECIPS

One or more recipients were invalid or did not resolve to any address.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was sent.

MAPI_E_TEXT_TOO_LARGE

The text in the message was too large. No message was sent.

MAPI_E_TOO_MANY_FILES

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

MAPI_E_TOO_MANY_RECIPIENTS

There were too many recipients. No message was sent.

MAPI_E_UNKNOWN_RECIPIENT

A recipient did not appear in the address list. No message was sent.

MAPI_E_USER_ABORT

The user canceled one of the dialog boxes. No message was sent.

SUCCESS_SUCCESS

The call succeeded and the message was sent.

Remarks

The MAPISendMail function sends a standard message, with or without any user interaction. The profile must be configured so that MAPISendMail can open the default service providers without requiring user interaction. However, if the flFlags parameter is set to MAPI_NEW_SESSION, disallowing the use of a shared session, and the profile requires a password, MAPI_LOGON_UI must be set or the function will fail. Client applications can avoid this situation by using an explicit profile without a password or by using the default profile without a password.

Client applications can provide a full or partial list of recipient names, subject text, file attachments, or message text. If any information is missing, MAPISendMail can prompt the user for it. If no information is missing, either the message can be sent as is or the user can be prompted to verify the information, changing values if necessary.

A successful return from MAPISendMail does not necessarily imply recipient validation. The message might not have been sent to all recipients. Depending on the transport provider, recipient validation can be a lengthy process.

A NULL value for the lpszSubject member of the MapiMessage structure pointed to by the lpMessage parameter indicates that there is no text for the subject of the message. A NULL value for the lpszNoteText member indicates that there is no message text. Some client applications can truncate subject lines that are too long or contain carriage returns, line feeds, or form feeds.

Each paragraph should be terminated with a CR (0x0d), an LF (0x0a), or a CRLF pair (0x0d0a). MAPISendMail wraps lines as appropriate. If the text exceeds system limits, the function returns the MAPI_E_TEXT_TOO_LARGE value.

The lpszMessageType member of the MapiMessage structure pointed to by lpMessage is used only by non-IPM applications. Applications that handle IPM messages can set it to NULL or have it point to an empty string.

The number of attachments per message can be limited in some messaging systems. If the limit is exceeded, the MAPI_E_TOO_MANY_FILES value is returned. If no files are specified, a pointer value of NULL should be assigned to the lpFiles member of the structure pointed to by lpMessage. File attachments are copied to the message before MAPISendMail returns; therefore, later changes to the files do not affect the contents of the message. The files must be closed when they are copied. Do not attempt to display attachments outside the range of the message text.

Some messaging systems can limit the number of recipients per message. A pointer value of NULL for the lpRecips member in the MapiMessage structure pointed to by lpMessage indicates no recipients. If the client application passes a non-NULL value indicating a number of recipients exceeding the system limit, MAPISendMail returns the MAPI_E_TOO_MANY_RECIPIENTS value. If the value of the nRecipCount member in the MapiMessage structure pointed to by lpMessage is 0, the MAPI_DIALOG flag must be present in the call to MAPISendMail.

Note that the lpRecips member in the MapiMessage structure can include either an entry identifier, the recipient's name, an address, or a name and address pair. The following table shows how MAPISendMail handles the variety of information that can be specified:

Client applications that send messages to custom recipients can avoid name resolution. Such clients should set the lpszAddress member of the MapiRecipDesc structure pointed to by the lpRecips member of the MapiMessage structure pointed to by the lpMessage parameter to the custom address.

MAPISendMail does not require an originator-type recipient to send a message.

See Also

MAPILogon, MapiMessage, MapiRecipDesc