Прочетете на английски Редактиране

Споделяне чрез

Implement an integrated spam-reporting add-in

  • Статия

With the number of unsolicited emails on the rise, security is at the forefront of add-in usage. Currently, partner spam-reporting add-ins are added to the Outlook ribbon, but they usually appear towards the end of the ribbon or in the overflow menu. This makes it harder for users to locate the add-in to report unsolicited emails. In addition to configuring how messages are processed when they're reported, developers also need to complete additional tasks to show processing dialogs or supplemental information to the user.

The integrated spam-reporting feature eases the task of developing individual add-in components from scratch. More importantly, it displays your add-in in a prominent spot on the Outlook ribbon, making it easier for users to locate it and report spam messages. Implement this feature in your add-in to:

  • Improve how unsolicited messages are tracked.
  • Provide better guidance to users on how to report suspicious messages.
  • Enable an organization's security operations center (SOC) or IT administrators to easily perform spam and phishing simulations for educational purposes.

Бележка

Integrated spam reporting was introduced in Mailbox requirement set 1.14. For information on client support for this feature, see Supported clients.

Supported clients

The following table identifies which Outlook clients support the integrated spam-reporting feature.

Client Status
Outlook on the web Supported*
new Outlook on Windows Supported*
classic Outlook on Windows
Version 2404 (Build 17530.15000)		 Supported
Outlook on Mac
Version 16.81 (23121700) or later		 Preview (see Preview the integrated spam-reporting feature in Outlook on Mac)
Outlook on Android Not available
Outlook on iOS Not available

Бележка

* In Outlook on the web and the new Outlook on Windows, the integrated spam-reporting feature isn't supported for Microsoft 365 consumer accounts.

Preview the integrated spam-reporting feature in Outlook on Mac

To preview the integrated spam-reporting feature in Outlook on Mac, you must install Version 16.81.1217.0 or later. Then, join the Microsoft 365 Insider program and select the Beta Channel option to access Office beta builds.

Set up your environment

Съвет

To immediately try out a completed spam-reporting add-in solution, see the Report spam or phishing emails in Outlook sample.

Complete the Outlook quick start, which creates an add-in project with the Yeoman generator for Office Add-ins.

Configure the manifest

To implement the integrated spam-reporting feature in your add-in, you must configure the following in your manifest.

  • The runtime used by the add-in. In classic Outlook on Windows, a spam-reporting add-in runs in a JavaScript-only runtime. In Outlook on the web and on Mac and in the new Outlook on Windows, a spam-reporting add-in runs in a browser runtime. For more information, see Runtimes in Office Add-ins.

  • The button of the spam-reporting add-in that always appears in a prominent spot on the Outlook ribbon. The following is an example of how the button of a spam-reporting add-in appears on the ribbon of the classic Outlook client on Windows. The ribbon UI may vary depending on the platform the user's Outlook client is running on.

    A sample ribbon button of a spam-reporting add-in.

  • The preprocessing dialog. When a user selects the add-in button, a dialog appears with Report and Don't Report options. In this dialog, you can share information about the reporting process or implement input options to get information about a reported message. Input options include checkboxes, radio buttons (preview), and a text box. When a user selects Report from the dialog, the SpamReporting event is activated and is then handled by the JavaScript event handler. The following is an example of a preprocessing dialog in Outlook on Windows. Note that the appearance of the dialog may vary depending on the platform the user's Outlook client is running on.

    A sample preprocessing dialog of a spam-reporting add-in.

Select the tab for the type of manifest you're using.

