Skip to main content
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. It reaches Exchange Online only. On-premises Exchange Server is not supported.

​
How it works

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.
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

Follow Microsoft 365 Setup with the Outlook rows of its permission table. 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

1

Open the Outlook connector

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

Create a credential

Select an existing Outlook credential or create one as described in Microsoft 365 Setup.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.
3

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.
4

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.
5

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.
6

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.
7

Connect and verify

Select Create Connector. Then open Admin Panel → Existing Connectors, select the connector, and confirm its initial indexing attempt completes.

​
Advanced settings

​
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. 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

See Microsoft 365 Setup for the messages every Microsoft 365 connector can show.