Skip to content

Microsoft 365 mailboxes

Enterprise feature (new in 1.20.7, helpdesk). See the Helpdesk overview and the Email channel.

If your help addresses live in Microsoft 365 (Exchange Online), the desk can read them directly. Nothing is forwarded and no inbound mail provider sits in between: the desk talks to Microsoft Graph only. It does not use EWS or IMAP.

  • New mail arrives at once. Microsoft tells the desk when a message lands (a change notification), and the desk fetches it. A check on a timer is the safety net, and the only way for an install Microsoft can’t reach.
  • The app sees your help mailboxes and nothing else. You limit it in Exchange Online, and the page tells you what it can reach.
  • Replies can leave as the mailbox, so they show in its Sent Items.
  • Every rule of the email channel still applies: who may write in, sender checks, reply threading, attachments, meeting invites, loops and duplicates. See What happens to a message.

The inbound webhook keeps working as it is. You can use both: some addresses on Microsoft 365, others forwarded.

Shared mailboxes Yes. This is the usual choice for help@yourcompany.com.
User mailboxes Yes.
Aliases Yes, with one condition: see Which address a mail was sent to.
Distribution lists No. A list has no mailbox to read. Use a shared mailbox.
Microsoft 365 groups No. An app can’t read a group’s mailbox this way. Use a shared mailbox.
Mail contacts, mailboxes in another organization No.
On-premises Exchange mailboxes No. The mailbox must be in Exchange Online.

One Microsoft 365 organization (tenant) can be connected per workspace.

Desk settings → Email → Microsoft 365.

Capability
Set up, change or remove the connection (the app registration) Helpdesk settings
Connect or disconnect a mailbox, change how a mailbox is looked up Helpdesk settings
Everything else on the card: Check access, Check now, Try again, Last messages, Options, placing a help address on a connected mailbox Email channel

The first two decide which mailboxes the desk reads, so they take the higher capability. Someone with Email channel alone sees the card without those controls, and a line saying who to ask.

Set up automatically with Microsoft signs you in once as a tenant admin (you enter a short code at microsoft.com/devicelogin) and creates an app registration named CompassDocs Helpdesk Mail, with a client secret that is stored encrypted. The sign-in asks for one permission, Application.ReadWrite.All, uses it for these calls and keeps nothing.

The app is created with no Microsoft Graph mail permission at all. That is on purpose: it can’t read any mailbox until you allow it in step 3.

To do it by hand instead, open Enter an app registration by hand:

  1. In the Microsoft Entra admin center, register an app (single tenant).
  2. Add a client secret and copy its Value.
  3. Do not add Mail.Read, Mail.ReadWrite or Mail.Send under API permissions. Granted there, they reach every mailbox in your organization (see Limit the app).
  4. Enter the tenant ID, the application (client) ID and the secret, and choose Connect. The desk signs in with them before it saves anything, and says why if Microsoft refuses.

Under Mailboxes, enter the main address of each help mailbox (not an alias) and choose Connect mailbox.

Straight after the setup the app may not read the mailbox yet, so it is listed as Waiting for access. That is expected: the next step needs the list of mailboxes first.

An address that is not a mailbox is refused, with the reason: “Distribution lists, Microsoft 365 groups, mail contacts and mailboxes in another organization can’t be connected. Use a shared mailbox instead.”

The address may hold letters, digits, dots, hyphens, underscores and apostrophes before the @. Other characters are refused, because the address goes into the commands you run in step 3.

A connected mailbox is not read until a help address lives on it (step 4). Until then its row says “No help address lives here yet, so it is not being read”. Mail that was already in the Inbox, and mail that arrives before a help address is placed on the mailbox, is left alone. The desk takes in what arrives from then on.

Microsoft looks a mailbox up by its object ID or its sign-in name (user principal name). When the mailbox’s address is also its sign-in name, which is the usual case, you can leave this empty.

Open Advanced and fill it in when:

  • Microsoft “found no mailbox with that address” although the mailbox exists. Its sign-in name is then something else (common for shared mailboxes whose address was changed);
  • a mailbox’s notifications fail with “Microsoft 365 could not look this mailbox up for notifications (error 503)”. Microsoft recommends the object ID for notifications;
  • the address has an apostrophe. Such a mailbox is read on the timer until it has an object ID.

