For administrators
← All topics

Microsoft 365: connecting mailboxes

Connecting with the mailbox account (organisation client), and a registration on top for shared mailboxes — and exactly what to set up in Microsoft Entra, step by step.

For the assistant to read mail in Microsoft 365 and write drafts there, it needs access through Microsoft Graph. For that, the organisation registers an app in its own Microsoft Entra ID; draften has no shared app you would simply consent to. This holds for our service and for an installation on your own server alike.

Everything here applies only to Microsoft 365 work and school accounts. Personal outlook.com, hotmail.com and live.com accounts cannot be connected at all — see Supported providers and their limits.

What you want and what to set up

What you wantWhat to set up
Members sign in with a Microsoft account and each has their own mailboxthe organisation client — that is enough
On top of that, shared mailboxes (info@, sales@), or mailbox access set up centrally, without their ownersthe organisation registration as well
You do not want signing in with Microsoft accountspeople sign in with the password from their invitation; the organisation registration (or IMAP) connects the mail

Two separate apps

The organisation client and the organisation registration are two separate apps in Entra. Each does something different, and neither can stand in for the other:

Organisation clientOrganisation registration
What it doesmembers signing in with the Sign in with Microsoft button, and the Connect Outlook button at a person's own mailboxthe assistant's access to mailboxes without their owners signing in
Where in draftenOrganisation → Sign-in and mail access → the Account sign-in and mailbox connections cardOrganisation → Sign-in and mail access → the Registrations for shared mailboxes and central management card
Who sets it up in draftenthe organisation ownerthe organisation's owner or a manager
Permissions in Entradelegated (Delegated)application (Application)
Who signs in to the mailboxthe owner of each mailbox, oncenobody
Which mailboxes it reachesonly those that people connect themselvesthe directory's mailboxes (can be narrowed)
Shared mailboxesno — they have no sign-in of their ownyes
When someone leaves the companyonce their account is blocked, the mailbox disconnectsnothing changes

They are two apps on purpose. Consent to the client grants rights only to the mailboxes that people connect themselves — never to the mail of the whole organisation. The organisation registration, on the other hand, reaches every mailbox, and that is why only draften gets it, for mailbox access, not for signing in. Do not merge them into one.

Each mailbox uses one of the two kinds of access. You can have both apps at once: say, the client for signing in and people's own mailboxes, and the registration for the shared info@ mailbox.

Never give either app the Mail.Send permission. draften sends nothing, and without that permission it cannot — which is the point.

Organisation client: signing in and Connect Outlook

The client has delegated permissions: the app may do only what the signed-in person may, and only in their own mailbox. You create it once; the mailbox owners then connect by themselves and no longer need the Entra administrator.

In Microsoft Entra

You work in the Microsoft Entra admin center, https://entra.microsoft.com, signed in with an administrator account of your Microsoft 365 directory.

  1. In draften, first open Organisation → Sign-in and mail access, the Account sign-in and mailbox connections card. It shows two redirect URIs made exactly for your draften address — ending in /auth/callback and /mailboxes/connect/callback. Copy them from there; they must match character for character.
  2. Open the list of app registrations: in the menu on the left, Entra ID → App registrations (in the older version of the menu, Identity → Applications → App registrations). Directly: https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
  3. At the top, click + New registration and fill in:
    • Name — say draften – sign-in,
    • Supported account types — Accounts in this organizational directory only (… only - Single tenant),
    • Redirect URI — in the Select a platform drop-down, choose Web and paste the first address from the card next to it (it ends in /auth/callback).

    Click Register. The new app's page opens.

  4. On the Overview page, copy the Application (client) ID and the Directory (tenant) ID (the copy icon next to the value).
  5. In the app's menu on the left, open Authentication. At the Web platform, in the Redirect URIs part, click Add URI, paste the second address from the card (it ends in /mailboxes/connect/callback) and click Save at the bottom.
  6. Certificates & secrets → the Client secrets tab → + New client secret. Description say draften; under Expires, choose the validity (24 months at most) and click Add. In the table, copy the value from the Value column straight away — it is shown only now; draften does not need the Secret ID. Note down the date in the Expires column too.
  7. API permissions → + Add a permission → Microsoft Graph → Delegated permissions. Type into the search one by one and tick openid, profile, email, offline_access, User.Read, Mail.ReadWrite and MailboxSettings.ReadWrite, then click Add permissions at the bottom. User.Read is usually in the list from the start. Without offline_access the connection does not last — draften would get no refresh token.
  8. On the same page, click Grant admin consent for … and confirm with Yes. Every row must have a green tick in the Status column. If your organisation does not let users consent to apps, connecting would otherwise end with a message that the consent was refused.

