Ctrlk
Go to Workbench
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Microsoft 365: Remove Malicious Email

This guide helps you set up your Microsoft 365 device and grant necessary permissions so that you can enable the Remove Malicious Email auto remediation in Workbench.

This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the Enable an Auto Remediation in Workbench guide to finish your setup.

How It Works

If our SOC identifies an email that must be removed, Workbench completes the action automatically unless it is specifically called out as a "Never remove" asset (the inboxes must first be added as context and then configured in Workbench; see Step 3). Quarantine inboxes are often called out as "Never remove" assets.

This is a soft delete (the message is moved to Deleted Items) and is reversible. It runs per recipient mailbox.

Endpoints Used

Microsoft Graph API

v1.0, messages located depending on the tenant (Exchange Online PowerShell for migrated tenants or the Reporting Web Service for legacy tenants)

Method
Endpoint
Purpose

GET

v1.0/servicePrincipals(appId='{client-id}')/appRoleAssignments

Detect migrated vs. legacy tenant (picks the message trace path)

Powershell

Connect-ExchangeOnline, Get-MessageTraceV2, Disconnect-ExchangeOnline

For migrated tenants. Open an Exchange Online session using the Graph-issued access token; locate delivered messages by sender, time range, and subject; use this info to build the recipient list; close the Exchange Online session

GET

reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace?$filter=SenderAddress eq '{sender}' and StartDate eq datetime'{start}' and EndDate eq datetime'{end}'&$format=json

For legacy tenants (fallback). Locate delivered messages by sender and time; use this info to build the recipient list

GET

v1.0/users?$filter=mail eq '{recipient}'

Use recipient email to find the username

GET

v1.0/users/{user}/messages?$filter=internetMessageId eq '{id}'

Find the message in the mailbox

GET

v1.0/users/{user}/messages?$filter=receivedDateTime ge {received-25h} and receivedDateTime le {received+25h}&$select=id,subject,parentFolderId,from,receivedDateTime

Fallback when the exact message ID lookup returns nothing; page the mailbox and match subjects carrying a prepended tag

GET

v1.0/users/{user}/mailFolders/deleteditems

Get the Deleted Items folder ID

POST

v1.0/users/{user}/mailFolders/{folder}/messages/{msgId}/move

Move the message to Deleted Items

Reversible via the revert capability, which moves the message back to its original folder.

Prerequisites

  • You must install and activate Microsoft 365 Message Trace so that we can automatically remove the malicious email from other inboxes. For instructions, see Microsoft 365 Message Trace Setup.

  • You must have admin access in Workbench, as auto remediations are enabled at the organization level.

Step 1: Assign the SecurityReader Role

The SecurityReader role allows us to perform a message trace or search your instance when we identify an email that needs remediation. This role provides read-only access.

  1. Log in to the Azure portal.

  2. Navigate to the Microsoft Entra ID service.

  3. Go to Manage > Roles and administrators.

  4. Use the search bar to locate the Security Reader role, then select it to view its assignments.

  5. Select Add assignments.

  6. Use the search box under Select member(s) to locate your custom app. You are searching for the app's service principal, which usually has the same name as the app registration.

  7. Select your app, then choose Add. You should now see the app's service principal listed as an active member of the Security Reader role.

Step 2: Add an Additional API Permission

The Exchange.ManageAsApp permission allows us to connect to PowerShell to run the necessary commands to remove an email.

If you used the Expel O365 Integration when onboarding the Microsoft 365 device:

  • If you onboarded after March 12, 2026, the Exchange.ManageAsApp permission has already been granted and you may skip to Update Your Context.

  • If you onboarded prior to March 12, 2026, skip to Manually Grant Admin Consent.

If you used a custom app when onboarding the Microsoft 365 device, follow the below instructions to add the Exchange.ManageAsApp permission.

  1. Navigate to the App registrations page in the Azure portal: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade

  2. Find and select the custom app you created when you set up your security device.

  3. In the left menu, go to Manage > API permissions.

  4. Select Add a permission.

  5. Locate the Office 365 Exchange Online API, and add the Exchange.ManageAsApp permission as an application permission (not as a delegated permission).

  6. Select Grant admin consent and Yes at the prompt.

Step 3: Update Your Context

If you do not want to specify any inboxes for a "do not remove" list, skip to Step 4. Quarantine inboxes are often called out as "Never remove" assets.

Working with your Customer Success Manager (CSM), add any inboxes that should be on the "do not remove" list as org context for your environment. You will then be able to select those inboxes as "Never remove" assets when you enable the auto remediation in Workbench.

If our SOC identifies an email that must be removed, any emails from inboxes added as "Never remove" assets are assigned to you as actions rather than being removed automatically.

Step 4: Return to the Main Setup Guide

Your Microsoft 365 device is now ready for the Remove Malicious Email auto remediation. You should now do one of the following:

  • If you do not need to set up any other devices for this auto remediation, you can return to the Enable an Auto Remediation in Workbench guide to finish Step 2 of the process.

  • If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations, be sure to complete those setup guides as well before returning to the Enable an Auto Remediation in Workbench guide to finish Step 2 of the process. Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.

Manually Grant Admin Consent (Legacy Customers Only)

If you onboarded your Microsoft 365 security device prior to March 12, 2026, and you also used the Expel O365 integration (not a custom app) to create your API connection, you must go back into Azure to grant us admin consent in order for the Microsoft Remove Malicious Email auto remediation to work. This permission was not included in the Expel O365 integration prior to that date.

  1. Log in to https://portal.azure.com/.

  2. Select Enterprise Applications.

  3. Select the Expel application.

  4. In the left menu, go to Security > Permissions.

  5. Select the Grant admin consent for Expel button.

  6. Select the Refresh option to verify that the permissions have been updated.

  7. Go to Step 3: Update Your Context.

Last updated

Was this helpful?