Connect a Microsoft 365 Mailbox

Goal: Let your workspace read, and send from, Microsoft 365 mailboxes, through an identity of its own in your Microsoft organisation.

In Environment -> Communications, a Microsoft 365 account is one of the mail accounts you can connect. Its choice reads Sign in with Microsoft: "Send and read mail in a Microsoft 365 mailbox." The window opens as a panel: it floats at the right at first, docks anywhere, and keeps your place when you move it. See Node editors and work windows as panels.

OpenX creates OpenX Mail, an application in your own Microsoft organisation, for this one account. It is not the identity your cloud connection uses, so a leak of one does not hand over the other. It reads mail through Microsoft Graph with no person signed in, and its client secret is kept in your workspace's own vault in your landing zone, never at Fathym.

Before you start

• A connected cloud and a provisioned private landing zone, as for every mail account: the client secret is kept in the landing zone's Key Vault.
• You are a workspace owner or an access admin. Only they create the identity, register it, approve access and run the read check; anyone else sees each step without its buttons.
• The administrators in your Microsoft organisation who approve access. Which ones depends on the way you choose:

Who	What they do	Roles that can
Your Microsoft Entra administrator	"Approves the permissions OpenX Mail asks for, in Microsoft."	Privileged Role Administrator or Global Administrator
Your Exchange administrator	"Runs the script that limits OpenX Mail to the mailboxes you named."	Exchange Administrator (in Entra) or Organization Management (in Exchange)

An Application Administrator cannot approve these permissions.

Choose how to connect

The panel shows one step at a time: Choose how to connect, Create the identity, Grant access, then Check.

Way	What OpenX Mail can read	Who acts
Only the mailboxes I name (recommended)	"OpenX Mail reads, and optionally sends from, only the mailboxes you list here."	The Entra and the Exchange administrator
Every mailbox in my organisation (small business)	"One approval, no script. OpenX Mail can read every mailbox until you narrow it."	The Entra administrator

For the first way, list the mailboxes in Mailboxes to read, such as intake@contoso.com, orders@contoso.com. Turn on Send email from this account too to send as well, and name the mailbox in Send as; on the first way it must be one of the mailboxes you listed. The card Who needs to act names the administrators before you go on.

Create the identity

Press Create OpenX Mail identity. It runs with your own Microsoft sign-in and reads "Creating OpenX Mail in your Microsoft organisation…" until it is done. If your sign-in has run out, the panel asks you to sign in again, then press Create again; if Microsoft needs you in the directory this account connects to, it offers that sign-in instead.

If your organisation creates apps itself

Some organisations do not let a person create applications. Press My organisation creates apps itself: the panel shows a PowerShell script that creates the application. Your administrator runs it, and you paste back the Directory (tenant) id, Application (client) id, Service principal object id and Client secret it printed, then press Register. OpenX checks the secret with Microsoft on every Register, so a stored secret is never reused: paste it each time.

Grant access

Every mailbox in your organisation

The step says what the grant means before it offers anything:

• "OpenX Mail can read every mailbox in your organisation, including executives' and HR mail, until you narrow it."
• "It cannot sign in as anyone. With sending on, it can send as any mailbox."
• "You can remove it in Microsoft Entra at any time. Narrowing later means running the scoping script, then removing this grant."

Tick I understand what this grants. Only then does Approve in Microsoft ↗ appear, with Copy link and Email the link to hand it to your Entra administrator.

Only the mailboxes you name

Approve in Microsoft ↗ asks your Entra administrator to let OpenX Mail look people up in your directory. Then the step shows the script that limits OpenX Mail to the mailboxes you named, with Copy script and Email the script for your Exchange administrator. When it has run, press I ran the script.

Approving, and coming back

Approve in Microsoft ↗ opens Microsoft's page in a new tab: "This tab stays open. Come back here when you are done." Microsoft labels OpenX Mail "Unverified". That is expected: it is an application your own organisation owns.

When the approval or the script is done, come back to the OpenX tab and press Check again. While someone still has to act, the step says who: "Microsoft can take up to two hours to apply this" for an approval, and up to two hours to apply the scope after the script. I need to change how I connect goes back to the first step.

Check it, and use it

The Check step says what is true now:

