Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer


This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Deletes one or more messages.

HRESULT DeleteMessages(
  ULONG_PTR ulUIParam,
  ULONG ulFlags


[in] A pointer to an ENTRYLIST structure that contains the number of messages to delete and an array of ENTRYID structures that identify the messages.


[in] A handle to the parent window of the progress indicator. The ulUIParam parameter is ignored unless the MESSAGE_DIALOG flag is set in the ulFlags parameter.


[in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the MESSAGE_DIALOG flag is set in the ulFlags parameter.


[in] A bitmask of flags that controls how the messages are deleted. The following flags can be set:


Permanently removes all messages, including soft-deleted ones.


Displays a progress indicator as the operation proceeds.


The specified message or messages were successfully deleted.


The call succeeded, but not all of the messages were successfully deleted. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

The IMAPIFolder::DeleteMessages method deletes messages from a folder. Messages that do not exist, that have been moved elsewhere, that are open with read/write permission, or that are currently submitted cannot be deleted.

When the delete operation involves more than one message, perform the operation as completely as possible for each folder, even if one or more of the messages cannot be deleted. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

Expect these return values under the following conditions.


Return value

DeleteMessages has successfully deleted every message.


DeleteMessages was unable to successfully delete every message and subfolder.


DeleteMessages was unable to complete.

Any error value except MAPI_E_NOT_FOUND

When DeleteMessages is unable to complete, do not assume that no work was done. DeleteMessages might have been able to delete one or more of the messages before encountering the error.

DeleteMessages returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store's implementation.

For MFCMAPI sample code, see the following table.






MFCMAPI uses the IMAPIFolder::DeleteMessages method to delete the specified messages.

© 2015 Microsoft