> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Outlook

> Index mail, attachments and calendar events from Exchange Online mailboxes

The Outlook connector indexes mailboxes in your Microsoft 365 tenant through Microsoft Graph.
It reads mail conversations, the text of file attachments, and calendar events,
and it can mirror who may read each item with **Auto Sync Permissions**.

The connector signs in as an app registration set up in [Microsoft 365
Setup](/admins/connectors/official/microsoft-365/setup). It reaches Exchange Online only.
On-premises Exchange Server is not supported.

## How it works

| Content       | Behavior                                                                                                                                                                                                                                                                |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Conversations | One document per conversation per mailbox. Each message contributes its sender, recipients, date and text body, oldest first. Drafts are skipped. Long threads keep their newest 100 indexable messages, found among the newest 500.                                    |
| Folders       | Every indexed folder becomes part of the mailbox's hierarchy. Junk Email, Deleted Items, Drafts and Outbox are always skipped, as are hidden folders and search folders. You can skip more folders by name, and the subfolders of a skipped folder are skipped with it. |
| Attachments   | Optional. The text of file attachments is added to the message it came with. Inline attachments (usually signature images), attached mail items and cloud links are skipped, as are files over 20 MB and file types Onyx cannot parse.                                  |
| Calendar      | Optional. One document per event with its time, location, organizer, attendees and description. A recurring series is indexed once from its master plus any modified occurrence. Cancelled events and events marked private or confidential are skipped.                |
| Permissions   | Optional, on paid plans. The mailbox owner can see everything in the mailbox. An event is also visible to its organizer and attendees.                                                                                                                                  |

Each refresh reads the messages each folder received since the last run and rebuilds every conversation that gained one.
A conversation that only lost a message keeps its old text until it gains a message or the connector is re-indexed.
Pruning removes conversations that no longer exist and calendar events that have left the calendar window.

## Before you begin