The object ID is best: it always names one mailbox. The commands in step 3 print both values for each mailbox (Get-EXOMailbox … | Format-List UserPrincipalName, ExternalDirectoryObjectId). You can also set or change it later under Advanced on the mailbox’s row. The one-click setup does not look it up for you: that would take a directory permission the app is deliberately not given.

This is the one step you run yourself. Microsoft has no way to do it through Microsoft Graph, so the desk can’t do it for you.

Open Limit the app to your help mailboxes. The page shows the exact commands for your app and your mailboxes, with Copy commands. Run them in Exchange Online PowerShell (the ExchangeOnlineManagement module) as an Exchange administrator (a member of Organization Management). They:

  1. tell Exchange about the app (New-ServicePrincipal);
  2. make a scope that names your help mailboxes and nothing else (New-ManagementScope, with the filter EmailAddresses -eq 'help@yourcompany.com' -or …);
  3. give the app two roles over that scope only (New-ManagementRoleAssignment):
    • Application Mail.ReadWrite: read new mail, mark it read or move it;
    • Application Mail.Send: send replies as the mailbox;
  4. print each mailbox’s sign-in name and object ID (Get-EXOMailbox). This changes nothing;
  5. show what Exchange has on record (Test-ServicePrincipalAuthorization … | Format-Table RoleName, GrantedPermissions, AllowedResourceScope, InScope). InScope should read True for both roles. The mailbox is named by its object ID when you gave one, else by its address. If Exchange can’t find it by the address, use the object ID from the line before.

Every value in the block is written as a single-quoted PowerShell literal, so nothing in it is expanded or run.

This is Microsoft’s RBAC for Applications. It replaces the older application access policies (New-ApplicationAccessPolicy), which Microsoft says not to create any more.

When you connect or disconnect a mailbox later, run the shorter block under Later, when you connect or disconnect a mailbox. It rewrites the scope.

Microsoft can take from 30 minutes to 2 hours to apply a change.

If you would rather manage a group. Instead of naming addresses, the scope can be “the direct members of a group”: make the scope with the filter MemberOfGroup -eq '<the group's distinguished name>' (find the name with Get-Group). Members of nested groups are not in scope. Microsoft 365 groups, mail-enabled security groups and distribution lists can be used this way. You then add a mailbox to the group instead of running the shorter block. The desk’s generated commands always name addresses.

Then choose Check access. The desk signs in afresh and reports:

  • whether the app holds mail permissions granted in Entra (see below);
  • whether each connected mailbox can be read;
  • optionally, whether a mailbox the desk should not reach is refused. Enter any other mailbox, such as your own, in A mailbox the desk should not reach. “Microsoft 365 refused, as it should” is the answer you want.

“This app can read every mailbox in your organization”

Section titled ““This app can read every mailbox in your organization””

The two kinds of permission add up. An Exchange scope limits nothing while a mail permission is granted to the app in Entra: Mail.Read, Mail.ReadWrite, Mail.Send, Mail-Advanced.ReadWrite.All, or any of MailboxItem.*.All and MailboxFolder.*.All.

The desk reads what the app’s own sign-in carries when the connection is saved, every half hour, and when you press Check access. If it finds such a permission:

  • the warning is at the top of the card until the permission is gone. You do not have to press anything to see it;
  • connecting a mailbox asks first. Microsoft will not stop the desk from reading any mailbox you name, so the page asks you to confirm, and the audit log records that you did;
  • the change is in the audit log.

Remove the permission from the app in Entra (App registrations → API permissions) once the Exchange roles are in place.

Under Addresses, add or edit a help address and pick its Microsoft 365 mailbox. A help address with the same address as a mailbox is placed on it when you connect the mailbox. An alias picks the mailbox it is an alias of.

A help address shown with the Microsoft 365 chip is read from its mailbox. You don’t forward it to the webhook, and you don’t need to turn the webhook on.

Each connected mailbox says how its mail arrives, when it was last read, and how many messages were taken in and dropped.

  • Notifications on. Microsoft posts a notification to your desk the moment mail arrives, and the desk fetches the message. The desk also checks every 15 minutes as a safety net. Notifications are renewed in the background.
  • On a timer. The desk checks every few minutes (Options → Check every, 1 to 60 minutes, 2 by default). This is used when:
    • you turned Notifications from Microsoft off;
    • Microsoft can’t reach your desk. Notifications need a public https address. An install on a private network reads on the timer, and the page says so;
    • Microsoft refused the notification subscription. The reason is on the row, and the desk tries again every 15 minutes.
  • Not being read. No help address lives on the mailbox yet, or the connection was removed.