What it says	What to do
The account signs in and can read	Nothing
The tenant-wide mail permission has not been approved	Ask an administrator to approve the permissions, then check again
The scoping script was run recently; Exchange can take up to two hours to apply the scope	Check again later
The account cannot read the mailbox, and the Exchange scope is not in effect	Ask your Exchange administrator to run the scoping script, then check again
OpenX Mail also holds a tenant-wide mail permission, so the scope is not in effect	Remove tenant-wide Mail.Read from the OpenX Mail application, then check again
OpenX Mail cannot look people up in your directory	Ask an administrator to approve User.Read.All for the OpenX Mail application
Microsoft refused the stored client secret: it is wrong or expired, or the application was deleted	Press Create again to mint a new secret
The client secret could not be read from your workspace's own vault	Check the cloud connection, then press Create again if the secret is gone
The account could not read the chosen mailbox	Choose a mailbox the account should read, then check again
The client secret ends soon	Press Create again to mint a new secret before it ends

A scope that is not in effect is shown as a failure, not a warning: mail is not narrowed while it reads that way.

Test reading a mailbox finds mailboxes as you type at least two characters of a name or an address. It lists only the ones OpenX Mail can read, and says how many matches are outside them. Read this mailbox runs the read check on one. A group or shared mailbox is not found by search. With sending on, Send as this mailbox makes a row the sender.

Send a test email

Send a test email sends a real email from the sender to the address you give. It needs the Workspace.Communications.Send right. The result shows each step it reached: Reach the server, Sign in, Allowed to send, Recipient accepted and Message accepted, with a plain reason when one fails. "Accepted means it took the message, not that it has arrived."

After three failed sign-ins in ten minutes, the test and the read check wait a few minutes before trying again, so your mail provider does not lock the account.

A sender on an onmicrosoft.com address shows Microsoft's daily limit: "Microsoft 365 (an onmicrosoft.com tenant) allows 100 external recipients a day. The provider reports a send over the limit by a bounce after sending."

When the secret is about to end

A secret OpenX created ends on a known date. From 30 days before, the account's row reads "Expires in" the days left, with Reconnect, which opens the account: "Press Create again to mint a new secret before it ends." A secret your administrator pasted has no date OpenX knows, so it never warns.

Remove an account

Press Remove on the account's row. The removal says what goes, and it happens at the next Deploy:

• Deleted: "This account's settings in this workspace, and its copy of the client secret in your workspace's own secret vault (the secret moves to that vault's deleted list)."
• Kept: "One small settings file, without the secret, in your landing zone's data archive. It stays until you delete it."
• Stays yours: the mailbox and its mail. The OpenX Mail application OpenX created, and its password, are deleted from your Microsoft directory right after the Deploy, with your Microsoft sign-in. An application your administrator created stays theirs.

After the Deploy, the Mail accounts list shows Removed Microsoft 365 accounts, one row each:

Row reads	Means
Removing its application	OpenX is deleting the application it created
Application removed	"OpenX deleted its OpenX Mail application and its password from your Microsoft directory."
Not finished	It could not finish; press Try again
Finish in Microsoft 365	"OpenX removed this account. An administrator finishes the rest in Microsoft 365 with the script below."

Finish in Microsoft 365 carries the scripts left for an administrator:

• On the first way, the scope: "An Exchange administrator runs this to remove the mailbox limit and OpenX Mail's Exchange entry. OpenX cannot tell whether it has been run." Deleting the application does not remove it.
• For an application your administrator created: "This script takes OpenX's password off it and keeps the application." OpenX never deletes an application it did not create.

Messages you may see

Message	What to do
"Name at least one mailbox for OpenX to read."	List a mailbox, or choose the other way
"This is not a mailbox address OpenX can use. Use letters, digits and . _ % + - only."	Check the address
"The sending mailbox must be one of the mailboxes named above."	Add it to Mailboxes to read, or send as one of them
"Your Microsoft sign-in has expired. Sign in again, then create the identity."	Sign in, then press Create again
"This account is waiting to be removed at the next Deploy. Restore it first, or remove it and connect a new one."	Restore it, or connect a new account
"OpenX Mail has not been given permission to look people up in your directory."	Ask your Entra administrator to approve directory read
"No mailbox OpenX Mail can read matches that."	Check the name, or the scope your Exchange administrator set

Sending through a relay instead

If a relay account's host is smtp.office365.com, the relay form says: "Microsoft is switching off password sign-in for SMTP by default at the end of December 2026. Connect this Microsoft 365 account in Mail accounts and send through it instead."

Next steps

• The other mail accounts -> Communications
• The landing zone that holds the secret -> Manage Private CALZ