MAPISENDMAILW callback function (mapi.h)
Sends a Unicode message. This function replaces the ANSI function MAPISendMail.
On Windows 7 and earlier: Install the Microsoft Windows Software Development Kit (SDK) for Windows 8 and use MAPISendMailHelper to send a message.
All information applies to both MAPISendMailW and MAPISendMail unless otherwise specified.
Syntax
MAPISENDMAILW Mapisendmailw;
ULONG Mapisendmailw(
[in] LHANDLE lhSession,
[in] ULONG_PTR ulUIParam,
[in] lpMapiMessageW lpMessage,
[in] FLAGS flFlags,
ULONG ulReserved
)
{...}
Parameters
[in] lhSession
Type: LHANDLE
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.
[in] ulUIParam
Type: ULONG_PTR
Parent window handle or zero.
If the ulUIParam parameter contains the parent window handle, the handle is type HWND (cast to a ULONG_PTR).
If no dialog box is displayed during the call, ulUIParam is ignored.
[in] lpMessage
Type: lpMapiMessageW
Pointer to a MAPISendMailW structure containing the message to be sent.
| Member | Notes |
|---|---|
| lpFiles | Set this member to NULL when the message does not have file attachments. |
| lpszMessageType | Used by applications that do not handle interpersonal messages. If your application handles interpersonal messages, set the lpszMessageType member to NULL or set it to point to an empty string. |
| lpszSubject | A value of NULL means that there is no text for the subject of the message. |
| lpszNoteText | A value of NULL means that there is no text in the body of the message. |
| lpRecips | A value of NULL means that there are no recipients. Additionally, when this member is NULL, the nRecipCount member must be zero. |
| nRecipCount | A value of zero means that there are no recipients. Additionally, when this member is zero, the lpRecips member must be NULL. |
For more details about how the function handles recipient information, see Handling Recipient Information in Remarks.
[in] flFlags
Type: FLAGS
Bitmask of option flags. The following flags can be set.
| Value | Meaning |
|---|---|
|
A application modal dialog box should be displayed to prompt the user for recipients and other sending options.
If neither MAPI_DIALOG nor MAPI_DIALOG_MODELESS is set, at least one recipient must be specified. |
|
Available on Windows with next version of Office: A modeless dialog box should be displayed to prompt the user for recipients and other sending options. If MAPI_DIALOG_MODELESS is set, the lhSession parameter should be set to zero. Otherwise, if this flag is set and lhSession is not zero, Outlook will raise an exception. Additionally, if MAPI_DIALOG_MODELESS is set, the system ignores the MAPI_NEW_SESSION flag. If neither MAPI_DIALOG nor MAPI_DIALOG_MODELESS is set, at least one recipient must be specified. Tip To use this flag on Windows 7 or earlier you must have both Windows SDK for Windows 8 and next version of Office installed, and you must call MAPISendMailHelper instead of MAPISendMailW.
|
|
A dialog box should be displayed to prompt the user to log on if required.
If 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. If the lpszMessageID parameter is empty, the MAPI_LOGON_UI flag is ignored. |
|
An attempt is made to create a new session rather than acquire the environment's shared session. If the MAPI_NEW_SESSION flag is not set, the function uses an existing, shared session.
If you set the MAPI_NEW_SESSION flag (preventing the use of a shared session) and the profile requires a password, you must also set the MAPI_LOGON_UI flag or the function will fail. Your client application can avoid this failure by using the default profile without a password or by using an explicit profile without a password. |
|
Do not convert the message to ANSI if the provider does not support Unicode.
Note This flag is available for MAPISendMailW only.
|
ulReserved
Type: ULONG
Reserved; must be zero.
Return value
Type: ULONG
This function returns one of the following values.
| Return code/value | Description |
|---|---|
|
A recipient matched more than one of the recipient descriptor structures and MAPI_DIALOG was not set. No message was sent. |
|
The specified attachment was not found. No message was sent. |
|
The specified attachment could not be opened. No message was sent. |
|
The specified attachment was too large. No message was sent. |
|
The type of a recipient was not MAPI_TO, MAPI_CC, or MAPI_BCC. No message was sent. |
|
One or more unspecified errors occurred. No message was sent. |
|
There was insufficient memory to proceed. No message was sent. |
|
One or more recipients were invalid or did not resolve to any address. |
|
There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was sent. |
|
The text in the message was too large. No message was sent. |
|
There were too many file attachments. No message was sent. |
|
There were too many recipients. No message was sent. |
|
The MAPI_FORCE_UNICODE flag is specified and Unicode is not supported.
Note This value can be returned by MAPISendMailW only.
|
|
A recipient did not appear in the address list. No message was sent. |
|
The user canceled one of the dialog boxes. No message was sent. |
|
The call succeeded and the message was sent. |
Remarks
The MAPISendMailW (Unicode) and MAPISendMail (ANSI) functions both send a standard message, with or without any user interaction. The profile must be configured so that either function can open the default service providers without requiring user interaction.
Neither MAPISendMailW nor MAPISendMail requires an originator-type recipient to send a message.
Your client application can provide a full or partial list of recipient names, subject text, file attachments, or message text. If any information is missing, the function you call (either MAPISendMailW or MAPISendMail) can prompt the user for the missing information.
If no information is missing, the message can be sent as is or the user can be prompted to verify the information and change values if necessary.
Both MAPISendMailW and MAPISendMail differ from the MAPISendDocuments function in that they allow greater flexibility in message generation.
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). Both MAPISendMailW and MAPISendMail wrap lines as appropriate.
If the text exceeds system limits, the function returns the MAPI_E_TEXT_TOO_LARGE value.
File attachments
The number of attachments per message can be limited in some messaging systems. If this limit is exceeded, the function fails and returns the MAPI_E_TOO_MANY_FILES value.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.
Do not attempt to display attachments outside the range of the message text.
Recipients
Some messaging systems can limit the number of recipients per message. If the client application passes a non-NULL value indicating a number of recipients exceeding the system limit, the function fails and returns the MAPI_E_TOO_MANY_RECIPIENTS value.If your client application sends messages to one or more custom recipients and you want to avoid resolving the names of those recipients, you must specify the address of the custom recipient.
To specify an address of a recipient when you call MAPISendMailW, you must set the lpszAddress member of the MapiRecipDescW structure that contains the recipient's information to the custom address. This MapiRecipDescW structure is included in the array of recipients stored in the lpRecips member of the MapiMessageW structure that is passed to the function by the lpMessage parameter.
A successful return from the function 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.
Handling recipient information
The lpRecips member of the MapiMessageW or 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 the function handles each case.| Recipient 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. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 [desktop apps only] |
| Minimum supported server | Windows Server 2012 [desktop apps only] |
| Target Platform | Windows |
| Header | mapi.h |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for