Microsoft notifies the address shown under Options → Notifications from Microsoft: the one the desk was open at when the connection was saved. If you move the desk to another address, open the desk there and choose Send notifications here.

Check now reads a mailbox at once and says what happened.

A message is taken in once, whatever delivers it: a notification, the timer, a restart, or two app instances at the same time. Only the Inbox is read: a notification about a message that lies in another folder is not acted on.

Options → After a message is taken in:

  • Mark it as read (the default). The message stays in the Inbox.
  • Move it to a folder. The message is marked read and moved to Processed (or the name you give). The folder is made if it is missing.

Mail the desk drops (an auto-reply, a duplicate, its own mail coming back, a refused sender, a message with no sender address) is marked or moved too, so the Inbox doesn’t fill up.

The desk tells two kinds of trouble apart.

  • Microsoft did not answer, or said “try later” (a timeout, a network problem, “too many requests”, an error at Microsoft’s end, a problem with the app’s sign-in or access), or the desk itself was busy. The message waits and is tried again: after a minute, then two, four and so on up to half an hour, or as long as Microsoft asks. This does not use up a try. The row shows “1 waiting to be tried again”. After a week of it the desk stops.
  • Microsoft or the desk refused this message. It is tried again at each read, five times. Then it is left in the Inbox, unread, and the row says “1 message could not be taken in”.
  • Microsoft refused access to one message (403) while the rest of the mailbox still reads (1.20.25). That is about the message, not the connection: it is given up after two tries and shown with Microsoft’s error code, instead of waiting for a week.

Try again on the row starts such messages over. From 1.20.25, Try now on a waiting message in Last messages tries it at once, and Try all waiting now on the row tries every waiting message.

A large attachment that Microsoft does not hand over in time does not hold a message back for good. After two waits the message is taken in without that file, and a note on the ticket names it. The email is still in the mailbox with the file.

To keep a flood from costing much, the desk reads a message’s headers first. Its own mail coming back, automatic mail and a message it already has are dropped without downloading attachments. More than 20 messages from one sender in 10 minutes, or more than 300 messages a minute in all, wait as above (the same limits as the webhook). From 1.20.25 the per-sender limit can be set from 5 to 200 under Desk settings → Email → Who can write in, and trusted senders listed there (an address, or @ and a domain, such as a docketing system or a scanner) are never dropped as automatic mail and are held only to 300 in 10 minutes. A trusted sender must still pass the sender check; loops and duplicates still apply.

Each mailbox has Last messages: for the last few messages, when each arrived, the sender’s domain, how the sender check went, and what became of the message.

Passed Microsoft’s results verify the sender.
Failed Microsoft evaluated the message and it did not pass.
Internal Exchange marked it as mail from inside your organization.
No result Exchange wrote no results at all, and no internal mark.

Under each is one line saying what the desk found in Microsoft’s headers, for example AuthAs stamp: anonymous; first of 1 Authentication-Results: spf=pass, dkim=pass, dmarc=pass, compauth=pass (reason 100).

From 1.20.25 each dropped or waiting line also says why in words, for example “Automatic mail (List-Unsubscribe header)”, “Already taken in as #1047 (it was also sent to itsupport@)”, “Sam Lee’s account can’t use Get help”, “Too many messages from this sender. Tries again at 10:42”, or Microsoft’s own error code, with a link to the setting that would change it. A waiting line has Try now.

Take in anyway on a dropped line (for whoever manages email settings) reads the message again and skips only the rule that dropped it: automatic mail, an outside sender, or a colleague who can’t use Get help. The desk’s own mail coming back and blocked contacts are never taken in, and an “already taken in” line offers its ticket instead. Each one is audited (helpdesk.m365.taken_in_anyway).

No subject or text of a message is kept or shown here, and an outside sender’s address never appears; a colleague’s CompassDocs account can be named to admins. Use it when a colleague’s mail is treated as outside mail, when mail is dropped or waiting, or when you first connect a mailbox and want to see how your organization’s mail is read.

