> For the complete documentation index, see [llms.txt](https://docs.teleskope.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.teleskope.ai/connectors/saas/communication/exchange.md).

# M365 - Exchange

{% hint style="info" %}
**Beta connector.** Contact Teleskope to arrange onboarding before starting setup.
{% endhint %}

Exchange Online supports two capabilities. Enable either one or both:

| Capability              | What it does                                                                                                   | Setup required                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Historical mail**     | Discovers and classifies existing messages from a date you choose, then checks for changes on a schedule.      | Microsoft Graph application permissions and a credential provisioned with Teleskope. No Outlook add-in is required. |
| **Outbound protection** | Checks attachments, subject, and plain-text body against your policies when a user sends a message in Outlook. | Two Entra app registrations and an Outlook add-in deployed to participating users.                                  |

Both use the same Entra tenant connection. Saving that connection does not enable either capability.

## Before you begin

You need an Exchange Online tenant with active mailboxes, an Entra administrator who can configure app registrations and grant consent, and a Teleskope **Admin** account.

For outbound protection, you also need a Microsoft 365 administrator authorized to deploy Office add-ins and the public HTTPS **Satellite hostname** supplied by Teleskope. Satellite hosts the add-in and connects Outlook to Teleskope; participating clients must be able to reach it. Check [supported clients](#supported-clients-and-limitations) before rollout.

## Save the tenant connection

1. In Microsoft Entra admin center, copy the **Tenant ID** from **Microsoft Entra ID > Overview**.
2. In Teleskope, open **Settings > Connectors > Microsoft 365 > Exchange Online**.
3. On the **Enrollment** tab, enter the **Entra tenant ID** under **Microsoft Entra connection** and select **Save connection**.
4. Continue with [historical mail](#set-up-historical-mail), [outbound protection](#set-up-outbound-protection), or both.

The tenant ID identifies your organization. It does not supply the application credential needed to read historical mail.

Teleskope uses the company-wide internal email domains under **Settings > Organization** for internal/external policy conditions. You do not configure a separate domain list for Exchange.

## Set up historical mail

### 1. Arrange Microsoft Graph access

Historical mail uses application permissions to read mailboxes without a signed-in user.

1. Coordinate the Graph reader app registration with your Teleskope contact. If you also use outbound protection, Teleskope can confirm whether to reuse the protected API registration or use a separate reader registration. Do not use the Outlook add-in client for this purpose.
2. Give the reader Microsoft Graph **application** permissions `User.Read.All` and `Mail.Read`, and grant tenant-wide admin consent. See [Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-reference).
3. Have Teleskope provision the application credential before continuing. The Exchange settings page has no credential entry or app authorization flow for historical mail.
4. In **Enrollment > Microsoft Entra connection**, select **Test connection**. The test verifies that Teleskope can enumerate tenant users and access an Exchange mailbox folder.

### 2. Choose the mailboxes to scan

Open **Allow/deny settings**, choose a list type, and select **Save mailbox scope**:

| List type     | Behavior                                                                         |
| ------------- | -------------------------------------------------------------------------------- |
| **Allowlist** | Scans only listed mailboxes. An empty list scans no mailboxes.                   |
| **Denylist**  | Excludes listed mailboxes. An empty list scans every mailbox the app can access. |

Use **Add mailboxes** to enter exact email addresses, user principal names, or Microsoft Graph user IDs. Groups and wildcards such as `*@example.com` are not supported.

You must save a scope before enabling historical mail, including when using an empty denylist. This selects mailboxes, not message senders: messages from external senders inside a selected mailbox are included.

### 3. Configure and enable scanning

1. Open **Scan settings > Historical**.
2. Set the **Historical start date**. Messages received on or after this date are discovered. The date is required and cannot be in the future.
3. Set the scan schedule. It uses a five-field cron expression in UTC and defaults to hourly.
4. Select **Save historical settings**.
5. Switch **Historical mail** to **Enabled** and confirm.

### 4. Verify historical discovery

1. Confirm **Last mailbox inventory** updates under **Scan settings > Historical**.
2. Confirm resources from the selected mailboxes appear in the Data Catalog after the initial crawl. Check classification results and any findings; discovery is not limited to messages with findings.
3. Confirm subsequent changes are picked up on the configured schedule.

Historical discovery does not require either of the outbound app registrations or an Outlook manifest. Exchange Online Archive mailboxes are outside the Microsoft Graph mail API coverage used by this connector.

## Set up outbound protection

### 1. Register the protected API

This app registration identifies the Teleskope API that Outlook calls.

1. Create or select the protected API app registration in Microsoft Entra.
2. Under **Expose an API**, configure its **Application ID URI** and add a delegated scope named `access_as_user`.
3. Under **Manifest**, set `api.requestedAccessTokenVersion` to `2` and save.
4. Copy the app's **Application (client) ID** from **Overview**. You will enter this GUID as **API audience** in Teleskope.

The Application ID URI and API audience are different values. For example:

| Value              | Example or source                                      | Where it is used                                                |
| ------------------ | ------------------------------------------------------ | --------------------------------------------------------------- |
| Application ID URI | `api://teleskope.ai/api`                               | **Expose an API** in Entra; keep your configured URI            |
| Exposed permission | `api://teleskope.ai/api/access_as_user`                | Delegated permission granted to the add-in client               |
| API audience       | Protected API app's **Application (client) ID** GUID   | Teleskope **API audience** field and the v2 token's `aud` claim |
| Add-in client ID   | Separate add-in app's **Application (client) ID** GUID | Teleskope **Add-in client ID** field                            |

An existing URI such as `api://teleskope.ai/api` does not need to become a GUID. Enter the API app's client GUID in Teleskope, not that URI. [Microsoft defines v2 token audiences as the API's client ID](https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference).

Teleskope derives the requested scope as `<API audience>/access_as_user`; there is no scope field to fill in. You still need to expose `access_as_user` in Entra and grant the add-in access to it.

### 2. Register the Outlook add-in client

Create a separate app registration for the Outlook add-in:

1. Under **Authentication**, select **Add a platform > Single-page application (SPA)**.
2. Add `brk-multihub://<satellite-hostname>` using the hostname supplied by Teleskope, with no path. This enables [nested app authentication (NAA)](https://learn.microsoft.com/en-us/office/dev/add-ins/develop/enable-nested-app-authentication-in-your-add-in?tabs=outlook).
3. Under **API permissions > Add a permission > APIs my organization uses**, select the protected API app and add its delegated `access_as_user` permission.
4. Select **Grant admin consent for** , confirm **Yes**, and verify `access_as_user` shows **Granted for** .
5. Copy this app's **Application (client) ID** for the **Add-in client ID** field in Teleskope.

### 3. Save the add-in and outbound settings

1. In Teleskope, open **Enrollment > Outlook add-in**.
2. Enter the protected API app's client GUID as **API audience** and the separate add-in app's client GUID as **Add-in client ID**.
3. Select **Save add-in configuration**.
4. Open **Scan settings > Outbound** and choose **Degraded posture**:
   * **ALLOW** permits sending when an operational failure or timeout prevents a completed check.
   * **BLOCK** prevents sending in that situation.
5. Select **Save outbound settings**.

Degraded posture covers operational failures in communication, scanning, or policy evaluation. It does not override a confirmed policy warning or block for the current draft. Invalid authentication and inconsistent message state remain blocked.

### 4. Configure Exchange policies

1. Create or edit an Exchange Online policy in PolicyMaker.
2. In the workflow editor, add **Set send verdict**.
3. Select the resources to evaluate: **Message body or subject**, **Attachments**, or both. Subject and plain-text body are classified together as one message resource.
4. Choose the verdict:

   | Verdict   | Sender experience                                                                                                                             |
   | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
   | **ALLOW** | Records the policy violation without interrupting the send.                                                                                   |
   | **WARN**  | Pauses sending for the sender to review findings and provide a business justification, or report a false positive when offered by the policy. |
   | **BLOCK** | Prevents sending. The sender must change the message to resolve the violation.                                                                |
5. For **WARN** or **BLOCK**, enter the sender message.
6. In the save dialog, choose **Policy coverage > Outbound protection** and **Save and run policy** to activate it.

Each Exchange policy requires an explicit send-verdict action. If multiple applicable policies match, **BLOCK** takes precedence over **WARN**, then **ALLOW**. Scan scope and normal enforcement are configured per policy; degraded posture is configured under outbound settings.

### 5. Deploy the Outlook add-in

1. Return to **Enrollment > Outlook add-in** and select **Download add-in manifest**.
2. In the [Microsoft 365 Admin Center](https://admin.microsoft.com), open **Settings > Integrated apps** and select **Upload custom apps**.
3. Choose **Office Add-in** and upload the XML manifest. It is not a Teams app or a unified Microsoft 365 manifest.
4. Assign it to pilot users first, then expand to the required users or groups. Nested-group members do not inherit the assignment.
5. Accept the permission request if prompted, review, and finish deployment.

The manifest requests Office permission `ReadWriteMailbox` and Outlook Mailbox requirement set 1.14. This Office permission is separate from the historical reader's Graph application permissions.

See Microsoft's [deployment requirements](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/centralized-deployment-of-add-ins?view=o365-worldwide) for administrator roles and licenses. Microsoft documents up to 24 hours for initial deployment and up to 72 hours for updates or on/off changes in its [deployment FAQ](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/centralized-deployment-faq?view=o365-worldwide).

The manifest loads the Teleskope-managed add-in bundle. Routine bundle fixes do not require reinstalling the manifest. Changes to the manifest itself, including its native send fallback after a degraded-posture change, require downloading and deploying the updated manifest.

### 6. Enable and verify outbound protection

1. Open **Scan settings > Outbound** and switch **Outbound protection** to **Enabled**. Saving configuration alone does not activate protection.
2. Send a benign message from an assigned pilot account on each Outlook client you intend to support.
3. Confirm **Last check received** updates under **Enrollment > Outlook add-in**.
4. Exercise your **WARN** and **BLOCK** policies with synthetic test content:
   * For **WARN**, choose **Review message**, enter a response, and select **Submit response and send**. On clients showing **Save response**, save it and send again from Outlook. The final send checks the current draft again.
   * For **BLOCK**, confirm sending is prevented, remove the triggering content, and verify the revised message can send.
5. Confirm assignment covers all intended users before expanding enforcement.

Enabling outbound protection does not enable historical mail.

## Troubleshooting

| Symptom                                                     | Check                                                                                                                                                                                  |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No field for historical app credentials**                 | This is expected. Arrange credential provisioning with Teleskope, then use **Enrollment > Microsoft Entra connection > Test connection**.                                              |
| **Test connection fails**                                   | Confirm the Graph reader credential is provisioned, `Mail.Read` and `User.Read.All` are application permissions with admin consent, and the tenant has an accessible Exchange mailbox. |
| **Historical mail cannot be enabled**                       | Save the tenant connection and mailbox scope, test the connection, and set a non-future start date and valid schedule.                                                                 |
| **Historical inventory is empty**                           | Check the saved mailbox scope. An empty allowlist scans nothing; entries must identify mailboxes exactly, without groups or wildcards.                                                 |
| **Token has the wrong audience or scope**                   | Use the protected API app's client GUID as **API audience**, set v2 access tokens, expose `access_as_user`, and grant the separate add-in client access to that permission.            |
| **Outbound protection cannot be enabled**                   | Save the API audience and add-in client ID under **Enrollment**, then save the selected degraded posture under **Scan settings > Outbound**.                                           |
| **Add-in does not appear**                                  | Check deployment assignment, client requirements, and Microsoft's propagation window. Nested-group members do not inherit assignment.                                                  |
| **Outlook still behaves incorrectly after a bundle update** | Close all Outlook windows and reopen Outlook to reload the add-in. If the issue persists, share the exact Outlook version/build and test time with Teleskope.                          |
| **External-recipient policies match unexpectedly**          | Review company-wide internal domains under **Settings > Organization**. With none configured, every recipient is treated as external.                                                  |

## Data handling

Teleskope processes message content and attachments for classification. The Data Catalog retains resource metadata, fingerprints, scan state, classification results, and policy information. Outbound subjects are retained for catalog display when message content is prepared; historical inventory does not retain the raw subject.

Recipient information is used for policy conditions, including internal/external comparisons. Send records retain decision and policy metadata. The sender review displays policy information and detection categories/counts, not matched sensitive values.

Message bodies and attachment bytes are not retained as catalog content. Authorized previews retrieve content from Microsoft Graph; processing and preview delivery can involve temporary content storage. Contact Teleskope for the retention settings applicable to your deployment.

## Supported clients and limitations

Outbound protection requires both Outlook Smart Alerts and nested app authentication. Basic Smart Alerts support alone is insufficient.

| Client                                                  | Requirement                                                              |
| ------------------------------------------------------- | ------------------------------------------------------------------------ |
| Outlook on the web                                      | Supported Microsoft 365 work or school mailbox                           |
| New Outlook for Windows                                 | Support for Smart Alerts and NAA                                         |
| Classic Outlook for Windows, Microsoft 365 subscription | Version 2409, build 18025.20000 or later, with the required Outlook APIs |
| Outlook for Mac                                         | Version 16.89, build 24090815 or later, with the required Outlook APIs   |

These are Microsoft platform requirements, not a claim that every build has been individually tested. Consult Microsoft's [NAA client requirements](https://learn.microsoft.com/en-us/javascript/api/requirement-sets/common/nested-app-auth-requirement-sets?view=word-js-preview) and [Smart Alerts support](https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/onmessagesend-onappointmentsend-events), including separate Windows perpetual and LTSC requirements, and validate your deployed client during the pilot.

Outbound protection does not cover Outlook for iOS or Android, other unsupported clients, or users without the add-in assignment. Historical mail runs server-side and is independent of these client limitations.