You need a Microsoft 365 tenant with Exchange Online mailboxes and the roles listed in [Microsoft 365
Setup](/admins/connectors/official/microsoft-365/setup#before-you-begin).

<Note>
  The app registration can open every mailbox in the tenant by default. To limit it to specific mailboxes,
  either restrict the Graph grants with an [application access
  policy](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access),
  or replace the mail and calendar grants with scoped roles through [Exchange RBAC for
  Applications](https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac).
  Keep **User.Read.All** either way. Exchange takes 30 minutes to two hours to apply such a change.
</Note>

## Configure Microsoft Entra

Follow [Microsoft 365 Setup](/admins/connectors/official/microsoft-365/setup)
with the Outlook rows of its [permission table](/admins/connectors/official/microsoft-365/setup#permissions).
What each grant is for:

* **Mail.Read**: read mail and attachments in every mailbox the app may open
* **User.Read.All**: list the tenant's users, resolve mailbox addresses and build permission lists
* **Calendars.Read**: read calendars, only needed when you turn on **Include Calendar**

A client secret or a certificate both work. Outlook reads no SharePoint API, so nothing here needs a certificate.

## Configure Onyx

<Steps>
  <Step title="Open the Outlook connector">
    In Onyx, go to **Admin Panel → Add Connector** and select **Outlook**.
  </Step>

  <Step title="Create a credential">
    Select an existing Outlook credential or create one as described in [Microsoft 365
    Setup](/admins/connectors/official/microsoft-365/setup#enter-the-credential-in-onyx).

    Onyx validates the connector when you save it: the app can sign in,
    and the tenant's users can be listed or each listed mailbox is reachable. During indexing,
    a mailbox or calendar the app may not open is recorded as an error naming the missing permission when you listed the
    mailbox, and skipped with a log line in every-mailbox mode.
  </Step>

  <Step title="Choose the mailboxes">
    Give the connector a name. In **Mailboxes**, list the user principal names or primary email addresses to index,
    or leave the list empty to index the mailbox of every enabled user who has a mail address.

    Shared mailboxes are normally sign-in disabled, so automatic discovery does not pick them up. List them explicitly.
  </Step>

  <Step title="Choose what to index">
    Turn on **Include Attachments** to index the text of file attachments and **Include Calendar** to index each
    mailbox's calendar as well as its mail. Both are off by default.
  </Step>

  <Step title="Choose the access type">
    Select the connector access type:

    * **Public** makes all indexed mail visible to every Onyx user.
    * **Private** limits the connector to selected Onyx user groups.
    * **Auto Sync Permissions** mirrors mailbox ownership and meeting attendance.

    **Private** and **Auto Sync Permissions** are paid features: the Business and Enterprise tiers on Onyx Cloud,
    and the Enterprise Edition when self-hosted.
  </Step>

  <Step title="Set an indexing start date">
    Under **Advanced Configuration**, set an **Indexing Start Date** unless you need every message ever received.
    Without one, the first indexing attempt reads each mailbox from its first message,
    and a tenant with years of mail in many mailboxes takes days to become searchable. With a start date,
    Onyx indexes the conversations that received a message on or after it and skips the rest.
    The calendar has its own window, set by **Calendar Past Days** and **Calendar Future Days** below.
    See [Advanced Configuration](/admins/connectors/overview#advanced-configuration).
  </Step>

  <Step title="Connect and verify">
    Select **Create Connector**. Then open **Admin Panel → Existing Connectors**, select the connector,
    and confirm its initial indexing attempt completes.
  </Step>
</Steps>

### Advanced settings

| Setting              | Default                             | Purpose                                                                                                                                                                                           |
| -------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Excluded Folders     | empty                               | Whole folder names to skip in every mailbox, in addition to the folders that are always skipped. Names are matched without regard to case, and a skipped folder's subfolders are skipped with it. |
| Calendar Past Days   | 365                                 | How far back the calendar window reaches. Events older than this leave the index at the next prune. Widening it later needs a re-index, since unchanged events do not re-enter on their own.      |
| Calendar Future Days | 180                                 | How far ahead the calendar window reaches. Widening it later also needs a re-index.                                                                                                               |
| Authority Host       | `https://login.microsoftonline.com` | The Microsoft identity endpoint. See [National clouds](/admins/connectors/official/microsoft-365/setup#national-clouds).                                                                          |
| Graph API Host       | `https://graph.microsoft.com`       | The Microsoft Graph endpoint. See [National clouds](/admins/connectors/official/microsoft-365/setup#national-clouds).                                                                             |

## Attachments

With **Include Attachments** on, Onyx downloads each file attachment and appends its text to the message it came with.
Onyx parses these types: `.csv`, `.docx`, `.eml`, `.epub`, `.html`, `.json`, `.md`, `.mdx`, `.pdf`, `.pptx`, `.tsv`,
`.txt`, `.xlsx`, `.xlsm`, `.xml`, `.yaml`, `.yml`, `.conf`, `.log` and `.sql`.

A message contributes at most 20 attachments, and a conversation stops downloading after 25 download attempts,
failed ones included, or one million characters of attachment text.
Set `OUTLOOK_CONNECTOR_ATTACHMENT_SIZE_THRESHOLD` (bytes) to change the 20 MB (20 × 1024 × 1024 bytes) size limit.

## Auto Sync Permissions

With **Auto Sync Permissions**, Onyx grants access by email address.
A mailbox's address must match the user's email in Onyx.

| Outlook item              | Who can see it in Onyx                                     |
| ------------------------- | ---------------------------------------------------------- |
| Folders and conversations | The owner of the mailbox                                   |
| Calendar events           | The owner of the mailbox, the organizer and every attendee |

Permissions are attached during indexing,
so a new connector is searchable by the right people from its first indexing attempt.
A permission sync then runs every 5 minutes by default and updates the access lists of existing documents.
Set `OUTLOOK_PERMISSION_DOC_SYNC_FREQUENCY` (seconds) to change the interval.

<Warning>
  A shared mailbox has no owner who signs in to Onyx,
  so its conversations stay hidden under **Auto Sync Permissions** unless an Onyx account carries the mailbox's own
  address. Delegate access to a shared mailbox is not synchronized. To make a shared mailbox searchable,
  index it with a separate connector set to **Private** and assign the user groups who should see it.
</Warning>

Permission sync uses the same **Mail.Read** and **Calendars.Read** grants as indexing and needs no further Graph
permission. **User.Read.All** supplies the owner addresses. Both authentication methods support it.

## Troubleshooting

See [Microsoft 365 Setup](/admins/connectors/official/microsoft-365/setup#troubleshooting)
for the messages every Microsoft 365 connector can show.

| Message or symptom                        | Cause and fix                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The app cannot look up the tenant's users | Grant **User.Read.All** as an application permission and admin-consent it.                                                                                                                                                                                                                                           |
| Graph reported `ErrorAccessDenied`        | Either **Mail.Read** (or **Calendars.Read**) is missing, or the mailbox sits outside the app's Exchange scope. Grant the permission or add the mailbox to the scope, then wait up to two hours.                                                                                                                      |
| These mailboxes cannot be indexed         | An address in **Mailboxes** matches no user, or Graph found no mailbox behind it or refused it because it sits outside the app's Exchange scope. Use the user principal name or primary SMTP address, and add scoped mailboxes to the app's scope. Shared mailboxes usually need no license, only an explicit entry. |
| Calendar events are missing               | Turn on **Include Calendar** and grant **Calendars.Read**. Events outside the past and future day windows are not indexed, and widening a window needs a re-index.                                                                                                                                                   |