Edit

Office.SpamReportingEventCompletedOptions interface

  • Reference
Package:
outlook

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Specifies the behavior of an integrated spam-reporting add-in after it completes processing a SpamReporting event.

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// The following example handles a SpamReporting event to process a reported spam or phishing message.
function onSpamReport(event) {
    // Gets the Base64-encoded EML format of a reported message.
    Office.context.mailbox.item.getAsFileAsync({ asyncContext: event }, (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(`Error encountered during message processing: ${asyncResult.error.message}`);
            return;
        }

        // Run additional processing operations here.

        /**
        * Signals that the spam-reporting event has completed processing.
        * It then moves the reported message to a custom mailbox folder named "Reported Messages"
        * and shows a post-processing dialog to the user.
        * If an error occurs while the message is being processed, the `onErrorDeleteItem`
        * property determines whether the message will be deleted.
        */
        const event = asyncResult.asyncContext;
        event.completed({
            moveItemTo: Office.MailboxEnums.MoveSpamItemTo.CustomFolder,
            folderName: "Reported Messages",
            onErrorDeleteItem: true,
            showPostProcessingDialog: {
                title: "Contoso Spam Reporting",
                description: "Thank you for reporting this message.",
            },
        });
    });
}

Properties

folderName

When you use the completed method to signal that a reported message has finished processing, this property specifies the Outlook mailbox folder to which the message will be moved.
moveItemTo

When you use the completed method to signal that a reported message has finished processing, this property specifies whether the message is moved to a different folder in the mailbox.
onErrorDeleteItem

When set to true, deletes a reported message if an error occurs while the message is processed. If this property is set to false or isn't specified in the completed method, the reported message remains in its current mailbox folder.
postProcessingAction

When you use the completed method to signal that a reported message has finished processing, this property specifies whether the message is moved to a different folder in the mailbox. The following post-processing actions are available.

  • delete - Moves the reported message to the Deleted Items folder of the mailbox.

  • moveToCustomFolder - Moves the reported message to a specified folder. You must specify the name of the folder in the folderName property.

  • moveToSpamFolder - Moves the reported message to the Junk Email folder of the mailbox.

  • noMove - Leaves the reported message in its current folder.
showPostProcessingDialog

When you use the completed method to signal that a reported message has finished processing, this property indicates if a post-processing dialog is shown to the user. The JSON object assigned to this property must contain a title and a description. If this property isn't specified, a dialog isn't shown to the user once their reported message is processed.

Property Details

folderName

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

When you use the completed method to signal that a reported message has finished processing, this property specifies the Outlook mailbox folder to which the message will be moved.

folderName?: string;

Property Value

string

Remarks

[ API set: Mailbox preview ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

Important:

  • If the specified folder doesn't exist yet, it will be created before the message is moved.

  • If the postProcessingAction property is set to moveToCustomFolder, the folderName property must be specified. Otherwise, the reported message is moved to the Junk Email folder of the mailbox. If postProcessingAction is set to another action other than moveToCustomFolder, the folderName property is ignored.

moveItemTo

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

When you use the completed method to signal that a reported message has finished processing, this property specifies whether the message is moved to a different folder in the mailbox.

moveItemTo?: MailboxEnums.MoveSpamItemTo;

Property Value

Office.MailboxEnums.MoveSpamItemTo

Remarks

[ API set: Mailbox preview ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

Important:

  • You can only use this property in a spam-reporting add-in in Outlook on the web, on Windows (starting in Version 2308 (Build 16724.10000)), on Mac, and in new Outlook on Windows (preview). If you're using an earlier build in Outlook on Windows that supports the integrated spam-reporting feature, use the postProcessingAction property instead.

  • If the property is set to Office.MailboxEnums.MoveSpamItemTo.CustomFolder, you must specify the name of the folder to which the message will be moved in the folderName property of the event.completed call. Otherwise, the moveItemTo property will default to Office.MailboxEnums.MoveSpamItemTo.JunkFolder and move the reported message to the Junk Email folder.

onErrorDeleteItem

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

When set to true, deletes a reported message if an error occurs while the message is processed. If this property is set to false or isn't specified in the completed method, the reported message remains in its current mailbox folder.

onErrorDeleteItem?: boolean;

Property Value

boolean

Remarks

[ API set: Mailbox preview ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

postProcessingAction

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

When you use the completed method to signal that a reported message has finished processing, this property specifies whether the message is moved to a different folder in the mailbox. The following post-processing actions are available.

  • delete - Moves the reported message to the Deleted Items folder of the mailbox.

  • moveToCustomFolder - Moves the reported message to a specified folder. You must specify the name of the folder in the folderName property.

  • moveToSpamFolder - Moves the reported message to the Junk Email folder of the mailbox.

  • noMove - Leaves the reported message in its current folder.

postProcessingAction?: string;

Property Value

string

Remarks

[ API set: Mailbox preview ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

Important:

  • In Outlook on Windows, you can only use this property in earlier builds that support the integrated spam-reporting feature. If you're on Version 2308 (Build 16724.10000) or later, use the moveItemTo property instead.

  • This property isn't supported in Outlook on the web, on Mac, or in new Outlook on Windows (preview). Use the moveItemTo property instead.

  • If the property is set to moveToCustomFolder, you must specify the name of the folder to which the message will be moved in the folderName property of the event.completed call. Otherwise, the postProcessingAction property will default to moveToSpamFolder and move the reported message to the Junk Email folder.

Examples

// The following example handles a SpamReporting event to process a reported spam or phishing message.
function onSpamReport(event) {
    // Gets the Base64-encoded EML format of a reported message.
    Office.context.mailbox.item.getAsFileAsync({ asyncContext: event }, (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(`Error encountered during message processing: ${asyncResult.error.message}`);
            return;
        }

        // Run additional processing operations here.

        /**
        * Signals that the spam-reporting event has completed processing.
        * It then moves the reported message to the Junk Email folder of the mailbox and shows a
        * post-processing dialog to the user.
        */
        const event = asyncResult.asyncContext;
        event.completed({
            postProcessingAction: "moveToSpamFolder",
            showPostProcessingDialog: {
                title: "Contoso Spam Reporting",
                description: "Thank you for reporting this message.",
            },
        });
    });
}

showPostProcessingDialog

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

When you use the completed method to signal that a reported message has finished processing, this property indicates if a post-processing dialog is shown to the user. The JSON object assigned to this property must contain a title and a description. If this property isn't specified, a dialog isn't shown to the user once their reported message is processed.

showPostProcessingDialog?: object;

Property Value

object

Remarks

[ API set: Mailbox preview ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

Important: In Outlook on the web or in new Outlook on Windows (preview), a post-processing dialog isn't shown once the add-in completes processing a reported message. This applies even if showPostProcessingDialog is configured. However, depending on how you configured the moveItemTo property in the event.completed call, a notification is shown to signal when the reported message is deleted or moved to another folder in the mailbox. To learn more, see the "Review feature behavior and limitations" section of Implement an integrated spam-reporting add-in (preview).