Office 365 Directory and Mailbox Access – mxHero Help Center

mxHERO connects to Microsoft 365 in two separate ways: a directory source that imports your users and groups, and Office 365 mailbox access that lets mailbox rules read and change mail stored in user mailboxes. Both use Microsoft Graph and need a Microsoft 365 administrator to grant consent. Set up the directory source for every Microsoft 365 organization; set up mailbox access only if you will use User Mailboxes rules.

This page does not cover mail routing. For connectors and transport rules, see Office 365 Configuration Service.

Before you begin

You need a Microsoft 365 account that can grant tenant-wide admin consent, for example a Global Administrator. See Microsoft's Grant tenant-wide admin consent to an application.
You need the Owner or Administrator role in the Admin Dashboard.
Add your domains in Settings › Organization and domains first, or let the directory source add them. See Organization and domains.
Decide which users to import. You can limit the import with filters, for example to one domain or to members of some groups.

What mxHERO is allowed to do

mxHERO uses an application registered by mxHERO in Microsoft Entra ID. When you consent, Microsoft adds it to your tenant as an enterprise application, with application (app-only) permissions.

Purpose	What mxHERO reads or changes	Graph permissions
Directory source	Users, their aliases, groups, group members and verified domains. Read only.	Read access to users, groups and domains
Mailbox rules: Copy Emails, Move Emails	Mail in the selected mailboxes; moves or deletes mail for Move Emails; adds the "processed" category if you turn it on	Mail read/write access
Mailbox rules: Protect Attachments	Imports a copy of each message with links in place of attachments, then deletes the original	`MailboxFolder.Read.All`, `MailboxItem.Read.All`, `MailboxItem.ImportExport.All`

You can review what you granted in the Microsoft Entra admin center under Enterprise applications › the mxHERO application › Permissions.

Connect the Office 365 directory

In the Admin Dashboard, open Settings › Accounts and Groups.
In the Directory Sources panel, click Add Source and choose Office 365.
The Adding Office 365 Source dialog starts a Microsoft sign-in. Sign in with your Microsoft 365 administrator account and accept the permissions.

Back in the dashboard, set the import options. All are optional; leave them empty to import every member user and group.

Option	What it does
Users filter	A Microsoft Graph `$filter` on users, for example `endswith(mail,'@example.com')`.
Groups filter	A Graph `$filter` on groups, for example `startswith(displayName,'Marketing')`.
Only import email accounts that belong to a filtered group	Imports only users who are members of the groups the groups filter returns. Needs a groups filter.
Include nested groups in the filter	Also imports the subgroups of the groups the filter matches. Needs one of the two inheritance options below.
Subgroup members inherit parent groups	On by default. A member of a subgroup also counts as a member of its parent groups, as in Entra ID.
Parent members inherit subgroups	Off by default. A member of a parent group also counts as a member of its subgroups.
Exclude domains	Skips accounts and groups in these domains.
Schedule Daily Synchronization	Runs the sync at a fixed hour in the time zone you choose. Without it, each sync runs 24 hours after the last one.

The two inheritance options can't both be on. See Groups for how they affect rules.

Click the button to save the source. The first sync starts.

What gets imported

Users: each member user, by mail address, or by userPrincipalName if it has no mail address. Guest users are not imported.
Aliases: the user's mail, userPrincipalName, proxyAddresses and otherMails values that are in your mxHERO domains. Other aliases are dropped.
Groups: each group with its mail address and display name, its user members and its member groups.
Domains: the verified domains of the tenant, with their MX host as the domain's Server. Check the Server field of each new domain afterwards. See Domain Server and Relay settings.

Accounts that disappear from the tenant (or from your filter) are deleted from mxHERO at the next sync.

Connect Office 365 mailboxes

Do this if you will create User Mailboxes rules with the Office 365™ for organizations provider.

Open Settings › Integrations and select the Applications tab.
On the Office365 Mailbox card, click Install.
A Microsoft admin consent page opens. Sign in as your Microsoft 365 administrator and click Accept.
Back in the dashboard, check that the card no longer shows Not installed.

You can also start consent from the rule editor: on the Target step of a rule, choose User Mailboxes, then Organization: Office 365™ for organizations. If consent is missing, the consent page opens.

To connect a single mailbox with a user's own sign-in instead, see IMAP and individual mailboxes.

Microsoft Graph and the end of EWS

Microsoft retires Exchange Web Services (EWS) for Exchange Online on October 1, 2026. Since September 2026, mxHERO mailbox rules use Microsoft Graph only. Protect Attachments mailbox rules need three extra Graph permissions (in the table above), so tenants that consented earlier must consent again.

If the permissions are missing, the Office365 Mailbox card shows that consent is needed again. Click it and accept the new permissions.
You can't save an Office 365 Protect Attachments mailbox rule until consent is complete. The rule editor offers a button to grant consent.
For individual Office 365 accounts, the account is flagged in Settings › Integrations › Accounts and must be re-authenticated. The delegated permissions are MailboxFolder.Read, MailboxItem.Read and MailboxItem.ImportExport.

How Protect Attachments works through Graph:

mxHERO imports a new copy of the message with links in place of the attachments. Flags and categories are copied to it.
It then moves the original to Deleted Items and deletes it from there. By default (Delete original email permanently after saving) the original is deleted permanently. If you selected Move original email to Trash folder in the rule's Advanced Options, the original stays in Deleted Items.
Calendar items and sharing invitations are saved to storage but never replaced in the mailbox.

You don't configure anything for change notifications. mxHERO subscribes to new-mail notifications itself for continuously updating rules.

Verify

Directory: in Settings › Accounts and Groups, the Office 365 source shows a recent synchronization with no errors. Search for a few users and check their aliases. Check Group accounts for your groups.
Mailboxes: create a test Copy Emails rule with the User Mailboxes target, the Office 365™ for organizations provider, one test account, and the time range Between two dates in time set to a few days. Save it and open the rule from Rules › Rules List to watch its progress. See Copy Emails.
Check the files in the storage folder.

Troubleshooting

Symptom	Cause	Fix
Sync fails with `ERROR_USERS_FILTER` or `ERROR_GROUPS_FILTER`	The Graph filter is not valid.	Check the syntax in Microsoft's Use the $filter query parameter. Use single quotes around values.
Sync fails with `error_access_token_azuread` or `credential_error`	Consent was removed or never completed.	Remove the source and add it again, signing in as an administrator who can grant admin consent.
Warning `domain_controlled_by_other_organization`	A tenant domain already belongs to another mxHERO organization.	Remove the domain from the other organization, or ignore the warning if that is intended.
Some users are missing	They are guests, are outside your filters, or their aliases are not in your mxHERO domains.	Adjust the filters, or add the accounts by hand.
Saving an Office 365 Protect Attachments mailbox rule asks for consent or re-authentication	The new Graph permissions have not been granted.	Grant consent again on the Office365 Mailbox card, or re-authenticate the individual account.
Mailbox shows `inactive_inbox_account`	The mailbox is inactive, soft-deleted or hosted on-premises, so Graph can't reach it.	Remove the account from the rule, or use a mailbox hosted in Exchange Online.
Mailbox shows `inbox_account_without_permission`	Consent was revoked or the permissions changed.	Grant consent again, then restart the rule's failed accounts.