A colleague whose account can’t use Get help is no longer dropped while Accept mail from outside the workspace is on: their mail becomes a ticket from an outside sender, not linked to their account, with a note saying why. Give their role Get help to link it.

When several help addresses share one mailbox, the desk reads the To and Cc lines of the message to tell them apart, exactly as it does for the webhook. Team aliases see only the addresses the mail names. Mail that names none of them (it was on Bcc) counts as mail to the mailbox’s own help address.

Aliases need a setting in Microsoft 365. By default Exchange Online rewrites an alias on a message to the mailbox’s main address (SendFromAliasEnabled is off). Mail sent to billing@ then looks like mail to help@, and is handled as mail to help@. To route by alias, turn the setting on for your organization:

Terminal window
Set-OrganizationConfig -SendFromAliasEnabled $true

It affects all mail in the organization, so read Microsoft’s notes on it first. Without it, use a separate shared mailbox for each help address that needs its own team. Replies to a ticket are not affected: they thread by the reply address whichever way the setting is.

Replies thread by the reply address (help+hd-…@yourcompany.com), the reference in the subject, or the mail’s thread headers. Plus addressing is on by default in Exchange Online. If your organization turned it off (Set-OrganizationConfig -DisablePlusAddressInRecipients $true), mail to the tagged reply address bounces. Replies whose To line is the plain help address still thread by the reference in the subject.

Exchange delivers a meeting invite, and its updates and cancellations, as a meeting message with no .ics attachment. The desk reads the invite from the message itself and handles it exactly as an invite that arrives through the webhook: the ticket’s event is filled in, and an update or a cancellation from the ticket’s own verified requester finds that ticket. The same size limits apply.

From 1.20.28 an email attached to a message in the mailbox, such as one forwarded as an attachment, is saved on the ticket as an .eml file, named after its subject, to download like any other attachment. The same size limits apply. Up to 1.20.27 it was listed as not added.

Other attached Outlook items, such as a calendar event or a contact, and links to cloud files are still not added. A note on the ticket lists them. See Attached emails.

The desk reads Microsoft’s own verdict from each message: the SPF, DKIM and DMARC results Exchange Online writes into the Authentication-Results header on the way in. A header the sender put in the message is never read.

  • DMARC pass for the address the message shows, or SPF or DKIM passing for the sender’s own domain: the sender is verified.
  • A failed check: never trusted. This includes Microsoft’s composite check (compauth=fail, or one of its failure reason codes: 000, 001, 002, 010, 6xx).
  • Results that are all “none” (nothing signed, nothing published) are a failed check. Exchange evaluated the message and nothing passed. dmarc=bestguesspass and compauth=softpass are not a pass either.
  • Mail from inside your organization has no SPF or DKIM result. Exchange marks it as internal, and the desk treats that one mark as a verified sender.
  • No result at all (no results header and no internal mark): unverified, unless you turned on Trust sender addresses without SPF or DKIM results. That switch applies to this case only, never to results that are all “none”.
  • No sender address: the message is dropped.

What a verified and an unverified sender may do is the same as for any other mail: see Sender authentication.

The desk trusts Exchange Online to check mail on its way in, and it trusts the mailbox.

Anyone who can put a message into the mailbox’s Inbox without sending it through Exchange can impersonate a sender. That is: a person with full access to the shared mailbox, another app that may write to it, or an import. Such a message carries whatever headers its author gave it, including “passed” results or the internal mark, and the desk will treat its From address as verified. It could then add to tickets or reply as an agent whose address it shows.

So treat write access to a help mailbox as you treat an agent account:

  • give full access to the shared mailbox only to people you would let act as any of your agents;
  • do not give other apps write access to it;
  • keep this app limited to your help mailboxes (step 3).

Mail that arrives from outside in the normal way cannot do this. Exchange writes its results above anything the sender wrote, and removes the internal mark from outside mail.

Edit a help address that lives on a connected mailbox and, under Send replies from, pick Microsoft 365, as help@yourcompany.com.