Бележка

  1. In your preferred code editor, open the add-in project you created.

  2. Open the manifest.json file.

  3. Add the following object to the "extensions.runtimes" array. Note the following about this markup.

    • The "minVersion" of the Mailbox requirement set is configured to "1.14". This is the lowest version of the requirement set that supports the integrated spam-reporting feature.
    • The "id" of the runtime is set to a unique descriptive name, "spam_reporting_runtime".
    • The "code" property has a child "page" property that's set to an HTML file and a child "script" property that's set to a JavaScript file. You'll create or edit these files in later steps.
    • The "lifetime" property is set to "short". This means that the runtime starts when the SpamReporting event occurs and shuts down when the event handler completes.
    • The "actions" object specifies the event handler function that runs in the runtime. You'll create this function in a later step.
    JSON 
    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.14"
            }
        ]
    },
    "id": "spam_reporting_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/spamreporting.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onSpamReport",
            "type": "executeFunction"
        }
    ]
},

  4. Add the following object to the "extensions.ribbons" array. Note the following about this markup.

    • The "contexts" array contains the "spamReportingOverride" string. This prevents the add-in button from appearing at the end of the ribbon or in the overflow section.
    • The "tabs" array must be specified in an "extensions.ribbons" object. However, because the button of a spam-reporting add-in is displayed in a specific spot on the ribbon, only an empty array is specified.
    • The "fixedControls" array contains an object that configures the look and functionality of the add-in button on the ribbon. The name of the event handler specified in the "actionId" property must match the value used in the "id" property of the object in the "actions" array. While the "enabled" property must be specified in the array, its value doesn't affect the functionality of a spam-reporting add-in.
    • The "spamPreProcessingDialog" object specifies the information and options that are shown in the preprocessing dialog. While you must specify a "title" and "description" for the dialog, you can optionally configure the following properties.
      • The "spamReportingOptions" object. It provides a multiple-selection list of up to five choices. This helps a user identify the type of message they're reporting.
      • The "spamFreeTextSectionTitle" property. It provides a text box for the user to add more information about the message they're reporting.
      • The "spamMoreInfo" object. It includes a link in the dialog to provide informational resources to the user.
    JSON 
    {
    "contexts": [
        "spamReportingOverride"
    ],
    "tabs": [],
    "fixedControls": [
        {
            "id": "spamReportingButton",
            "type": "button",
            "label": "Report Spam Message",
            "enabled": false,
            "icons": [
                {
                    "size": 16,
                    "url": "https://localhost:3000/assets/icon-16.png"
                },
                {
                    "size": 32,
                    "url": "https://localhost:3000/assets/icon-32.png"
                },
                {
                    "size": 80,
                    "url": "https://localhost:3000/assets/icon-80.png"
                }
            ],
            "supertip": {
                "title": "Report Spam Message",
                "description": "Report an unsolicited message."
            },
            "actionId": "onSpamReport"
        }
    ],
    "spamPreProcessingDialog": {
        "title": "Report Spam Message",
        "description": "Thank you for reporting this message.",
        "spamReportingOptions": {
            "title": "Why are you reporting this email?",
            "options": [
                "Received spam email.",
                "Received a phishing email.",
                "I'm not sure this is a legitimate email."
            ]
        },
        "spamFreeTextSectionTitle": "Provide additional information, if any:",
        "spamMoreInfo": {
            "text": "Reporting unsolicited messages",
            "url": "https://www.contoso.com/spamreporting"
        }
    }
},

  5. Save your changes.

Съвет

To learn more about manifests for Outlook add-ins, see Office Add-ins manifest.

Implement the event handler

When your add-in is used to report a message, it generates a SpamReporting event, which is then processed by the event handler in the JavaScript file of your add-in. To map the name of the event handler you specified in your manifest to its JavaScript counterpart, you must call Office.actions.associate in your code.

  1. In your add-in project, navigate to the ./src directory. Then, create a new folder named spamreporting.

  2. In the ./src/spamreporting folder, create a new file named spamreporting.js.

  3. Open the newly created spamreporting.js file and add the following JavaScript code.

    JavaScript 
    // Handles the SpamReporting event to process a reported message.
function onSpamReport(event) {
  // TODO - Send a copy of the reported message.

  // TODO - Get the user's responses.

  // TODO - Signal that the spam-reporting event has completed processing.
}

// IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onSpamReport", onSpamReport);

  4. Save your changes.

Forward a copy of the message and get the preprocessing dialog responses

