Redigera

Implement an integrated spam-reporting add-in (preview)

  • Artikel

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.

Important

The integrated spam-reporting feature is currently in preview in Outlook on Windows, on Mac, on the web, and in new Outlook on Windows (preview). Features in preview shouldn't be used in production add-ins. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the Feedback section at the end of this page).

Preview the integrated spam-reporting feature

To preview the integrated spam-reporting feature, you must have one of the following supported clients.

Tip

If you're unable to choose a channel in your Outlook client on Windows, see Let users choose which Microsoft 365 Insider channel to install on Windows devices.

Set up your environment

Tip

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

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

Configure the manifest

Note

Integrated spam reporting isn't yet supported for the unified manifest for Microsoft 365.

To implement the integrated spam-reporting feature in your add-in, you must configure the VersionOverridesV1_1 node of your manifest accordingly.

  • In Outlook on the web and on Mac and in the new Outlook on Windows, an add-in that implements the integrated spam-reporting feature runs in a browser runtime. You must specify the HTML file that references or contains the code to handle the spam-reporting event in the resid attribute of the Runtime element.
  • In Outlook on Windows, an add-in that implements the integrated spam-reporting feature runs in a JavaScript-only runtime. As such, you must specify the JavaScript file that contains the code to handle the spam-reporting event in the Override child element of the <Runtime> element.
  • To activate the add-in in the Outlook ribbon and prevent it from appearing at the end of the ribbon or in the overflow section, set the xsi:type attribute of the <ExtensionPoint> element to ReportPhishingCommandSurface.
  • To customize the ribbon button and preprocessing dialog, you must define the ReportPhishingCustomization node.

    • A user reports an unsolicited message through the add-in's button in the ribbon. To configure the ribbon button, set the xsi:type attribute of the Control element to Button. Then, set the xsi:type attribute of the Action child element to ExecuteFunction and specify the name of the spam-reporting event handler in its <FunctionName> child element. A spam-reporting add-in can only implement function commands.

      The following is an example of how the button of a spam-reporting add-in appears on the ribbon of the 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 is shown to a user when they select the add-in button. It's configured through the PreProcessingDialog element of your manifest. While the dialog must have a title and description, you can optionally include the following elements.

      • A multiple-selection list of choices to help a user identify the type of message they're reporting. To learn how to configure these reporting options, see ReportingOptions element.
      • A text box for the user to provide additional information about the message they're reporting. To learn how to implement a text box, see FreeTextLabel element.
      • Custom text and URL to provide informational resources to the user. To learn how to personalize these elements, see MoreInfo element.

      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.

