> ## 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, not as a user. 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
* Permission to create an app registration in Microsoft Entra and to grant it admin consent
* An Onyx administrator account
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.
## Configure Microsoft Entra
Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com)
(`https://entra.microsoft.us` for GCC High or DoD) and open **App registrations**. Select **New registration**,
name it something like `Onyx Outlook Connector`, leave the other settings as they are, and select **Register**.
On the **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**.
Onyx asks for both.
Open **API permissions**, select **Add a permission**, then **Microsoft Graph** and **Application permissions**.
Add:
* **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**
Select **Add permissions**, then **Grant admin consent** for your organization and confirm.
Open **Certificates & secrets**. Either select **New client secret**,
set an expiration and copy the secret **Value** right away,
or upload the public certificate of a PFX bundle under **Certificates**. Onyx accepts both. For a certificate,
keep the PFX file and its password for the next section.
## Configure Onyx
In Onyx, go to **Admin Panel → Add Connector** and select **Outlook**.
Choose the authentication method and enter the values from Entra:
* **Client Secret**: the client ID, the directory ID and the secret value
* **Certificate Authentication**: the client ID, the directory ID, the PFX bundle and its password
Onyx validates the connector on its first indexing attempt: 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.
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.
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.
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.
Select **Create Connector**. Then open **Admin Panel → Existing Connectors**, select the connector,
and confirm its initial indexing attempt completes.
### 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. For GCC High or DoD, use `https://login.microsoftonline.us`. |
| Graph API Host | `https://graph.microsoft.com` | The Microsoft Graph endpoint. For GCC High, use `https://graph.microsoft.us`. For DoD, use `https://dod-graph.microsoft.us`. |
## 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.
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.
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
| Message or symptom | Cause and fix |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Microsoft rejected the client secret or certificate | The secret or certificate is wrong, expired or belongs to another app registration. Create a new one and update the credential. |
| Microsoft does not know this directory | The directory ID or the authority host is wrong. For GCC High or DoD, set both advanced hosts. |
| 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. |