Your event handler is responsible for processing the reported message. You can configure it to forward information, such as a copy of the message or the options selected by the user in the preprocessing dialog, to an internal system for further investigation.

To efficiently send a copy of the reported message, call the getAsFileAsync method in your event handler. This gets the Base64-encoded EML format of a message, which you can then forward to your internal system.

If you need to keep track of the user's responses to the options and text box in the preprocessing dialog, extract the options and freeText values from the SpamReporting event object. For more information about these properties, see Office.SpamReportingEventArgs.

The following is an example of a spam-reporting event handler that calls the getAsFileAsync method and gets the user's responses from the SpamReporting event object.

  1. In the spamreporting.js file, replace its contents with the following code.

    JavaScript 
    // Handles the SpamReporting event to process a reported message.
function onSpamReport(event) {
  // Get 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;
    }

    // Get the user's responses to the options and text box in the preprocessing dialog.
    const spamReportingEvent = asyncResult.asyncContext;
    const reportedOptions = spamReportingEvent.options;
    const additionalInfo = spamReportingEvent.freeText;

    // Run additional processing operations here.

    // TODO - Signal that the spam-reporting event has completed processing.
  });
}

// IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onSpamReport", onSpamReport);

  2. Save your changes.

Бележка

To configure single sign-on (SSO) or cross-origin resource sharing (CORS) in your spam-reporting add-in, you must add your add-in and its JavaScript file to a well-known URI. For guidance on how to configure this resource, see Use single sign-on (SSO) or cross-origin resource sharing (CORS) in your event-based or spam-reporting Outlook add-in.

Signal when the event has been processed

Once the event handler has completed processing the message, it must call the event.completed method. In addition to signaling to the add-in that the spam-reporting event has been processed, event.completed can also be used to do the following:

For a list of properties you can include in a JSON object to pass as a parameter to the event.completed method, see Office.SpamReportingEventCompletedOptions.

Бележка

Code added after the event.completed call isn't guaranteed to run.

  1. In the spamreporting.js file, replace its contents with the following code.

    JavaScript 
    // Handles the SpamReporting event to process a reported message.
function onSpamReport(event) {
  // Get 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;
    }

    // Get the user's responses to the options and text box in the preprocessing dialog.
    const spamReportingEvent = asyncResult.asyncContext;
    const reportedOptions = spamReportingEvent.options;
    const additionalInfo = spamReportingEvent.freeText;

    // 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, then
     * 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({
      onErrorDeleteItem: true,
      moveItemTo: Office.MailboxEnums.MoveSpamItemTo.JunkFolder,
      showPostProcessingDialog: {
        title: "Contoso Spam Reporting",
        description: "Thank you for reporting this message.",
      },
    });
  });
}

// IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart
Office.actions.associate("onSpamReport", onSpamReport);

    Бележка

    If you're on classic Outlook on Windows Version 2308 (Build 16724.10000) or later, Outlook on Mac, Outlook on the web, or the new Outlook on Windows, you must use the moveItemTo property in the event.completed call to specify the folder to which a reported message is moved once it's processed by your add-in. On earlier Outlook builds on Windows that support the integrated spam-reporting feature, you must use the postProcessingAction property.

  2. Save your changes.

The following is a sample post-processing dialog shown to the user once the add-in completes processing a reported message in Outlook on Windows. Note that the appearance of the dialog may vary depending on the platform the user's Outlook client is running on.

A sample of a post-processing dialog shown once a reported spam message has been processed by the add-in.

Съвет

As you develop a spam-reporting add-in that will run in Outlook on Windows, keep the following in mind.

  • Imports aren't currently supported in the JavaScript file that contains the code to handle the spam-reporting event.
  • Code included in the Office.onReady() and Office.initialize functions won't run. You must add any add-in startup logic, such as checking the user's Outlook version, to your event handlers instead.

