---
title: "Microsoft 365 - Mailboxes data source"
feature: "Data sources"
audience: ["end user", "developer", "system analyst", "system administrator", "system engineer"]
version: "Relativity aiR"
type: ["User Guide", "Tutorial"]
url: "https://help.relativity.com/RelativityaiR/Content/Collect/Data_sources/Microsoft_365_-_Mailboxes.htm"
lastModified: "2026-11-20"
---

# Microsoft 365 - Mailboxes data source

This topic provides details on how to capture Microsoft 365 mailbox data with Collect.

The Mailboxes connector uses Microsoft's Purview API to collect standard mailboxes, archived online mailboxes, and inactive mailboxes for a custodian in a single collection job.

> **Note:** This documentation contains references to third-party software, or technologies. While efforts are made to keep third-party references updated, the images, documentation, or guidance in this topic may not accurately represent the current behavior or user interfaces of the third-party software. For more considerations regarding third-party software, such as copyright and ownership, see [Terms of Use](https://www.relativity.com/terms-of-use/).

## Considerations

Consider the following about the Microsoft 365 Mailboxes data source:

### API and connector

- This connector uses Microsoft's Purview API.
- By default, Collect retrieves all mailbox types that the Purview API supports for a custodian. This includes:
  - The primary mailbox
  - The archived online mailbox, if enabled for the custodian
  - Any inactive mailboxes associated with the custodian
- You do not need to configure each mailbox type separately. For more information on how the Purview API handles each mailbox type, see [Data sources in eDiscovery](https://learn.microsoft.com/en-us/purview/edisc-data-sources) and [Learn about inactive mailboxes](https://learn.microsoft.com/en-us/purview/inactive-mailboxes-in-office-365).
- Use the Outlook connector if you need linked cloud files attached to their parent emails after processing, or if your organization uses E3 licenses and needs linked files collected. For more information, see [Microsoft 365 - Outlook data source](https://help.relativity.com/RelativityaiR/Content/Collect/Data_sources/Microsoft_365_-_Outlook.md).

### Purview case

- Relativity creates a case in Microsoft Purview, adds the custodian, runs the search, and exports the results to Collect.
- You can view this case at any time in the Microsoft Purview portal.
- Purview cases are created in your Microsoft Purview instance to support the search and export of mailbox data.

### Preserved files

- Relativity collects all available data, including preserved files.
- You do not need to take extra steps to collect preserved files. They are automatically included in the collection.
- For more information on preserving data, see [Preservation in-place](https://help.relativity.com/RelativityaiR/Content/Relativity/Preservation/Preservation_in_place.md).

### Requirements and limitations

- Export requires an account with the eDiscovery Manager role and an Azure AD app registration with the required delegated permissions.
- Microsoft APIs do not support verifying that an inactive mailbox exists before collection. You will see failed collections when a mailbox no longer exists.
- Relativity collects mailbox data as .pst files.
- This connector collects linked cloud files for E5 customers only. Microsoft treats linked files as a premium feature requiring an E5 license. For E3 customers who need linked files collected, use the [Microsoft 365 - Outlook data source](https://help.relativity.com/RelativityaiR/Content/Collect/Data_sources/Microsoft_365_-_Outlook.md) instead.
- Processing does not yet build family relationships between linked files and their parent emails for collections from this connector.
- This connector replaces the Office365 Exchange Archive connector, which uses the Exchange Web Services (EWS) API that Microsoft is deprecating. If you currently use the Office365 Exchange Archive connector, plan to migrate to this connector.
- If the password changes on the account used to generate the refresh token, all existing refresh tokens are invalidated. To continue collecting, go to **Collect Admin**, select the data source, click **Edit**, and generate a new refresh token.
- If the Azure Application Registration secret changes or expires, update all Microsoft data sources that use that registration. Go to **Collect Admin**, select each affected data source, click **Edit**, enter the new secret in the **Application Secret** field, and click **Save**.

## Collection size

Microsoft 365 collections can be large. When collection jobs become too large, performance decreases.

| Large collections | Best practices |
| --- | --- |
| 200 GB per search | Reduce search size |
| Multi-TB exports | Limit the number of custodians per job. Collect supports a maximum of 30 custodians per job. |
| Long date ranges with many mailboxes | Use smaller date ranges. |
| Large mailboxes | Plan for 2 GB per hour per mailbox transfer throughput. For mailboxes larger than 25 GB, collection may take more than 24 hours. |

### Export duration for large mailboxes

Export duration is determined primarily by mailbox size and whether or not date range criteria are being used, as well as the current load on Microsoft's services. Purview eDiscovery runs on shared, multi-tenant Microsoft 365 infrastructure, and Microsoft does not provide a service-level agreement or guaranteed throughput for export operations.

Exports occur in two phases, and each contributes to the overall duration.

#### Phase 1: Export preparation in Microsoft

Microsoft packages the mailbox data before transferring any documents.

- While this phase is in progress, the document counter on the Collect monitoring page remains at zero, which is normal.
- The counter reflects documents received by Collect. Nothing is transferred until preparation finishes.
- For large mailboxes, this phase alone can take several hours or longer.

### Phase 2: Data transfer

When preparation completes, documents begin transferring to Collect and the counter starts incrementing.

- Microsoft throttles transfer throughput. Throughput is typically around 2 GB per hour per mailbox.
- Completion of the preparation phase does not mean the collection is nearly finished.
- A 25 GB mailbox may require 12 or more hours of transfer time after preparation completes. A mailbox larger than 25 GB may take several hours to more than 24 hours to fully collect.

Do not cancel or restart a collection solely because progress appears slow. Doing so restarts the export preparation from the beginning.

If a large mailbox collection shows zero documents for more than 48 hours, contact ﻿[Relativity Support](https://community.relativity.com/s/contactsupport).

## Accessing Microsoft 365 tenants

Register the Collect application to access Microsoft 365.

When registering the application, the Microsoft 365 administrator creates a Microsoft Application ID and secret. Relativity uses this ID and secret to configure data sources in Collect and provides access to the Microsoft 365 tenants.

You can register the application through Azure Portal or by registering the delegated permissions through the Microsoft App Registration Portal. After registering the application, request administrator consent. From there, it is possible to revoke application access.

Use this information to create a Microsoft integration point. .

Depending on your Relativity aiR license, commercial or government, and your Microsoft tenant, Microsoft 365 or Microsoft 365 Government, you will be able to collect from either Microsoft 365 or both Microsoft 365 and Microsoft 365 Government data sources. Commercial users can only collect from Microsoft 365 tenants. Government users can collect from Microsoft 365 and Government 365 tenants. These data sources act the same, but have different icons within Collect.

### Registering the Collect application

Start with registering your application in the Azure portal by following the steps below.

> **Caution:** The listed permissions and roles are required and supported by Relativity.
> - Relativity does not support substitutions or reduced permissions.
> - You can submit requests for alternative or reduced permissions as product feedback.

For more information on registering an application in Azure, see [Microsoft's documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) or [Microsoft's authentication documentation](https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth).

> **Note:** These steps must be completed by a Microsoft 365 administrator.

1. Open your [Azure Portal](https://portal.azure.com/).
2. Click **Microsoft Entra ID** (formerly known as Azure Active Directory).
3. Click **App registrations**.
4. Click **New Registration** to display the Register an application page.
5. Enter an application name in the **Name** field.
6. Accept the default setting, **Accounts in this organizational directory only**, as the supported account type.
7. Click **Register**.
8. Once the application is registered, make note of the **Application (client) ID** and **Directory (tenant) ID** for use later when configuring the data source in Relativity aiR Collect.

### Obtaining a client secret

Next, obtain the client secret for the registered application in the Azure portal. For more information, see relevant Microsoft documentation on the Microsoft site.

> **Note:** These steps must be completed by a Microsoft 365 administrator.

1. From the registered application's page, click the **Certificates & secrets** option in the left navigation bar.
2. Click the **Client secrets** tab.
3. Click **New client secret**.
4. Enter a description for the client secret in the **Description** text box.
5. Select **730 days (24 months)** from the Expires list. The client secret will expire after this time frame.
   - Once the client secret expires, you must create a new client secret in the Azure portal as described in these steps.
   - Then you must update your Microsoft 365 Collect data sources with it. For more information, see [Expired Azure client secrets](#Expired).
   - For any additional assistance with client secrets, please contact the Azure Admin in your organization.
6. Click **Add** to create a new secret.

   > **Caution:** Microsoft will only show the secret value this one time. There is no way to recover a secret.
7. Click the copy icon to copy the **Secret Value** to the clipboard.
   - Paste it to a safe location.
   - You will use the Secret Value later when creating the data source in Collect.
   - Confirm you copy the *Secret Value* and not the Secret ID.
8. Give your Relativity Admin the Application ID and the Client Secret for setup of Collect.
   - This application secret is also needed for setting up a Microsoft Entra ID integration point.
   - For more information, see [Importing from Microsoft Entra ID](https://help.relativity.com/RelativityaiR/Content/Relativity/Integration_Points/Importing_data_through_Integration_Points.md#ImportingMSAzureAD).

#### Expired Azure client secrets

If your Azure client secret expires, follow these steps:

1. Get a new secret as outlined in the steps above.
2. Go to **Collect Admin** in Relativity aiR.
3. Select the desired data source that has expired, and click **Edit**.
4. Input the new client secret value in the **Application Secret** field.
5. Click **Save**.

You must repeat these steps for all Microsoft data sources that you have set up.

### Setting API permissions

Each data source has its own set of permissions necessary to allow access to the tenants. To add the correct permissions based on your selected Microsoft 365 data source, follow the steps below.

> **Note:** These steps must be completed by a Microsoft 365 administrator.

1. From the registered application's page, click the **Manage > API permissions** option in the left navigation bar.

   > **Note:** The *User.Read* permission is automatically added by default.
2. Click **Add a permission**.
3. Click **Graph API**.
4. Select **Delegated Permissions**.
5. Select the **eDiscovery.ReadWrite.All** permission from the Permission list.
6. Click **Add permissions**.
7. Click **Grant Permission**.  
   The window will show all permissions granted.
   - Make a note of the application ID that Microsoft assigned to the app registration.
   - This ID is also required for setup of data sources in Collect.
8. Click **Add a permission**.
9. Select **APIs my organization uses**.
10. Search for **MicrosoftPurviewEDiscovery**.
    - If *MicrosoftPurviewEDiscovery* does not appear in the APIs my organization uses list, you must first register the app in Microsoft Entra ID.
    - For more information, see Microsoft's [Register the MicrosoftPurviewEDiscovery app in Microsoft Entra ID](https://learn.microsoft.com/en-us/purview/edisc-ref-api-guide#step-1-register-the-microsoftpurviewediscovery-app-in-microsoft-entra-id) documentation.
11. Select **Application Permissions**.
12. Select the **eDiscovery.Download.Read** permission from the Permission list.
13. Click **Add permissions**.
14. Click **Grant Permission**.  
    The window will show all permissions granted.
    - Make a note of the application ID that Microsoft assigned to the app registration.
    - This ID is also required for setup of data sources in Collect.
15. Verify that all permissions have been granted.
16. Click **Add permissions**.
17. Click **Grant Permission**.
18. Click **Accept** to grant the permissions.

All API permissions have been granted and you can start creating the data source in Relativity aiR.

## Adding a redirect URI

After setting up API permissions, you must add a Redirect URI to the Azure Application Registration. Add the Redirect URI with the following steps:

1. In the left-side menu console, click **Authentication**.

   > **Note:** It may appear as **Authentication (Preview)**.
2. Click **Add Redirect URI**.
3. Click **Web**.
4. Enter your Redirect URI.
   - Your Redirect URI is your Relativity aiR tenant domain URL plus */collect-services/api/v1/Authentication/ms-auth-response*.
   - For example, *https://acme.corp.relativity.one/collect-services/api/v1/Authentication/ms-auth-response*

## Finding Azure credentials

If an application is already created and you need to find the application information to complete the Source Connection step, follow the steps below in the Azure Portal. For more information, see relevant Microsoft documentation on the Microsoft site.

1. Open your [Azure Portal](https://portal.azure.com/).
2. Click **Microsoft Entra ID** (formerly known as Azure Active Directory).
3. Navigate to **Enterprise applications**.
4. In the list of applications, locate and click on your application.The application page displays.
5. Navigate to **Properties**.
6. Click the **copy icon** next to the **Application ID**. The ID is copied to your clipboard to use as needed.  
   ![Properties dialog showing Application ID](https://help.relativity.com/RelativityaiR/Content/Resources/Images/Features/Integration_Points/SCR_AzureApplication.png)

## Revoking application access

Revoke the application from the Azure portal or by using a PowerShell script. For more information, see [Microsoft's documentation](https://docs.microsoft.com/en-us/skype-sdk/trusted-application-api/docs/tenantadminconsent#revoking-tenant-admin-consent).

### Revoking access via Azure Portal

To revoke access from the Azure portal:

1. Open your [Azure Portal](https://portal.azure.com/).
2. Navigate to **Enterprise Application**.
3. Under **All applications**, search for your application and click its link.
4. Under **Manage > Properties**, click **Delete**.

Collect no longer has access.

### Revoking access via Powershell

Revoke access in Powershell using the Remove-MsolServicePrincipal script. See the Powershell example below of retrieving and deleting an application registration.

```
Get-MsolServicePrincipal -AppPrincipalId 19ab8a2e-ccce-4fa8-a9ee-eb16e220d602


      ExtensionData         : System.Runtime.Serialization.ExtensionDataObject
        AccountEnabled        : True
     Addresses             : {}
        AppPrincipalId        : 19ab8a2e-ccce-4fa8-a9ee-eb16e220d602
       DisplayName           : Relativity-Development-Application
        ObjectId              : 51798fb3-e72c-4373-8c63-6e7d0dd63ad7
        ServicePrincipalNames : {19ab8a2e-ccce-4fa8-a9ee-eb16e220d602}
       TrustedForDelegation  : False


       Remove-MsolServicePrincipal -AppPrincipalId 19ab8a2e-ccce-4fa8-a9ee-eb16e220d602
```

## Creating the data source in Collect

The Collection Admin tab is where you create, edit, and remove data sources from your workspace.

- You need to setup each data source once.
- You must create your data sources prior to setting up your custodian targets.

In Relativity aiR, navigate to **Collect**.

1. Click the **New Collection Source Instance** button.
2. Enter in a unique name for the data source.
3. Select a **Microsoft 365 Inactive Mailbox** data source.

   > **Note:** Collect automatically collects any data that is preserved due to an in-place hold or litigation hold. Data on a hold is stored in a preservation library and separate folders. For more information, see [Microsoft Retention Policies](https://docs.microsoft.com/en-us/office365/securitycompliance/retention-policies).
4. Enter the required information in Settings. For more information, see [Settings fields](#Fields)
5. Click **Save**.

After clicking Save, Relativity verifies the parameters and connectivity to the Microsoft 365 data source.

- If successful, Relativity saves the data source.
- If the connection fails, a message appears indicating that the connection failed.
  - If verification fails, verify that the values are correct.
  - The data source will save when it is corrected and is verified.

Once the set up is complete, the data source information on the Collect Admin page.

### Settings fields

To connect Relativity to a Microsoft Outlook data source, you need to gather and enter the information for the following fields:

- **Tenant ID**—enter the Tenant ID or Primary domain of the Microsoft 365 tenant the collection is intended for.
  - The domain name usually ends with .onmicrosoft.com.
  - To locate the tenant ID or primary domain name, see [Microsoft documentation](https://learn.microsoft.com/en-us/partner-center/account-settings/find-ids-and-domain-names#find-the-microsoft-entra-tenant-id-and-primary-domain-name).
- **Application Id**—enter the Application ID created during registering the Collect application in Microsoft 365.
- **Application secret**—enter the Application secret created during registering the Collect application in Microsoft 365. For more information, see [Accessing Microsoft 365 tenants](#AcessingM365Tenants).
- **Refresh token**—after entering in the three pieces of information, click **Generate Refresh Token**.
  - An authentication window appears.
  - In the authentication window, you must get a refresh token from a Microsoft account with the Microsoft eDiscovery Manager role assigned.

### Data source details

Each data source details page includes an Action console. Each data source has different actions.

On the Microsoft Teams data source page, click **Validate Connection** in the Actions console to validate the client ID, certificate, and other credentials with Microsoft 365.

## Configuring the data source in Collect

In Relativity aiR, configure the data sources chosen in the Collection Details step.

### Data source criteria

Add criteria to collect specific data. To configure the data sources, complete the following fields:

- **Select and unselected tabs**—choose the data sources to collect from by moving unselected data sources to the selected list.
- **Field**—choose the field to filter on within the data source.

  > **Note:** You must add start and end dates when you are configuring the Outlook Calendar data source to complete the Data Sources step.
- **Operator**—choose an operator, such as equals, contains, greater than, or less than.
- **Value**—enter a value to find in the selected field.

After selecting field options, you must click **Add Criteria**.

Details to know about criteria:

- Each criteria is then separated by an AND operator.
- Leave the data source criteria empty to collect all data from the sources.

### Criteria

Filter a data source's data that you want to collect by adding criteria.

This section covers the different criteria for each data source. It also includes what can be searched within each data source.

The following table lists the filter criteria supported for mailbox collections.

> **Note:** You must register Relativity in Microsoft 365 before using this data source. For information on registering Relativity in Microsoft 365, see [Accessing Microsoft 365 tenants](#AcessingM365Tenants).

The following table lists the filter criteria supported for mailbox collections.

All dates are in Coordinated Universal Time (UTC).

| Criteria | Operators | Description | Example |
| --- | --- | --- | --- |
| Email Received Date | Greater Than or Equals, Less Than or Equals | When you use the Email Received Date property in a query, the search returns all messages that equal or does not equal, greater or less than the date entered. | If you search “Less Than 1/1/2020,” your results include all emails received before January 1, 2020. |
| Email Sent Date | Greater Than or Equals, Less Than or Equals | When you use the Email Sent Date property in a query, the search returns all messages that equal or does not equal, greater or less than the date entered. | If you search “Greater Than 1/1/2001,” your results include all emails sent after January 1, 2001. |
