Edit

Share via

Office.SpamReportingEventCompletedOptions interface

  • Reference
Package:
outlook

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

Remarks

[ API set: Mailbox 1.14 ]

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

commandId

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.
contextData

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.
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

commandId

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

string

Remarks

[ API set: Mailbox 1.15 ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

Important:

  • To learn how to implement this 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 an add-in only manifest, the ID is specified in the id attribute of the Control element that represents the task pane. The commandId property isn't currently supported in a spam-reporting add-in that uses a unified manifest for Microsoft 365.

  • 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
    });
}

contextData

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

any

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 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
    });
}

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.

folderName?: string;

Property Value

string

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.

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.

moveItemTo?: MailboxEnums.MoveSpamItemTo;

Property Value

Office.MailboxEnums.MoveSpamItemTo

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.

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.

onErrorDeleteItem?: boolean;

Property Value

boolean

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read

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.

postProcessingAction?: string;

Property Value

string

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

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.

showPostProcessingDialog?: object;

Property Value

object

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): read item

Applicable Outlook mode: Message Read