Office.SpamReportingEventCompletedOptions interface

When you use the completed method to signal that a reported message has finished processing, this property specifies the ID of the task pane that opens after the message is processed.

commandId?: string;

Property Value

Remarks

[ API set: Mailbox 1.15 ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

Important:

• To learn how to implement the commandId property in your spam-reporting add-in, see Open a task pane after reporting a message.

• The commandId value must match the task pane ID specified in the manifest of your add-in. In the unified manifest for Microsoft 365, the ID is specified in the "id" property of the "extensions.ribbons.tabs.groups.controls" object that represents the task pane. In an add-in only manifest, the ID is specified in the id attribute of the Control element that represents the task pane.

• If you configure the commandId option in the event.completed call, a post-processing dialog isn't shown to the user even if the showPostProcessingDialog option is specified in the call.

• To ensure that the task pane of your spam-reporting add-in opens after a message is reported, you must set the moveItemTo option of the event.completed call to Office.MailboxEnums.MoveSpamItemTo.NoMove.

• If you implement a task pane to open after a reported message is processed, when the event.completed call occurs, any task pane that's open or pinned is closed.

Examples

function onSpamReport(event) {
    // Run operations to process the reported message.

    /**
     * Signals that the spam-reporting event has completed processing.
     * A task pane is opened instead of showing a post-processing dialog.
     * Context data is then passed to the task pane for processing.
     * To ensure that the task pane opens and receives the context data,
     * the reported message mustn't be moved from the folder in which it resides.
     */
    event.completed({
        commandId: "msgReadOpenPaneButton",
        contextData: JSON.stringify({ a: "aValue", b: "bValue" }),
        moveItemTo: Office.MailboxEnums.MoveSpamItemTo.NoMove
    });
}

When you use the completed method to signal that a reported message has finished processing, this property specifies any JSON data passed to the add-in's task pane after the message is processed.

contextData?: any;

Property Value

Remarks

[ API set: Mailbox 1.15 ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

Important:

• To learn how to implement the contextData property in your spam-reporting add-in, see Open a task pane after reporting a message.

• If you specify the contextData option in your event.completed call, you must also assign a task pane ID to the commandId option. Otherwise, the JSON data assigned to contextData is ignored.

• If you configure the commandId and contextData options in the event.completed call, a post-processing dialog isn't shown to the user even if the showPostProcessingDialog option is specified in the call.

• To ensure that the task pane of your spam-reporting add-in opens and receives context data after a message is reported, you must set the moveItemTo option of the event.completed call to Office.MailboxEnums.MoveSpamItemTo.NoMove.

• If you implement a task pane to open after a reported message is processed, when the event.completed call occurs, any task pane that's open or pinned is closed.

• To prevent the task pane of a spam-reporting add-in from relaunching if it's already open, implement a handler for the Office.EventType.InitializationContextChanged event. You can then pass the event arguments to the contextData property.

• To retrieve the value of the contextData property, you must call Office.context.mailbox.item.getInitializationContextAsync in the JavaScript implementation of your task pane. If you create a JSON string using JSON.stringify() and assign it to the contextData property, you must parse the string using JSON.parse() once you retrieve it.

Examples

function onSpamReport(event) {
    // Run operations to process the reported message.

    /**
     * Signals that the spam-reporting event has completed processing.
     * A task pane is opened instead of showing a post-processing dialog.
     * Context data is then passed to the task pane for processing.
     * To ensure that the task pane opens and receives the context data,
     * the reported message mustn't be moved from the folder in which it resides.
     */
    event.completed({
        commandId: "msgReadOpenPaneButton",
        contextData: JSON.stringify({ a: "aValue", b: "bValue" }),
        moveItemTo: Office.MailboxEnums.MoveSpamItemTo.NoMove
    });
}

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

Remarks

[ API set: Mailbox 1.14 ]

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.

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

Remarks

[ API set: Mailbox 1.14 ]

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 (new and classic (starting in Version 2308, Build 16724.10000)), and on Mac. If you're using an earlier build of classic 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.

• If you configure the commandId and contextData options in the event.completed call to open a task pane after a user selects the Report option from the preprocessing dialog, you must set the moveItemTo option to Office.MailboxEnums.MoveSpamItemTo.NoMove. Otherwise, the task pane won't open.

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

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

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

Remarks

[ API set: Mailbox 1.14 ]

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. 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.",
            },
        });
    });
}

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

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

Important: If you configure the commandId and contextData options in the event.completed call to open a task pane after a user selects the Report option from the preprocessing dialog, a post-processing dialog isn't shown to the user. This behavior applies even if the showPostProcessingDialog is specified in the event.completed call.