The following is an example of a <VersionOverrides> node configured for spam reporting.

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

  2. Open the manifest.xml file located at the root of your project.

  3. Select the entire <VersionOverrides> node (including the open and close tags) and replace it with the following code.

    <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.13">
        <bt:Set Name="Mailbox"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <Runtimes>
            <!-- References the HTML file that links to the spam-reporting event handler.
                 This is used by Outlook on the web and on the new Mac UI, and new Outlook on Windows (preview). -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the spam-reporting event handler. This is used by Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="WebViewRuntime.Url"/>
          <!-- Implements the integrated spam-reporting feature in the add-in. -->
          <ExtensionPoint xsi:type="ReportPhishingCommandSurface">
            <ReportPhishingCustomization>
              <!-- Configures the ribbon button. -->
              <Control xsi:type="Button" id="spamReportingButton">
                <Label resid="spamButton.Label"/>
                <Supertip>
                  <Title resid="spamButton.Label"/>
                  <Description resid="spamSuperTip.Text"/>
                </Supertip>
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16"/>
                  <bt:Image size="32" resid="Icon.32x32"/>
                  <bt:Image size="80" resid="Icon.80x80"/>
                </Icon>
                <Action xsi:type="ExecuteFunction">
                  <FunctionName>onSpamReport</FunctionName>
                </Action>
              </Control>
              <!-- Configures the preprocessing dialog. -->
              <PreProcessingDialog>
                <Title resid="PreProcessingDialog.Label"/>
                <Description resid="PreProcessingDialog.Text"/>
                <ReportingOptions>
                  <Title resid="OptionsTitle.Label"/>
                  <Option resid="Option1.Label"/>
                  <Option resid="Option2.Label"/>
                  <Option resid="Option3.Label"/>
                </ReportingOptions>
                <FreeTextLabel resid="FreeText.Label"/>
                <MoreInfo>
                  <MoreInfoText resid="MoreInfo.Label"/>
                  <MoreInfoUrl resid="MoreInfo.Url"/>
                </MoreInfo>
              </PreProcessingDialog>
             <!-- Identifies the runtime to be used. This is also referenced by the Runtime element. -->
              <SourceLocation resid="WebViewRuntime.Url"/>
            </ReportPhishingCustomization> 
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html"/>
        <bt:Url id="JSRuntime.Url" DefaultValue="https://localhost:3000/spamreporting.js"/>
        <bt:Url id="MoreInfo.Url" DefaultValue="https://www.contoso.com/spamreporting"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="spamButton.Label" DefaultValue="Report Spam Message"/>
        <bt:String id="PreProcessingDialog.Label" DefaultValue="Report Spam Message"/>
        <bt:String id="OptionsTitle.Label" DefaultValue="Why are you reporting this email?"/>
        <bt:String id="FreeText.Label" DefaultValue="Provide additional information, if any:"/>
        <bt:String id="MoreInfo.Label" DefaultValue="To learn more about reporting unsolicited messages, see "/>
        <bt:String id="Option1.Label" DefaultValue="Received spam email."/>
        <bt:String id="Option2.Label" DefaultValue="Received a phishing email."/>
        <bt:String id="Option3.Label" DefaultValue="I'm not sure this is a legitimate email."/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="spamSuperTip.Text" DefaultValue="Report an unsolicited message."/>
        <bt:String id="PreProcessingDialog.Text" DefaultValue="Thank you for reporting this message."/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</VersionOverrides>

  4. Save your changes.

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 the <FunctionName> element of 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.

    // 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 the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  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.

Important

To test the getAsFileAsync method while it's still in preview in Outlook on Windows, you must configure your computer's registry.

Outlook on Windows includes a local copy of the production and beta versions of Office.js instead of loading from the content delivery network (CDN). By default, the local production copy of the API is referenced. To reference the local beta copy of the API, you must configure your computer's registry as follows:

  1. In the registry, navigate to HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. If the key doesn't exist, create it.

  2. Create an entry named EnableBetaAPIsInJavaScript and set its value to 1.

    The EnableBetaAPIsInJavaScript registry value is set to 1.

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.

    // 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 the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onSpamReport", onSpamReport);
}

  2. Save your changes.

Note

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 customize a post-processing dialog to show to the user or perform additional operations on the message, such as deleting it from the inbox. 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.

Note

  • Code added after the event.completed call isn't guaranteed to run.
  • 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 the showPostProcessingDialog property in the event.completed call 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.

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

    // 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 the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onSpamReport", onSpamReport);
}

    Note

    If you're on Outlook on Windows Version 2308 (Build 16724.10000) or later, on Mac, on the web, or on new Outlook on Windows (preview), 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.

Tip

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>), replace the existing script entry with the following code.

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

    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.

    Tip

    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 the showPostProcessingDialog property in the event.completed call 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.

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.

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

  • A spam-reporting add-in can be used to report a message even if the Reading Pane of the Outlook client is turned off. However, this isn't supported in Outlook on Mac. In Outlook on Mac, the Reading Pane must be turned on to use a spam-reporting add-in.

  • In Outlook on Windows, only one message can be reported 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 them 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 Mac or on the web, or to new Outlook on Windows (preview). 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.

  • 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 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 include the Action element in the manifest and set its xsi:type attribute to ShowTaskpane. 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.

  • 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 the showPostProcessingDialog property in the event.completed call 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.

    The notification shown when a user deletes a message in Outlook on the web or in new Outlook on Windows.

Troubleshoot your add-in

As you develop your spam-reporting add-in, you may 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