> For the complete documentation index, see [llms.txt](https://docs.expel.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.expel.io/workbench-setup/auto-remediations/remove-malicious-email/microsoft-entra-id-via-event-hub-remove-malicious-email.md).

# Microsoft Entra ID via Event Hub: Remove Malicious Email

*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*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench.md) *guide to finish your setup.*

This guide helps you set up your Microsoft Entra ID via Event Hub device so that you can enable the Remove Malicious Email auto remediation in Workbench. During the setup process, you will grant Expel all necessary permissions for the remediation to work.

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

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**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)

<table data-search="false"><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>v1.0/servicePrincipals(appId='{client-id}')/appRoleAssignments</code></td><td>Detect migrated vs. legacy tenant (picks the message trace path)</td></tr><tr><td>Powershell</td><td><code>Connect-ExchangeOnline</code>, <code>Get-MessageTraceV2</code>, <code>Disconnect-ExchangeOnline</code></td><td><strong>For migrated tenants.</strong> 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</td></tr><tr><td>GET</td><td><code>reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace?$filter=SenderAddress eq '{sender}' and StartDate eq datetime'{start}' and EndDate eq datetime'{end}'&#x26;$format=json</code></td><td><strong>For legacy tenants (fallback).</strong> Locate delivered messages by sender and time; use this info to build the recipient list</td></tr><tr><td>GET</td><td><code>v1.0/users?$filter=mail eq '{recipient}'</code></td><td>Use recipient email to find the username</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/messages?$filter=internetMessageId eq '{id}'</code></td><td>Find the message in the mailbox</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/messages?$filter=receivedDateTime ge {received-25h} and receivedDateTime le {received+25h}&#x26;$select=id,subject,parentFolderId,from,receivedDateTime</code></td><td>Fallback when the exact message ID lookup returns nothing; page the mailbox and match subjects carrying a prepended tag</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/mailFolders/deleteditems</code></td><td>Get the Deleted Items folder ID</td></tr><tr><td>POST</td><td><code>v1.0/users/{user}/mailFolders/{folder}/messages/{msgId}/move</code></td><td>Move the message to Deleted Items</td></tr></tbody></table>

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

## Prerequisites

1. 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.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.
3. You must have already completed all of the steps in [Microsoft Entra ID via Event Hub Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-entra-id-via-event-hub-setup-for-workbench.md).

## 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.](https://portal.azure.com/)
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 Additional API Permissions

The `Exchange.ManageAsApp` permission allows us to connect to PowerShell to run the necessary commands to remove an email. The `Mail.ReadWrite` permission supports our fallback code for if/when email removal via the Exchange method fails.

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 following two permissions as application permissions (not as delegated permissions):
   * `Exchange.ManageAsApp`
   * `Mail.ReadWrite`
6. Make sure to **Grant admin consent** for both permissions.

## Step 3: Update Your Context <a href="#step-3-update-your-context" id="step-3-update-your-context"></a>

**If you do not want to specify any inboxes for a "do not remove" list, skip to** [**Step 4**](#step-4-return-to-the-main-setup-guide)**. 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](/workbench-setup/get-started/add-and-manage-org-context.md) for your environment. You will then be able to select those inboxes as "Never remove" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
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.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#step-4-return-to-the-main-setup-guide" id="step-4-return-to-the-main-setup-guide"></a>

Your Microsoft Entra ID via Event Hub 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](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench.md) 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](/workbench-setup/auto-remediations.md) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench.md) 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.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.expel.io/workbench-setup/auto-remediations/remove-malicious-email/microsoft-entra-id-via-event-hub-remove-malicious-email.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.