Integrated Spam Reporting

With the increase of unwanted emails, security is a top priority for add-in users. Currently, partner spam-reporting add-ins are added to the Outlook ribbon, although they are frequently found at the bottom or in the overflow menu. This makes it difficult for users to find the add-in for reporting unsolicited emails. In addition to configuring how messages are handled when they are reported, developers must fulfil extra duties such as displaying processing dialogues or supplemental information to users.

The integrated spam-reporting capability simplifies the process of creating individual add-in components from scratch. More significantly, it places your add-in in a prominent location on the Outlook ribbon, making it easier for users to find and report spam. Include this feature in your add-in to improve how unsolicited messages are tracked. Provide clearer instructions to users on how to report questionable texts. Allow an organization's security operations centre (SOC) or IT administrators to quickly run spam and phishing simulations for instructional reasons.

Configure the manifest

To enable the integrated spam-reporting feature in your add-in, you must configure the following settings in your manifest.
The runtime for the add-in. A spam-reporting add-in in old Outlook for Windows runs exclusively in JavaScript. A spam-reporting add-in runs in the browser runtime of Outlook on the web and Mac, as well as the new Outlook on Windows. The spam-reporting add-in's button is always prominently displayed on the Outlook ribbon. The sample below shows how a spam-reporting add-in button appears on the ribbon of the old Outlook client on Windows. The ribbon UI may differ depending on whatever platform the user's Outlook client is running on.

When the user selects the add-in button, the preparation dialogue appears. In this dialogue, a user can provide further information about the message they are reporting. When the user picks Report from the dialogue, the Spam Reporting event is triggered, which is then handled by the JavaScript event handler. The following is an example of a preprocessing dialogue in Outlook for Windows. The dialog's appearance may vary based on the platform on which the user's Outlook client is running.

Unified manifest for Microsoft 365

The integrated spam reporting with the unified manifest for Microsoft 365 is now in public developer preview. It is presently only available for use with classic Outlook on Windows. This should not be used for production add-ins. We encourage you to test it in test or development settings. For more details, see to the public developer preview app manifest schema.

• In your preferred code editor, open the add-in project you created.
• Open the manifest.json file.
• Add the following object to the extensions.runtimes array.

{
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.14" 
                // This is the lowest version of the requirement set that supports the integrated spam-reporting feature.
            }
        ]
    },
    "id": "spam_reporting_runtime",
    // The id of the runtime is set to a unique descriptive name, spam_reporting_runtime.
    "type": "general",
    "code": {
    // 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.
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/spamreporting.js"
        // You'll create or edit these files in later steps.
    },
    "lifetime": "short",
    // This means that the runtime starts when the Spam Reporting event occurs and shuts down when the event handler completes.
    "actions": [
    // The actions object specifies the event handler function that runs in the runtime. 
        {
            "id": "onSpamReport",
            "type": "executeFunction"
            // You'll create this function in a later step.
        }
    ]
},

• Add the following object to the extensions.ribbons array.

{
    "contexts": [
        "spamReportingOverride"
        // This prevents the add-in button from appearing at the end of the ribbon or in the overflow section.
    ],
    "fixedControls": [
    // 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.
        {
            "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": {
    // 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.
    // - The spamFreeTextSectionTitle property.
    // - The spamMoreInfo object.
        "title": "Report Spam Message",
        "description": "Thank you for reporting this message.",
        "spamReportingOptions": {
        // It provides a multiple-selection list of up to five choices. This helps a user identify the type of message they're reporting.
            "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:",
        // It provides a text box for the user to add more information about the message they're reporting.
        "spamMoreInfo": {
        // It includes a link in the dialog to provide informational resources to the user.
            "text": "Reporting unsolicited messages",
            "url": "https://www.contoso.com/spamreporting"
        }
    }
}

Add-in only manifest

• Set your add-in only manifest's VersionOverridesV1_1 node appropriately.
• You must specify the HTML file that refers or contains the code to handle the spam-reporting event in the resid attribute of the Runtime element in order to run a spam-reporting add-in in Outlook on the web, Mac, and the new Outlook on Windows.
• You must specify the JavaScript file containing the code to handle the spam-reporting event in the Override child element of the <Runtime> element in order to execute a spam-reporting add-in in Windows' old Outlook.
• Activate the add-in on the Outlook ribbon by changing its xsi:type property from ReportPhishingCommandSurface to avoid it showing up at the end of the ribbon or in the overflow area.
• To customize the ribbon button and preprocessing dialog, you must define the ReportPhishingCustomization node.
• 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 <Function Name> child element.
• Set up the Preprocessing Dialog element in your manifest to personalise the preprocessing dialogue. The dialogue needs a title and a description, but you can also choose to include the following components.
• A list of options with various selections to assist the user in identifying the kind of message they are reporting. See the Reporting Options element for information on configuring these reporting options.
• A text field where the user can enter details about the message they're reporting. See the FreeTextLabel element to find out how to construct a text box.
• Utilising a unique text and URL, give the user access to educational materials. See the More Info element to find out how to customise these elements.
• The custom text defined in the <MoreInfoText> element appears before the URL provided in the <MoreInfoUrl> element, depending on the Outlook client.

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

• In your preferred code editor, open the add-in project you created.
• Open the manifest.xml file located at the root of your project.
• Select the entire <Version Overrides> 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.14">
        <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. -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the spam-reporting event handler. This is used by classic 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="Reporting unsolicited messages"/>
        <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>

Implement the event handler

The event handler in your add-in's JavaScript file handles the Spam Reporting event that is created when a message is reported using your add-in. You must call Office.actions.associate in your code in order to map the name of the event handler you defined in your manifest to its JavaScript equivalent.

• Go to the ./src directory in your add-in project. Next, make a new spam reporting folder.
• Make a new file called spamreporting.js and place it in the ./src/spamreporting folder.
• Add the following JavaScript code to the newly created spamreporting.js file by opening it.

// Handles the Spam Reporting 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);
}

Forward a copy of the message

The reported message must be processed by your event handler. It can be set up to send data, like a copy of the message or the user-selected options in the preprocessing dialogue, to an internal system for additional analysis.
In your event handler, call the getAsFileAsync method to send a copy of the reported message quickly. This obtains the message's EML format in Base64-encoded form, which you can subsequently forward to your internal system.
Extract the free Text values and choices from the Spam Reporting event object if you need to record the user's responses to the text box and options in the preprocessing dialogue. See Office.SpamReportingEventArgs for more details on these characteristics.
The following is an example of a spam-reporting event handler that calls the getAsFileAsync method and gets the user's responses from the Spam Reporting event object.

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

// Handles the Spam Reporting 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);
}

The event handler needs to invoke the event.completed function after processing the message is finished. Event.completed can be used to do extra actions on the message, including deleting it from the inbox, or to customise a post-processing dialogue to display to the user, in addition to informing the add-in that the spam-reporting event has been processed. See Office.SpamReportingEventCompletedOptions for a list of properties you can include in a JSON object to give as a parameter to the event.completed method.
It is not guaranteed that code inserted after the event.completed call will execute.
In the spamreporting.js file, replace its contents with the following code.

// Handles the Spam Reporting 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.

    /**
     * Indicates that the processing of the spam-reporting event is finished. After moving the reported message to the mailbox's Junk Email folder, it presents the user with a post-processing dialogue. The onErrorDeleteItem attribute controls whether the message will be erased in the event of an error while it is being processed.
     */
    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);
}

