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.
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 |
| Mail.Send |
Send emails (for the tasks Forward, Reply, Send read receipt) |
| 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.
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 ¶
A shared mailbox is a Microsoft 365 mailbox used by several users - typically info@firma.de or support@firma.de. No one signs in directly to the shared mailbox; instead, administrators grant certain employees the permission to open the mailbox.
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 shared mailbox (e.g.
info@firma.de)
- Click Sign in with Microsoft - sign in with your personal account
The program will then authenticate with your token but access the shared mailbox (impersonation). Prerequisite: your account has the permission in Azure AD to read and write the shared mailbox.
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