Update the commands HTML file

  1. In the ./src/commands folder, open commands.html.

  2. Immediately before the closing head tag (</head>), add the following script entry.

    HTML 
    <script type="text/javascript" src="../spamreporting/spamreporting.js"></script>

    Бележка

    The integrated spam-reporting feature is currently in preview in Outlook on Mac. If you're testing the feature in this client, you must include a reference to the preview version of the Office JavaScript API in your commands.html file.

    HTML 
    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>
<script type="text/javascript" src="../spamreporting/spamreporting.js"></script>

  3. Save your changes.

Update the webpack config settings

  1. From the root directory of your add-in project, open the webpack.config.js file.

  2. Locate the plugins array within the config object and add this new object to the beginning of the array.

    JavaScript 
    new CopyWebpackPlugin({
  patterns: [
    {
      from: "./src/spamreporting/spamreporting.js",
      to: "spamreporting.js",
    },
  ],
}),

  3. Save your changes.

Test and validate your add-in

  1. Sideload the add-in in a supported Outlook client.
  2. Choose a message from your inbox, then select the add-in's button from the ribbon.
  3. In the preprocessing dialog, choose a reason for reporting the message and add information about the message, if configured. Then, select Report.
  4. (Optional) In the post-processing dialog, select OK.

Suppress the preprocessing dialog (preview)

Бележка

The "Don't show me this message again" option is currently in preview in Outlook on the web and on Windows (new and classic). To preview this feature in classic Outlook on Windows, install Version 2411 (Build 18227.20034) or later. Then, join the Microsoft 365 Insider program and select the Beta Channel option.

Depending on your scenario, you might not need a user to provide additional information about a message they're reporting. If the preprocessing dialog of your spam-reporting add-in only provides information to the user, you can choose to include a "Don't show me this message again" option in the dialog.

The 'Don't show me this message again' option in the preprocessing dialog.

To implement this in your add-in, you must specify the NeverShowAgainOption element in your manifest and set it to true. The following code is an example.

XML 
...
    <PreProcessingDialog>
      <Title resid="PreProcessingDialog.Label"/>
      <Description resid="PreProcessingDialog.Text"/>
      <NeverShowAgainOption>true</NeverShowAgainOption>
      <MoreInfo>
        <MoreInfoText resid="MoreInfo.Label"/>
        <MoreInfoUrl resid="MoreInfo.Url"/>
      </MoreInfo>
    </PreProcessingDialog>
...

Note the following behaviors when implementing this option in your add-in.

  • The "Don't show me this message again" option appears in the preprocessing dialog only if there are no user input options configured, such as reporting options or a text box. If your manifest also specifies user input options, they'll be shown in the dialog instead.

  • The option to suppress the preprocessing dialog is applied on a per-machine and per-platform basis.

  • After suppressing the preprocessing dialog, if a user reports a message and has the Reading Pane turned on, a progress notification is shown on the message while it's being processed. If the Reading Pane is turned off, no progress notification is shown.

    The progress notification shown after reporting a message while the Reading Pane is turned on.

    Бележка

    If you implement the "Don't show me this message again" option without configuring a post-processing dialog, a dialog with the following generic message is shown to the user after processing: "Thank you for reporting this message." It's good practice to configure a post-processing dialog to appear after a reported message is processed.

Reenable the preprocessing dialog

To reenable the preprocessing dialog in classic Outlook on Windows after selecting the "Don't show me this message again" option, perform the following steps.

  1. Open the Registry Editor as an administrator.
  2. Navigate to HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Outlook\Options\WebExt\SpamDialog.
  3. Locate your spam-reporting add-in using its ID specified in the manifest.
  4. Delete the entry of your add-in from the registry.

The preprocessing dialog will appear the next time a message is reported.

Open a task pane after reporting a message (preview)

Бележка

The option to implement a task pane from the event.completed method is currently in preview in Outlook on the web and on Windows (new and classic). To preview this feature in classic Outlook on Windows, install Version 2411 (Build 18227.20034) or later. Then, join the Microsoft 365 Insider program and select the Beta Channel option.

