Troubleshooting
This section describes common Mailbridge issues and the checks required to resolve them.
setFlag Errors
If a setFlag call fails, the application is usually missing the Microsoft Graph permission Mail.ReadWrite.
The Mailbridge does not only read emails. It also updates mailbox content such as message flags. Because of that, read-only permissions are not sufficient when the Mailbridge processes messages through Microsoft Graph.
Ensure that the Entra app registration used by the Mailbridge has permission to modify emails in the target mailbox. Without Mail.ReadWrite, message processing can fail even if mailbox access itself appears to work.
For a detailed explanation of the required Graph permissions, refer to the Graph Mailserver documentation.
Microsoft Graph Returns 403
If Microsoft Graph returns HTTP status 403 for a mailbox, first verify that
the Entra app registration has the required Graph permissions. For Mailbridge
processing, Mail.ReadWrite must be granted because the Mailbridge updates
message flags.
If the required permissions are granted and the application uses application
permissions, verify the mailbox access restriction for the target mailbox. The
central Graph Mailserver documentation describes the required Exchange Online
setup, the policy test, and the expected AccessCheckResult values.
For the complete mailbox restriction checks, refer to the Graph Mailserver documentation.
Shared Mailbox Access Problems
If the Mailbridge cannot read a shared mailbox, first verify the shared mailbox configuration before changing API permissions.
Configuration Checklist
The following settings must be configured correctly for shared mailbox access:
| Setting | Required value |
|---|---|
userserverEnabled | The option must be enabled for the technical user. |
mailServerTUser | This value must contain the user name of the transport account used for sending and authentication, not the shared mailbox address. |
mailserverUser | This value must use the format {login}\{email-address-of-the-shared-inbox}. |
isPublicMailbox | This option must be enabled in the Mailserver IMAP alias. |
| Mail client mailbox assignment | Use the email address of the shared mailbox. |
If you are using a Graph-based mail server, the application also requires the delegated permission Mail.ReadWrite.Shared for shared mailboxes. This permission is required because the Mailbridge updates mailbox content in addition to reading messages.
If the application only has Mail.ReadWrite, access to the main mailbox can work while access to the shared mailbox still fails.
For non-Graph mail server configurations, Mail.ReadWrite.Shared is not relevant.
For the complete shared mailbox setup, refer to the Mailbridge configuration guide. Microsoft also documents the permission details in the Graph permissions reference.