Microsoft

Outlook, OneDrive and Calendar, through Microsoft Graph.

A Microsoft connection lets Mankomail act on a member's Microsoft 365 work or school account through Microsoft Graph: mirror and send their Outlook mail, and — when the member allows it — work with their OneDrive files, their Outlook calendar, and the SharePoint sites they already have access to. Each member connects their own account.

Access is split into capabilities (mailbox, files, calendar, SharePoint). Each capability is a separate consent, granted on its own and added to the previous ones: connecting a mailbox gives no access to OneDrive, and allowing OneDrive does not ask for mail access again. The setup has two halves: an administrator registers the organisation's own application in Microsoft Entra ID once ("bring your own app"), then each member connects their account.

At a glance

• Identifier: microsoft
• Family: Account
• Set up by: Each member, for themselves
• Authentication: OAuth sign-in, one capability at a time
• Credential type: msgraph_oauth

Capabilities and scopes

Each capability is granted separately, when a member first needs it. Every authorisation also asks for openid, email, offline_access.

Capability	Scopes	Nodes
mail	Mail.ReadWrite, Mail.Send
calendar	Calendars.ReadWrite	Create an Outlook event, Find an Outlook slot
files	Files.ReadWrite	Upload to OneDrive, Search OneDrive, Create a OneDrive folder, Excel
sharepoint	Sites.Read.All, Sites.ReadWrite.All	SharePoint, Excel

Before you start

• Work or school accounts only. Mankomail signs members in through Microsoft's organizations endpoint, which accepts Microsoft Entra (work or school) accounts. Personal Microsoft accounts (Outlook.com, Hotmail, Live) cannot be connected.
• An administrator of the Mankomail instance registers the application. Members never see the client secret.
• A Microsoft Entra role that can register applications in your tenant (at least Application Developer). Granting tenant-wide admin consent, which SharePoint needs, takes a role allowed to grant consent for the organisation.
• The public address of your instance. The redirect URI is derived from the PUBLIC_BASE_URL setting; it must be the address your members actually use. See environment variables.
• An encryption key (ENCRYPTION_KEY) configured on the instance. Without it, nothing can be stored and every connection fails with oauth.encryption_disabled.

Register the application (administrator)

In Mankomail, open Administration › OAuth applications and select Microsoft under Provider to configure. The page shows the Redirect URI and the Microsoft Graph permissions requested capability by capability. The redirect URI always has this shape:

<PUBLIC_BASE_URL>/api/v1/oauth/microsoft/callback

Then, in the Microsoft Entra admin center:

1. Go to Entra ID › App registrations and select New registration.
2. Give it a Name your members will recognise: they see it on the consent screen.
3. Under Supported account types, choose Multiple Entra ID tenants. Microsoft refuses the organizations endpoint used by Mankomail for an application registered as single-tenant (error AADSTS50194).
4. Select Register. On the Overview page, copy the Application (client) ID.
5. Under Authentication, add a Web platform and paste the redirect URI copied from Mankomail, character for character.
6. Under Certificates & secrets, create a New client secret. Copy its Value — not its ID: it is shown only once. Note its expiry date.

You do not need to add the mail, files or calendar permissions in the registration: Mankomail requests them when a member connects each capability. SharePoint is the exception (see the warning below).

Back in Mankomail, under Application credentials:

1. Paste the Client ID. It must be a GUID (00000000-0000-0000-0000-000000000000); the field refuses anything else.
2. Paste the Client secret (the value).
3. Click Save. The state badge switches to Application registered.

SharePoint needs admin consent

The SharePoint capability requests Sites.Read.All and Sites.ReadWrite.All. In a Microsoft 365 tenant left on its default settings, users cannot consent to these themselves: an administrator must grant consent once for the whole organisation. In Entra, open the app registration, then API permissions, add the two delegated Microsoft Graph permissions Sites.Read.All and Sites.ReadWrite.All, and select Grant admin consent. Without this step, the first member who clicks Connect SharePoint sees Microsoft's "Need admin approval" page (AADSTS65001).

Client secret expiry

Entra client secrets expire. Once the secret has expired, Microsoft refuses every token refresh (AADSTS7000222) and connections stop working. Before the expiry date, create a new secret, paste it in Mankomail together with the client ID, and save: the secret is never kept between saves and must be re-entered every time.

Connect an account (member)

1. Open Connections, click Add a connection, then Connect on the Microsoft card.
2. Microsoft asks you to pick an account. Choose your work account — this choice is always offered, so that a browser signed in to another account does not connect the wrong mailbox.
3. Accept the requested permissions. You come back to Mankomail with the message Mailbox … connected. and the mailbox starts syncing under Mailboxes (see mailboxes and the mirror).

The first connection always grants the mailbox capability. The other capabilities are added from the account's row in Connections, under Mail and cloud accounts: Connect OneDrive, Connect the calendar, Connect SharePoint. Each click opens a consent for that access only; once granted, the capability appears as a badge on the account. Microsoft's consent is cumulative: granting a new capability never removes the previous ones.

• An authorisation must be completed within ten minutes of clicking; after that, or if the link is reused, it is refused (oauth.invalid_state).
• Authorising the same Microsoft address again updates the existing connection instead of creating a second one.
• Microsoft has no spreadsheet capability of its own: Excel workbooks are reached through OneDrive or SharePoint.

