Skip to main content

Migration from IMAP to Graph Mailserver

The phased enforcement of Multi-Factor Authentication (MFA) by Microsoft, starting September 1, 2025, necessitates a transition in how the Mailbridge connects to mail services. To ensure continued operation and compliance with these security requirements, the Mailbridge must be migrated from the traditional IMAP protocol with OAuth2 to the Microsoft Graph API.

info

For comprehensive details regarding the mandatory MFA enforcement, please refer to the official Microsoft documentation on Microsoft Entra ID Mandatory Multi-Factor Authentication.

Create a New Mailserver Graph Alias​

The first step in the migration process involves defining a new alias specifically for the Microsoft Graph API. This alias will replace the existing IMAP connection.

  1. Locate the alias node within the project tree of the ADITO Designer.
  2. Right-click the node and select New from the context menu to initialize a new alias.
  3. In the configuration dialog, choose Mailserver Graph as the alias type and provide a descriptive name.
  4. Deploy the newly created alias to the target system to make it available for use.

Update the Global Mailbridge Configuration​

Once the new Graph alias is deployed, the global preferences must be updated to reference this server. This change ensures that the system-wide Mailbridge service utilizes the Graph API.

  1. Navigate to Preferences > _PREFERENCES_PROJECT > Modules > Email > mailBridgeMailserver.
  2. Open the configuration dialog by clicking the ellipsis (three dots) button next to the property.
  3. Within the list of active mail bridges, locate the entry for each relevant user or service and update the server selection to the newly created Graph alias.
note

This step updates the default server association at the project level, but individual user settings must also be verified as described in the next section.

Configure Individual User Settings​

The Mailbridge identifies the specific mailbox and server configuration through the user's extended properties. Each user account associated with the Mailbridge must be updated to use the new alias.

  1. Open the System module and navigate to the Users section.
  2. Select the specific Mailbridge user account that requires migration.
  3. Switch to the Extended tab within the user details view.
  4. Locate the mailserverAlias property and select the new Graph alias from the dropdown menu.

Finalize and Verify the Migration​

To complete the migration and ensure that the Mailbridge functions correctly with the Graph API, certain administrative actions and permission checks are required.

Administrative Actions​

After updating the configurations, the changes must be applied to the running environment. This is achieved by restarting all web pods associated with the application. This restart ensures that the new preference values and alias definitions are correctly loaded into the runtime environment.

Permission Requirements​

The Microsoft Graph API requires specific permissions within the Entra ID (formerly Azure AD) environment to access and manage emails. The technical user configured in the mailserverUser property under the Extended tab of the user settings must have the Mail.ReadWrite permission granted in the Entra app registration.

warning

If the Mail.ReadWrite permission is missing, the Mailbridge will be unable to process or flag emails, leading to potential synchronization issues.

For further technical details on configuring the Graph API and its required permissions, please consult the Graph Mailserver documentation.