In draften

  1. The organisation owner opens Organisation → Sign-in and mail access and, in the Account sign-in and mailbox connections card, fills in the Application (client) ID (step 4) and the Client secret (step 6) under Entra registration for Sign in with Microsoft and Connect Outlook, then clicks Save.
  2. They switch on signing in with a Microsoft account on the same page, in the How members sign in card: they put the Directory (tenant) ID into Microsoft directory (Entra) ID. Once the organisation has both the client and the directory ID, members sign in with their Microsoft accounts and their passwords stop working — see How members sign in.
  3. The mailbox owner opens the mailbox's page and, in the Mail access card, in the Connect with the mailbox account: row, clicks Connect Outlook. They sign in with that mailbox's account — draften refuses any other — and allow the access. Only the mailbox owner sees the button, and only when the organisation has the client; without it, the card says instead of the button that connecting with an account will work once the organisation owner adds the client.
  4. Then Test the connection.

When a mailbox disconnects

Organisation registration: access without signing in

The registration has application permissions: the assistant gets into the mailbox without anyone signing in. It suits shared mailboxes and organisations that want to manage mailbox access centrally. It has nothing to do with signing in to draften.

You need an account with the Global Administrator or Privileged Role Administrator role — only such an account can consent to Microsoft Graph application permissions. The registration itself can also be created by an Application Administrator.

In Microsoft Entra

You work in the Microsoft Entra admin center, https://entra.microsoft.com.

  1. Open the list of app registrations: in the menu on the left, Entra ID → App registrations (in the older version of the menu, Identity → Applications → App registrations). Directly: https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
  2. At the top, click + New registration and fill in:
    • Name — say draften – mail,
    • Supported account types — Accounts in this organizational directory only (… only - Single tenant),
    • Redirect URI — leave it empty.

    Click Register. The new app's page opens.

  3. On the Overview page, copy the Application (client) ID and the Directory (tenant) ID (the copy icon next to the value).
  4. In the app's menu on the left, Certificates & secrets → the Client secrets tab → + New client secret. Description say draften; under Expires, choose the validity (24 months at most) and click Add. In the table, copy the value from the Value column straight away — it is shown only now; draften does not need the Secret ID. Note down the date in the Expires column too.
  5. API permissions → + Add a permission → Microsoft Graph → Application permissions (not Delegated). Type into the search and tick Mail.ReadWrite and MailboxSettings.ReadWrite, then click Add permissions at the bottom. MailboxSettings.ReadWrite serves only the colour of the Outlook category; without it the category is added without a colour. Optionally add User.Read.All — with it draften checks the mailbox's aliases; without it the connection test says it cannot check them.
  6. On the same page, click Grant admin consent for … and confirm with Yes. Every row must have a green tick in the Status column.

In draften

  1. Open Organisation → Sign-in and mail access, the Registrations for shared mailboxes and central management card. Registrations are managed by the organisation's owner or managers.
  2. System: Microsoft 365 (Entra). Fill in Name, Directory (tenant) ID, Application (client) ID, Client secret (the value from step 4, not its ID) and Secret expires. Click Add registration. The secret is stored encrypted and never shown again.
  3. The registration connects nothing by itself. On each mailbox's page, in the Mail access card, choose this registration under Organisation registration, click Apply and then Test the connection. Only someone who owns the mailbox and is also the owner or a manager of the organisation sees the choice (the organisation's owner owns every mailbox). The whole procedure with screenshots is in the guide Adding and connecting a mailbox.