What each permission allows

All permissions are delegated: Mankomail acts as the member, with the member's own rights, never with application-wide access.

• Mailbox — Mail.ReadWrite to read the mirror and file messages (flags, moves, drafts), Mail.Send to send.
• Files — Files.ReadWrite: the member's own OneDrive, in read and write. Not colleagues' OneDrives (Files.ReadWrite.All is never requested) and not SharePoint sites.
• Calendar — Calendars.ReadWrite: create events and look up free slots in the member's calendar.
• SharePoint — Sites.Read.All and Sites.ReadWrite.All: read and write documents and list items on the sites the member already has access to. Mankomail creates items, never lists or columns, so it never asks for Sites.Manage.All or Sites.FullControl.All.

openid, email and offline_access are requested with every capability: the address identifies the connection, and offline_access is what gives a refresh token — without it, access would last one hour.

Calendar invitations

Microsoft Graph notifies attendees as soon as an event is created with them. When the Send invitations option of Create an Outlook event is off (the default), Mankomail does not send the attendees as such: it lists them in the event body, and nobody receives an email.

Disconnect, revoke, reconnect

• Removing the mailbox. A Microsoft account is not deleted from Connections: you disconnect its mailbox from Mailboxes. Disconnecting stops the sync, keeps the history readable and removes the mailbox capability. If the account still carries other capabilities (OneDrive, calendar, SharePoint), the connection stays so that those nodes keep working; otherwise it is erased.
• Revoking at Microsoft. Disconnecting in Mankomail does not withdraw the consent recorded by Microsoft. Microsoft revokes a whole grant, not a single capability.
• When access is lost. If Microsoft refuses to refresh the token, Mankomail marks the connection as revoked and the mailbox shows an error. Nodes that need the account then fail with credential.capability_missing or microsoft.access_denied.
• Reconnecting. Connect the same account again — the mailbox first (Reconnect this mailbox under Mailboxes, or the Microsoft card in Connections), then each capability you need. The existing connection and mailbox are reused, history included.

Common errors

Errors of the connection flow are shown as a banner on Connections when you come back from Microsoft. Errors raised by nodes appear in the step's details of the run.

Message or code	Cause	What to do
oauth.app_not_configured — No application is configured for this provider.	No Microsoft application is registered, or it is disabled.	An administrator registers it under Administration › OAuth applications.
oauth.invalid_client_id — The client ID does not have the shape this provider expects.	The pasted value is not a GUID (often the secret ID, or extra text).	Paste the Application (client) ID alone.
oauth.encryption_disabled	ENCRYPTION_KEY is not configured.	Configure the encryption key and restart the instance.
Microsoft page AADSTS50011	The redirect URI registered in Entra differs from the one Mankomail sends.	Copy the Redirect URI again into the Web platform of the registration.
Microsoft page AADSTS50194	The application is registered as single-tenant.	Set Supported account types to multiple tenants.
Microsoft page AADSTS65001 / "Need admin approval"	The tenant does not let users consent to this permission (typically SharePoint).	An administrator grants admin consent in API permissions.
oauth.access_denied — You declined the authorisation at the provider.	The member cancelled or refused the consent.	Start the connection again and accept.
oauth.capability_not_granted — You did not grant every access requested.	The returned token lacks the permissions of the requested capability.	Start the connection again and accept every permission.
oauth.invalid_state — The authorisation link expired or was already used.	More than ten minutes passed, the link was used twice, or another member is signed in to Mankomail in the same browser.	Start the connection again.
oauth.exchange_failed	Microsoft refused the code exchange (wrong or expired client secret, for example).	Try again; if it persists, check the client ID and secret saved by the administrator.
credential.capability_missing — This action needs an extra access.	The step needs a capability the member never granted, or that was revoked.	Click the matching Connect … button in Connections.
microsoft.access_denied	The account is connected but the permission is missing or was revoked.	Reconnect the account in Connections.
microsoft.auth_failed	Microsoft no longer accepts the token.	Reconnect the account in Connections.
microsoft.not_found	The folder, file, site or calendar no longer exists.	Check the node's target.
microsoft.rejected	Graph refused the request itself (format, unindexed SharePoint column…).	Check the node's parameters; the step is not retried.
microsoft.conflict	The item changed since it was read.	Read it again and decide; the step is not retried.
microsoft.locked	The file is open or checked out by someone else.	Nothing: the step is retried until the file is released.
microsoft.storage_full	The OneDrive or SharePoint site is full.	Free space or raise the quota; the step is not retried.
microsoft.unavailable	Throttling, bandwidth limit, outage or network error.	Nothing: the step is retried automatically.

For how failed steps are retried or replayed, see error handling.

Nodes that use this connection

• Upload to OneDrive — onedrive.upload (capability files)
• Search OneDrive — onedrive.search (capability files)
• Create a OneDrive folder — onedrive.create_folder (capability files)
• Create an Outlook event — outlook_calendar.create_event (capability calendar)
• Find an Outlook slot — outlook_calendar.find_free (capability calendar)
• SharePoint — sharepoint.api (capability sharepoint)
• Excel — excel.api (capability sharepoint)
• Excel — excel.api (capability files)