MAPI Report Messages
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Report messages present status information about a message to its sender.
There are two general types of report messages:
Read status reports.
Delivery status reports.
Read Status Reports
Read status reports are initiated by message store providers through a call to the IMAPISupport::ReadReceipt method and are sent to the recipient represented by the entry identifier in the PR_REPORT_ENTRYID (PidTagReportEntryId) property. Read status reports are not generated automatically; client applications that want to receive them must explicitly request them.
A read report indicates that the read flag of a message has been set, which can occur when the message is opened, printed, moved, or copied. Whether or not a message store provider generates a read report in response to a move or copy operation depends on where the message is going. If it is being moved or copied to another message store, a read report will most likely always be sent. If it is being moved or copied in the current message store, a read report might or might not be sent.
A nonread report indicates that the read flag of a message is not set and that the message was not opened either before being placed in the Deleted Items folder or before the expiration of a time limit. Clients can call the IMessage::SetReadFlag or IMAPIFolder::SetReadFlags method to set or clear a message's read flag.
Delivery Status Reports
Delivery status is reflected in a delivery report, which is sent when a message has reached its intended recipient, and in a nondelivery report, which is sent when a message could not reach a recipient. Delivery status reports are sent to the recipient represented by the entry identifier in the PR_REPORT_ENTRYID property or to the sender if this property is not present.
Delivery reports are sent by request only and do not include the original message. Nondelivery reports are sent automatically unless a request is made to suppress them. Nondelivery reports include the original message as an attachment to enable the report's recipient to resend the message in case whatever blocked the delivery is no longer a problem. The attached message resembles the original as it existed when the IMessage::SubmitMessage method was called to send it initially.
One or more delivery status reports are generated by transport providers when they call the IMAPISupport::StatusRecips method. Transport providers compose a list of recipients for a message. Whether or not a recipient receives a report and the type of report that is generated depends on the following:
Delivery reports go to recipients that set the PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED (PidTagOriginatorDeliveryReportRequested) property to TRUE before the message was placed in the message store.
Nondelivery reports go to recipients that did not set the PR_ORIGINATOR_NON_DELIVERY_REPORT_REQUESTED (PidTagOriginatorNonDeliveryReportRequested) property to FALSE.
Almost all of the information necessary to display a nondelivery report is contained in the recipient table of the attached message. A few properties are from the report itself. For delivery reports, the necessary information is contained in the recipient table of the report and in a few report properties.
Reports are messages with distinct message classes, based on the class of the sent message. Most service providers use a naming convention whereby the message class is composed of several parts separated by periods. The first part is "Report" and the last part is a constant that represents the report type. The middle part is reserved for the class of the sent message. For example, because a delivery report uses the constant DR, the message class for a delivery report about an IPM.Note message would be Report.IPM.Note.DR.
The following table shows the constants that represent the types of reports.
Report type |
Constant used in message class |
|---|---|
Read |
IPNRN |
Nonread |
IPNNRN |
Delivery |
DR |
Nondelivery |
NDR |
Interactive clients can display report messages by using standard forms provided by MAPI, or custom forms that have been registered with the form manager for the report's message class. Clients that receive a nondelivery report for an IPM.Note message, for example, can display the standard MAPI form that presents a list of the failed recipients and a suggested reason for the failure. The form also enables the user to resend the message, if desired.