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 want | What to set up |
|---|---|
| Members sign in with a Microsoft account and each has their own mailbox | the organisation client — that is enough |
| On top of that, shared mailboxes (info@, sales@), or mailbox access set up centrally, without their owners | the organisation registration as well |
| You do not want signing in with Microsoft accounts | people 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 client | Organisation registration | |
|---|---|---|
| What it does | members signing in with the Sign in with Microsoft button, and the Connect Outlook button at a person's own mailbox | the assistant's access to mailboxes without their owners signing in |
| Where in draften | Organisation → Sign-in and mail access → the Account sign-in and mailbox connections card | Organisation → Sign-in and mail access → the Registrations for shared mailboxes and central management card |
| Who sets it up in draften | the organisation owner | the organisation's owner or a manager |
| Permissions in Entra | delegated (Delegated) | application (Application) |
| Who signs in to the mailbox | the owner of each mailbox, once | nobody |
| Which mailboxes it reaches | only those that people connect themselves | the directory's mailboxes (can be narrowed) |
| Shared mailboxes | no — they have no sign-in of their own | yes |
| When someone leaves the company | once their account is blocked, the mailbox disconnects | nothing 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.
- 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/callbackand/mailboxes/connect/callback. Copy them from there; they must match character for character. - 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
- 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.
- Name — say
- On the Overview page, copy the Application (client) ID and the Directory (tenant) ID (the copy icon next to the value).
- 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. - 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. - 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.ReadWriteandMailboxSettings.ReadWrite, then click Add permissions at the bottom.User.Readis usually in the list from the start. Withoutoffline_accessthe connection does not last — draften would get no refresh token. - 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
- 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.
- 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.
- 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.
- Then Test the connection.
When a mailbox disconnects
- The client's secret expired — in Entra, open App registrations → the client's registration (say
draften – sign-in) → Certificates & secrets → + New client secret and copy the Value. Save it in the Account sign-in and mailbox connections card and click Reconnect Outlook on the mailboxes. - The person left or their account was blocked — Microsoft stops issuing tokens and draften disconnects the mailbox. Connect a mailbox without a sign-in of its own through the organisation registration (below).
- "The provider issued no refresh token" — the client lacks the
offline_accesspermission (step 7). - "A different account signed in than the mailbox address" — when connecting, sign in with the account of exactly that mailbox; whoever has several Microsoft accounts in the browser picks the right one.
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.
- 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
- 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.
- Name — say
- On the Overview page, copy the Application (client) ID and the Directory (tenant) ID (the copy icon next to the value).
- 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. - API permissions → + Add a permission → Microsoft Graph → Application permissions (not Delegated). Type into the search and tick
Mail.ReadWriteandMailboxSettings.ReadWrite, then click Add permissions at the bottom.MailboxSettings.ReadWriteserves only the colour of the Outlook category; without it the category is added without a colour. Optionally addUser.Read.All— with it draften checks the mailbox's aliases; without it the connection test says it cannot check them. - 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
- 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.
- 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.
- 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:
- 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). - In draften, in Organisation → Sign-in and mail access, choose New secret at the registration and enter the new value and the new date.
- 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 message | What it means | What to do |
|---|---|---|
AADSTS7000215, AADSTS7000222, invalid_client | a wrong or expired client secret | create a new secret and save it in draften |
AADSTS700016, AADSTS90002, unauthorized_client | a wrong Application ID or Directory ID | copy both IDs again from Overview |
AADSTS65001, AADSTS650057, consent_required | admin consent is missing | Grant admin consent at the app |
a token without Mail.ReadWrite | the permission is missing or not consented to | add the permission and grant consent |
invalid_grant, AADSTS50173, AADSTS700082, AADSTS70008 | the account connection expired or was revoked | Reconnect Outlook |
HTTP 403 AppOnly AccessPolicy | the mailbox is not in the access policy's group | add it to the group and wait |
| HTTP 404 | no such mailbox exists | check the address; the mailbox must have Exchange Online |
| HTTP 401 | another directory, or a missing permission | check the Directory ID and the permissions |
Other errors are covered in Troubleshooting.