You must utilise the moveItemTo property in the event if you're using traditional Outlook.finished call to designate the location where a reported message is stored once your add-in has processed it. To use the integrated spam-reporting capability on earlier Windows releases of Outlook, you need to use the postProcessingAction attribute.
When the add-in has finished processing a reported message in Outlook on Windows, the user is presented with the sample post-processing dialogue shown below. Keep in mind that the platform the user's Outlook client is running on may affect how the dialogue looks.
an illustration of a post-processing dialogue box that appears after the add-in has dealt with a reported spam message.
Consider the following when you create a Windows add-in for Outlook that reports on spam.

• The JavaScript file containing the logic to handle the spam-reporting event does not accept imports at this time.
• The Office.onReady() and Office.initialize function's code will not execute.
• Any add-in starting logic, including determining the user's Outlook version, needs to be added to your event handlers instead.
• In the ./src/commands folder, open commands.html.
• Immediately before the closing head tag </head>, add the following script entry.

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

• From the root directory of your add-in project, open the webpack.config.js file.
• 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",
    },
  ],
}),

Verify functionality

• Use an Outlook client that supports sideloading the add-in.
• Select the button for the add-in from the ribbon after picking a message from your inbox.
• Select a reason for reporting the message and, if configured, add details about the message in the preprocessing dialogue. Next, choose Report.
• Choose OK from the post-processing dialogue box.
• Examine the constraints and behaviour of features.
• Keep in mind the features and constraints of your add-in's integrated spam-reporting capability as you design and test it.
• The original Report button on the Outlook ribbon has been replaced by an integrated spam-reporting add-in in Outlook for Windows and the web. If you install more than one spam-reporting add-in, they will all show up on the ribbon's Report section.

An example of an integrated add-in for reporting spam that takes the place of the Outlook ribbon's Report button. Once activated, a spam-reporting add-in can operate for up to five minutes. The add-in will time out if processing takes more than five minutes. The user will be notified via a dialogue box if the add-in times out. The dialogue that appears when a spam-reporting add-in expires.
A spam-reporting add-in in classic Outlook for Windows can be used to report a message even when the Outlook client's Reading Pane is disabled. The spam-reporting add-in is available in Outlook on the web, Mac, and the new Outlook on Windows if the Reading Pane is enabled or the message to be reported is open in another window. Only one message may be reported at a time. If you choose numerous messages to report, the spam-reporting add-in's button becomes unavailable. Classic Outlook on Windows can only process one reported message at a time. If a user attempts to report another message while the prior one is still being processed, a dialogue will appear informing them of this.
The dialogue box appears when the user attempts to report another message while the prior one is still being processed. This does not apply to Outlook on the web, Mac, or the new Outlook for Windows. In these Outlook clients, a user can report a message from the Reading Pane while also reporting messages that are open in separate windows. Even if the user navigates away from the selected message, the add-in continues to process it. In Outlook for Mac, this is only possible if the user reports a message while it is open in a different window. If a user reports a message while seeing it in the Reading Pane and then navigates away, the reporting process is cancelled. The buttons in the pretreatment and postprocessing dialogues are not customisable. Additionally, the content and buttons in the timeout and current report dialogues cannot be changed.
The integrated spam reporting and event-based activation capabilities must share the same runtime. Multiple runtimes are not presently supported by Outlook. For additional information on runtimes, see Runtimes in Office Add-ins. A spam-reporting add-in only supports function commands. It is not possible to assign a task pane command to the ribbon's spam reporting button. To include a task pane in your add-in, you must configure it in your manifest as follows:

• Add-in-only manifest: Include the Action element in the manifest and specify the xsi:type property as ShowTaskpane.
• Unified manifest for Microsoft 365 Configure a task pane object using the extensions.runtimes and extensions.ribbons arrays. For more information, read the "Add a task pane command" part of Create add-in commands using the unified manifest for Microsoft 365. It should be noted that while a distinct button to activate the task pane will be added to the ribbon, it will not appear in the ribbon's designated spam-reporting area.

Ref: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/spam-reporting