Outlook

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, or replace the mail and calendar grants with scoped roles through Exchange RBAC for Applications. Keep User.Read.All either way. Exchange takes 30 minutes to two hours to apply such a change.

Configure Microsoft Entra

Create an app registration

Sign in to the Microsoft Entra admin center (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.

Copy the IDs

On the Overview page, copy the Application (client) ID and the Directory (tenant) ID. Onyx asks for both.

Add API permissions

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.

Add a client secret or a certificate

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

Open the Outlook connector

In Onyx, go to Admin Panel → Add Connector and select Outlook.

Create a credential

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.

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.

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.

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.

Connect and verify

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.

Getting Started

Language Models

Connectors

Managing Features

Access Control

Advanced Configs

Auditing

Plans & Billing

Miscellaneous

How it works

Before you begin

Configure Microsoft Entra

Configure Onyx

Advanced settings

Attachments

Auto Sync Permissions

Troubleshooting

​How it works

​Before you begin

​Configure Microsoft Entra

​Configure Onyx

​Advanced settings

​Attachments

​Auto Sync Permissions

​Troubleshooting

How it works

Before you begin

Configure Microsoft Entra

Configure Onyx

Advanced settings

Attachments

Auto Sync Permissions

Troubleshooting