With Mailbox automatically on (How members sign in), a new mailbox is bound to the registration by itself when exactly one is active for Microsoft 365.

Narrowing to selected mailboxes (optional)

An application permission reaches every mailbox of the directory; draften is the guard (a member cannot add a mailbox, the assistant neither sends nor deletes anything). Whoever wants a technical fence as well narrows the app to a security group with an ApplicationAccessPolicy in Exchange Online. You need PowerShell and the Exchange Administrator (or Global Administrator) role.

Step 1 — the Exchange Online module. Install it once: run PowerShell as the computer's administrator and enter:

Install-Module ExchangeOnlineManagement

Step 2 — the group and the policy. Sign in to Exchange Online, create a security group with the mailboxes draften may access, and a policy that restricts the app to that group only. Replace <Application (client) ID> with the registration's ID from step 3 above, and the addresses with your own mailboxes:

Connect-ExchangeOnline -UserPrincipalName admin@<tenant>.onmicrosoft.com
New-DistributionGroup -Name "draften - allowed mailboxes" -Alias draften-mailboxes -Type Security -Members mailbox@firma.cz
New-ApplicationAccessPolicy -AppId <Application (client) ID> -PolicyScopeGroupId draften-mailboxes@firma.cz -AccessRight RestrictAccess -Description "draften: allowed mailboxes only"

Step 3 — verification. For a mailbox in the group, the command should print AccessCheckResult : Granted; for a mailbox outside the group, Denied:

Test-ApplicationAccessPolicy -Identity mailbox@firma.cz -AppId <Application (client) ID>

You then add a further mailbox to the group in the Exchange admin center (https://admin.exchange.microsoft.com → Recipients → Groups), or with the command Add-DistributionGroupMember -Identity draften-mailboxes@firma.cz -Member another@firma.cz. A mailbox outside the group fails the connection test with error 403 (AppOnly AccessPolicy). The policy usually takes effect within an hour; we have seen four hours too. As a newer alternative, Microsoft offers RBAC for Applications in Exchange Online; we do not describe it yet.

Replacing the secret

The secret has a limited validity, and draften sends no warning before it ends — the date in the card turns yellow 30 days before expiry and red after it. Put a reminder in your calendar. Before it expires:

  1. In Entra, open App registrations → your registration (say draften – mail) → Certificates & secrets → + New client secret and copy the new Value (as in step 4 above).
  2. In draften, in Organisation → Sign-in and mail access, choose New secret at the registration and enter the new value and the new date.
  3. Delete the old secret in Entra with the bin icon on its row.

If the secret expires first, the mailboxes disconnect (invalid_client) and the assistants skip them. After replacing the secret, run Test the connection on the mailboxes — a successful test switches the mailbox back on.

Connection test errors

The test checks three steps: Access, Token and permission and Reading the Inbox. Each gets a tick, or a cross with the reason:

In the messageWhat it meansWhat to do
AADSTS7000215, AADSTS7000222, invalid_clienta wrong or expired client secretcreate a new secret and save it in draften
AADSTS700016, AADSTS90002, unauthorized_clienta wrong Application ID or Directory IDcopy both IDs again from Overview
AADSTS65001, AADSTS650057, consent_requiredadmin consent is missingGrant admin consent at the app
a token without Mail.ReadWritethe permission is missing or not consented toadd the permission and grant consent
invalid_grant, AADSTS50173, AADSTS700082, AADSTS70008the account connection expired or was revokedReconnect Outlook
HTTP 403 AppOnly AccessPolicythe mailbox is not in the access policy's groupadd it to the group and wait
HTTP 404no such mailbox existscheck the address; the mailbox must have Exchange Online
HTTP 401another directory, or a missing permissioncheck the Directory ID and the permissions

Other errors are covered in Troubleshooting.

Plain text version