Platform SDK: MAPI |
The MAPISendMail function sends a message. This function differs from the MAPISendDocuments function in that it allows greater flexibility in message generation.
Header file: | MAPI.H |
ULONG FAR PASCAL MAPISendMail( LHANDLE lhSession, ULONG ulUIParam, lpMapiMessage lpMessage, FLAGS flFlags, ULONG ulReserved )
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:
Information | Action |
---|---|
entry identifier | No name resolution; the name and address are ignored. |
name | Name resolved using the Simple MAPI resolution rules. |
address | No name resolution; address is used for both message delivery and for displaying the recipient name. |
name and address | No name resolution; name used only for displaying the recipient name. |
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.