50.2 Set Up Microsoft 365 (Graph)
50.2.1 Overview ¶
For mailboxes operated with Microsoft 365 (formerly Office 365, Exchange Online), the program uses the Microsoft Graph API instead of classic IMAP. This has several advantages: no app passwords needed, OAuth sign-in with two-factor authentication, modern permission management via Azure AD, and full access to Microsoft 365-specific features such as categories, flags, and shared mailboxes.
50.2.2 Required Inputs ¶
In the account editor (account type: Microsoft 365) you configure:
| Field |
Description |
| Display name |
Freely chosen name |
| Email address |
The Microsoft 365 address to be monitored later |
| Mailbox address (optional) |
Address of a shared mailbox if a jointly used mailbox is used instead of the personal mailbox (see chapter 50.2.6) |
Then click Sign in with Microsoft - the OAuth flow starts.
50.2.3 OAuth Sign-In ¶
When you click Sign in with Microsoft, a browser window opens with the Microsoft sign-in form. There you:
- Enter credentials (email address + password + two-factor code if applicable)
- Confirm the permission request - on the first sign-in, Microsoft asks whether the app may access the mailbox (see chapter 50.2.4)
- After a successful sign-in, the browser closes automatically and the OAuth status in the account editor changes to “Signed in”
The program does not store a password - instead, a refresh token is saved locally; with it, the program later obtains new access tokens on its own. The token store is located in the AppData directory of the Windows user and is encrypted.
Windows sign-in broker (WAM), as of version 4.2.0: If your organization enforces security policies with token protection (Conditional Access), browser sign-in fails with the message AADSTS53003. In that case, enable the option Use Windows sign-in broker (WAM) in the account editor - sign-in then runs via the sign-in service built into Windows, which issues device-bound sign-ins and satisfies these policies. After switching, a one-time new sign-in is required. When running as a Windows service, the sign-in broker is not available; if it is not available on the system, the program automatically falls back to the browser.
50.2.4 Permissions ¶
On the first sign-in, the program requests the following permissions:
| Scope |
Purpose |
| Mail.ReadWrite |
Read, move, copy, delete, flag emails, set categories on your own mailbox |
| Mail.ReadWrite.Shared |
Same operations on a shared mailbox or a user mailbox with FullAccess delegation |
| Mail.Send |
Send emails from your own mailbox (for Forward, Reply, Send read receipt) |
| Mail.Send.Shared |
Send emails as or on behalf of a shared mailbox or delegated user mailbox |
| User.Read |
Read display name and email address of the signed-in user |
| MailboxSettings.Read |
Read master categories of the mailbox (for auto-completion when setting categories) |
In companies with centrally administered Azure AD tenants, these permissions may need to be approved beforehand by an administrator consent - when in doubt, ask the IT department.
Approval required (admin consent): If Microsoft shows the message “Approval required” during sign-in, your organization does not allow users to consent to applications themselves. A separate app registration in Microsoft Entra ID is not required; an administrator grants consent once as follows:
- In the account editor, click Sign in with Microsoft… again and sign in at the Microsoft sign-in page with an administrator account of the organization.
- In the consent dialog, select the checkbox Consent on behalf of your organization and confirm.
- Afterwards, click Remove credentials in the account editor and repeat the sign-in with the actual account - it now completes without an approval prompt.
After consent has been granted, the application appears in the Entra admin center under “Enterprise applications”, where it can be reviewed or revoked at any time. All permissions are delegated, so the program does not receive any tenant-wide application access.
50.2.5 Token Cache and Refresh ¶
The token cache is located at:
%LOCALAPPDATA%\AutomaticEmailProcessor\GraphTokenCache\
It is managed by the program - no manual intervention needed. When the token expires, an automatic refresh happens in the background. Only if the refresh token itself becomes invalid (e.g. password changed, 90 days of inactivity, account lockout) does the account editor again show “Sign-in required” and you must click Sign in with Microsoft again.
50.2.6 Shared Mailbox and Delegated User Mailbox ¶
Both a shared mailbox (a Microsoft 365 mailbox without its own license, used by several users - typically info@firma.de or support@firma.de) and a regular user mailbox with FullAccess delegation can be monitored. Conversion to a shared mailbox is not required.
In the program you configure this as follows:
- Email address: Your personal Microsoft 365 address (with which you sign in)
- Mailbox address: Address of the target mailbox (e.g.
info@firma.de)
- Click Sign in with Microsoft - sign in with your personal account
The program then authenticates with your token but reads from and sends through the target mailbox (Microsoft Graph impersonation). Prerequisites:
- Your account has FullAccess delegation on the target mailbox (Microsoft 365 Admin Center → mailbox → Delegation → “Read and manage”).
- For the Send path: your account additionally has “Send as” or “Send on behalf of” permission on the target mailbox.
- The Azure AD app registration grants the scopes
Mail.ReadWrite.Shared and Mail.Send.Shared (admin consent for the tenant).
If an existing account configured before May 2026 shows 403 ErrorAccessDenied after the update, click Remove credentials in the account editor and sign in again - the renewed token then contains the new shared scopes.
50.2.7 Remove Credentials ¶
In the account editor there is a Remove credentials button. It deletes the refresh token from the cache. The account remains set up in the program, but on the next connection attempt a fresh sign-in is required.
Useful when token problems are suspected or when switching the signed-in Microsoft account.
50.2.8 Use Case ¶
Central Service Mailbox (Shared Mailbox)
Display name: “Incoming invoices”. Email address: max.mustermann@firma.de (sign-in account). Mailbox address: rechnungen@firma.de (monitored account). Sign in with max.mustermann@firma.de - access then takes place on the shared mailbox.
50.2.9 Tips ¶
- For centrally managed Azure AD tenants, administrator consent may be necessary. If sign-in fails with “Permission denied”, contact IT
- In service mode, the sign-in uses the token cache of the service user - ideally test the OAuth sign-in once interactively under the later service account