Instead of a post-processing dialog, you can implement a task pane to open after a user reports a message. For example, you can use the task pane to show additional information based on the user's input in the preprocessing dialog. Similar to the post-processing dialog, the task pane is implemented through the add-in's event.completed call.

Бележка

If both the post-processing dialog and task pane capabilities are configured in the event.completed call, the task pane is shown instead of the dialog.

To configure a task pane to open after a message is reported, you must specify the ID of the task pane in the commandId option of the event.completed call. The ID must match the value specified in the id attribute of the Control element that represents the task pane in the manifest.

If you need to pass information to the task pane, specify any JSON data in the contextData option of the event.completed call. To retrieve the value of the contextData option, you must call Office.context.mailbox.item.getInitializationContextAsync in the JavaScript implementation of your task pane.

Важно

To ensure that the task pane of the 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.

The following code is an example.

JavaScript 
...
    event.completed({
      commandId: "msgReadOpenPaneButton",
      contextData: JSON.stringify({ a: "aValue", b: "bValue" }),
      moveItemTo: Office.MailboxEnums.MoveSpamItemTo.NoMove
    });

If another task pane is open or pinned at the time a message is reported, the open task pane is closed then the task pane of the spam-reporting add-in is shown.

Review feature behavior and limitations

As you develop and test the integrated spam-reporting feature in your add-in, be mindful of its characteristics and limitations.

  • In Outlook on the web and on Windows (new and classic), an integrated spam-reporting add-in replaces the native Report button in the Outlook ribbon. If multiple spam-reporting add-ins are installed, they will all appear in the Report section of the ribbon.

    A sample integrated spam-reporting add-in that replaces the Report button in the Outlook ribbon.

  • A spam-reporting add-in can run for a maximum of five minutes once it's activated. Any processing that occurs beyond five minutes will cause the add-in to time out. If the add-in times out, a dialog will be shown to the user to notify them of this.

    The dialog shown when a spam-reporting add-in times out.

  • In classic Outlook on Windows, a spam-reporting add-in can be used to report a message even if the Reading Pane of the Outlook client is turned off. In Outlook on the web, on Mac, and in new Outlook on Windows, the spam-reporting add-in can be used if the Reading Pane is turned on or the message to be reported is open in another window.

  • Only one message can be reported at a time. If you select multiple messages to report, the button of the spam-reporting add-in becomes unavailable.

  • In classic Outlook on Windows, only one reported message can be processed at a time. If a user attempts to report another message while the previous one is still being processed, a dialog will be shown to notify them of this.

    The dialog shown when the user attempts to report another message while the previous one is still being processed.

    This doesn't apply to Outlook on the web or on Mac, or to the new Outlook on Windows. In these Outlook clients, a user can report a message from the Reading Pane and can simultaneously report each message that's open in a separate window.

  • The add-in can still process the reported message even if the user navigates away from the selected message. In Outlook on Mac, this is only supported if a user reports a message while it's open in a separate window. If the user reports a message while viewing it from the Reading Pane and then navigates away from it, the reporting process is terminated.

  • In Outlook on the web and the new Outlook on Windows, if a message is reported while it's open in a separate window, a post-processing dialog isn't shown to the user.

  • The buttons that appear in the preprocessing and post-processing dialogs aren't customizable. Additionally, the text and buttons in the timeout and ongoing report dialogs can't be modified.

  • The integrated spam-reporting and event-based activation features must use the same runtime. Multiple runtimes aren't currently supported in Outlook. To learn more about runtimes, see Runtimes in Office Add-ins.

  • A spam-reporting add-in only implements function commands. A task pane command can't be assigned to the spam-reporting button on the ribbon. If you want to implement a task pane in your add-in, you must configure it in your manifest as follows:

    Note that a separate button to activate the task pane will be added to the ribbon, but it won't appear in the dedicated spam-reporting area of the ribbon.

Troubleshoot your add-in

As you develop your spam-reporting add-in, you might need to troubleshoot issues, such as your add-in not loading. For guidance on how to troubleshoot a spam-reporting add-in, see Troubleshoot event-based and spam-reporting add-ins.

See also