How organization-wide mailbox access works, the exact Microsoft Entra permissions MailboxOS needs, and how to fix the errors you may see when setting it up or browsing mailboxes.
The tenant connector is an app registration you create and control in your own Microsoft Entra (Azure AD) tenancy. You grant it read-only permission, then enter three values — Directory (tenant) ID, Application (client) ID, and a client secret — under Settings → Tenant Connector. No MailboxOS software runs inside your tenancy, and you can revoke access at any time by deleting the app registration (or its secret) in Entra, or removing the connector in Settings.
Both are Application permissions on Microsoft Graph (not delegated), and both need admin consent:
| Permission | Type | Why MailboxOS needs it |
|---|---|---|
| Mail.Read | Application | Reads and analyzes the mailboxes you submit. This is the core mail-export permission. Read-only — MailboxOS can never send, modify, or delete mail. |
| User.Read.All | Application | Powers the Browse mailbox pick-list (in New Analysis and Settings). It reads your directory so users can choose a mailbox from a searchable list instead of typing addresses. Directory access is separate from mail access — without it, mail export still works but Browse cannot list mailboxes. |
Mail works but Browse doesn't? That is the classic symptom of a
connector that has Mail.Read but is missing
User.Read.All (or its admin consent). Add it using the steps
below.
Mail.Read and User.Read.All, then Add permissions.The client secret you entered has an expiry date (set when you created it under Certificates & secrets). When it expires, exports and Browse stop working until you rotate it: create a new client secret in Entra, copy its Value (not the Secret ID), then re-enter it under Settings → Tenant Connector → Replace credentials. Put a calendar reminder a couple of weeks before the expiry date.
| Message in MailboxOS | What it means & how to fix it |
|---|---|
| The tenant connector isn't set up yet. | No connector has been saved for your organization. Add your Entra app credentials under Settings → Tenant Connector. (You need the owner or admin role.) |
| Microsoft rejected the connector's sign-in. | The stored credentials no longer work: the client secret has
expired or was changed (AADSTS7000222 /
AADSTS7000215), or the app / tenant details are wrong
or the app was removed (AADSTS700016). Rotate the
secret (see above) or re-check the Directory and Application IDs,
then re-save under Settings → Tenant Connector. |
| The connector can sign in and read mail, but it isn't allowed to list mailboxes. | The app is missing the User.Read.All application
permission or its admin consent (Graph returns
Authorization_RequestDenied). Add
User.Read.All and grant admin consent using the
steps above, then try Browse again. Mail export is
unaffected in the meantime. |
| Couldn't reach Microsoft just now. | A temporary network, throttling, or Microsoft service issue. Wait a moment and try again. If it persists, check the Microsoft 365 service status. |
For the full IT-admin walkthrough — creating the app registration, creating
a secret, and scoping mail access to specific mailboxes — see the
Tenant Connector Setup Guide (docs/CONNECTOR_SETUP.md),
linked from the Settings → Tenant Connector card.