Replies about tickets on that address are then sent through Microsoft Graph as the mailbox, and show in its Sent Items. Answers still come back to the help address.

  • It is one choice of Send replies from. Picking a send-from address instead sends through your workspace mail server (SMTP) as before.
  • An address that picks neither keeps sending through SMTP, unchanged.
  • Notices to your own agents always go through SMTP.
  • If Microsoft refuses a reply, it goes out through your workspace mail server from the workspace address instead. The address shows “Microsoft 365 refused a reply…” with the reason until one goes through, and the refusal is in the audit log.
  • Send test on such an address sends through Microsoft 365 and reports Microsoft’s answer.
  • An alias as the From address. Unless your organization has turned on sending from aliases (SendFromAliasEnabled, off by default), people see the mailbox’s main address as the sender of a reply sent from an alias. The address editor says so when you pick it. Answers still thread.
  • A message over about 2.9 MB goes out through SMTP: Microsoft Graph takes at most 4 MB in one request.
  • Disconnect (on a mailbox) stops the desk reading it. Nothing in the mailbox is changed. Its help addresses go back to the webhook.
  • App registration → Remove connection forgets the app registration. The mailboxes stay listed, not read. The notification address is replaced: a new connection gets a new one. Delete the app registration in Entra yourself if you no longer need it, and remove its role assignments in Exchange (Remove-ManagementRoleAssignment).
  • Changing to another app registration turns off the old app’s notifications at Microsoft first.
  • To connect a different Microsoft 365 organization, disconnect the mailboxes first.

Saving or removing the connection, connecting and disconnecting a mailbox (and whether it was confirmed while the app could read every mailbox), changing how a mailbox is looked up, placing a help address on a mailbox, each access check, a change in the app’s organization-wide permissions, a refused notification subscription, a message given up on, Try again, and a refused send are all audited (helpdesk.m365.*). The client secret is never in the log.

Symptom What to check
A mailbox stays Waiting for access The commands under Limit the app have not been run, don’t name this mailbox, or Microsoft has not applied them yet (up to 2 hours). Run Test-ServicePrincipalAuthorization, then Check access.
A mailbox says Not being read No help address lives on it yet. Edit a help address and pick this mailbox.
“This app can read every mailbox in your organization” The app holds a mail permission granted in Entra. Remove it there once the Exchange roles are in place. The desk looks again every half hour, or press Check access.
“Microsoft 365 found no mailbox with that address” The address is a distribution list, a Microsoft 365 group, a contact, an alias, or in another organization. Enter a shared mailbox’s main address. If it is a real mailbox, its sign-in name differs from its address: enter its object ID under Advanced.
“Microsoft 365 could not look this mailbox up for notifications (error 503)” Enter the mailbox’s object ID under Advanced on its row. The desk reads it on the timer meanwhile.
A mailbox reads On a timer Notifications are off, your desk has no public https address, or Microsoft refused the subscription (the row says which). Mail still arrives, a few minutes later.
“Microsoft could not reach this desk’s notification address” Microsoft must be able to POST to https://your-domain/api/helpdesk/m365/notify/…. Allow that path through your firewall or reverse proxy, or turn notifications off.
“Microsoft 365 refused a reply” on a help address The Application Mail.Send role doesn’t cover the mailbox. Run the commands again and use Send test. Replies go out by SMTP meanwhile.
“1 message could not be taken in” The message is still in the Inbox, unread. Open Last messages for what happened, press Try again, or open it in Outlook. The server log has the reason (helpdesk.m365_intake_failed).
“1 waiting to be tried again” Microsoft was busy or unreachable, or a limit was reached. Nothing to do: the desk tries again by itself.
A colleague’s mail is treated as outside mail Open Last messages on the mailbox. It shows how the sender check went and why. See Sender checks.
Mail to an alias lands on the mailbox’s main help address Exchange rewrote the alias to the main address. See Which address a mail was sent to.
Replies sent from an alias show the mailbox’s main address The same setting: SendFromAliasEnabled.
A requester’s reply bounces at help+hd-…@ Your organization turned plus addressing off. Turn it on again: Set-OrganizationConfig -DisablePlusAddressInRecipients $false.
A meeting invite made a ticket with no event The invite was larger than the desk reads, or Microsoft did not hand the message over. The ticket is still there.
The one-click setup says “This build can’t do this setup yet” The enterprise image is older than 1.20.7. Update it, or enter the app registration by hand.
The sign-in is refused after a one-click setup Microsoft takes up to a minute to activate a new app. Press Check access again.
The client secret expired Add a new secret to the app registration in Entra, then App registration → Change app registration or secret.