Integration setup · for IT
For the administrator of the customer's Microsoft 365 tenant. Everything is configured inside your own tenant; roughly 20 minutes.
This page was almost certainly forwarded to you by a colleague who is setting up a BestTeam mailbox. What they are reading is the same procedure written for a non-administrator — worth a glance if you want to see what has been asked of them.
IMAP.AccessAsAppoutlook.office365.com:993, SASL XOAUTH2https://outlook.office365.com/.defaultSELECT, FETCH, SEARCH, and APPEND to Drafts. No \Deleted, no EXPUNGE, no SMTPXOAUTH2, which is the modern-auth path Microsoft provides for IMAP.IMAP.AccessAsApp is not a Graph mail permission. It enables the IMAP protocol for the application. It grants no access to the Microsoft Graph mail API, no Mail.Read/Mail.ReadWrite, and nothing outside Exchange.It polls the mailbox every few minutes, reads new messages, and APPENDs reply drafts to the Drafts folder. It never sends: the product has no SMTP client and no send operation anywhere in it, so a draft leaves the tenant only when a person opens it in Outlook and presses send.
Message bodies are redacted before anything is stored on our side. Attachments are parsed as text (PDF, Word, Excel, XML, plain text); images are not OCR'd.
| Step | Role |
|---|---|
| App registration | Application Administrator (or Global Administrator) |
| Grant admin consent for an application permission | Global Administrator or Privileged Role Administrator |
New-ServicePrincipal, Add-MailboxPermission,New-ApplicationAccessPolicy | Exchange Administrator (or Global Administrator) |
BestTeam, or your own conventionFrom Overview, record the Directory (tenant) ID and the Application (client) ID.
Then Grant admin consent. Remove the default User.Read delegated permission if your baseline requires it; it is not used.
Record the Value (not the Secret ID) and the expiry date. The Value is retrievable only at creation.
The Object ID below is the service principal's object ID — Entra ID → Enterprise applications → your app → Object ID. It is not the object ID shown on the App registration blade.
The client secret is not needed here and this page never asks for it. Values stay in your own browser.
Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser
Connect-ExchangeOnline -UserPrincipalName <admin-upn>New-ServicePrincipal -AppId <application-id> -ServiceId <sp-object-id> -DisplayName "BestTeam"
Add-MailboxPermission -Identity <mailbox> -User <sp-object-id> -AccessRights FullAccessNew-ServicePrincipal fails with already exists on tenants where Exchange has already synced the principal; that is benign, continue.
FullAccessFullAccess on the target mailbox is what Microsoft's app-only IMAP flow requires — there is no narrower mailbox right that permits IMAPSELECT and APPEND. It is granted on one mailbox, not tenant-wide, and step 5 is what prevents the application from using its permission against any other mailbox. If you skip step 5, the permission is effectively tenant-wide.
A shared mailbox is a good fit here and needs no licence under the usual size limit. If the mailbox does not exist yet, create it as a shared mailbox rather than a licensed user.
New-ApplicationAccessPolicy -AppId <application-id> -PolicyScopeGroupId <mailbox> -AccessRight RestrictAccess -Description "BestTeam: single mailbox"Test-ApplicationAccessPolicy -Identity <mailbox> -AppId <application-id>Disconnect-ExchangeOnlineScope to a mail-enabled security group instead of a single address if that fits your model better — pass the group as -PolicyScopeGroupId.
If you already use RBAC for Applications for this class of scoping, it is a reasonable substitute for the access policy. We have verified this integration against New-ApplicationAccessPolicy and not against RBAC for Applications, so if you take that route, tell us and expect one extra round of testing.
| Value | Where |
|---|---|
| Directory (tenant) ID | Step 1, Overview |
| Application (client) ID | Step 1, Overview |
| Client secret Value | Step 3 |
| Secret expiry date | Step 3 |
Plus the mailbox SMTP address.
The expiry date is not decorative: we store it and warn a month ahead. Without it, the first symptom of expiry is a mailbox that silently stops being processed, with an error indistinguishable from a wrong secret.
Outbound from our host only:
| Destination | Port | Purpose |
|---|---|---|
login.microsoftonline.com | 443 | Token acquisition |
outlook.office365.com | 993 | IMAP over TLS |
Nothing connects inbound to your network, there is no on-premises component, and no service account of yours is used for interactive sign-in. Tokens last about an hour and are refreshed roughly a minute before expiry.
The error our side reports distinguishes these, because the fixes differ:
| Symptom | Cause |
|---|---|
| Token request rejected | Wrong tenant ID, wrong client ID, or wrong/expired secret — most often the Secret ID was handed over instead of the Value |
Token issued, AUTHENTICATE XOAUTH2 refused | Admin consent missing (step 2), the step 4 commands not run, or the access policy excludes this mailbox (step 5) |
| Mailbox not found | Address is not a mailbox in this tenant, or it is a distribution list or a Microsoft 365 group rather than a mailbox |
Why IMAP rather than Graph?
The per-organisation mailbox path in this product is IMAP with XOAUTH2. IMAP.AccessAsApp also has a narrower blast radius than Mail.ReadWrite: it enables one protocol rather than the whole Graph mail surface.
Can it be scoped to a folder?
No. Neither IMAP permissions nor application access policies scope below the mailbox. The mailbox is the unit, which is the argument for pointing this at a dedicated shared mailbox rather than someone's personal one.
Can we use a certificate instead of a secret?
Not in the current build. See the note in step 3.
What happens if we delete the access policy?
The application regains the ability to reach every mailbox in the tenant, up to the limit of its IMAP.AccessAsApp grant. Keep the policy.
Anything unclear or refused by your policy, tell the person who sent you this document, or write to us directly at admin@bestteam.online. It is a normal outcome and we would rather adjust than have you work around it.