Migrating from EWS to Exchange Online Admin API

Microsoft has announced the formal retirement of Exchange Web Services (EWS) for Exchange Online. To ensure our customers experience zero disruption in service—particularly for advanced features like Distribution List (DL) expansion—ContactMonkey is proactively migrating to the new Exchange Online Admin API.

⚠️ Important: The Microsoft Graph integration is also migrating to a new permission. If your organization uses this expansion method, please follow the steps here to complete that update separately. 

What is happening with EWS?

Microsoft is phasing out legacy EWS in favour of more secure, modern REST-based APIs.

• When: Starting October 1, 2026, Microsoft will begin blocking EWS requests in Exchange Online. See Microsoft Blog post here: https://techcommunity.microsoft.com/blog/exchange/exchange-online-ews-your-time-is-almost-up/4492361
• Impact: Any integration relying solely on legacy EWS will eventually stop functioning for tasks like resolving recipient counts or expanding dynamic groups.

What is the Exchange Online Admin API, and how does it replace EWS?

The Exchange Online Admin API is a modern interface designed to handle specific administrative tasks that were previously only possible through EWS or PowerShell.

How ContactMonkey uses it:

We utilize this API to maintain high-performance directory features, including:

• Distribution Group Expansion: Accurately expanding and counting memberships for both standard and dynamic distribution groups.
• Mailbox & Group Insights: Viewing mailbox properties and group memberships to ensure your emails reach the right recipients.
• Read-Only Access: This API allows us to perform these checks with the minimum permissions required, adhering to security best practices.

Completing the steps below ensures you are proactively migrating to a modern interface for high-performance features like Distribution Group Expansion and Mailbox Insights.

Actions Required to Prepare Your Tenant:

1. Assign the RBAC Role (IT Admin)

To ensure the API can read the necessary group data, the service account requires the following Role-Based Access Control (RBAC) role assigned within the Exchange Admin Center:

• Role: View-Only Organization Management

Before granting API access, you must ensure the service account has read-only access to Exchange data.  A ContactMonkey Admin or Owner can go to Settings → Integrations to see which account is being used for other Utility integrations.

1. Open the Exchange Admin Center
2. Navigate to Roles → Admin roles
3. Search for and select View-Only Organization Management
4. Click the Assigned tab, search for and add your Service Account

Learn more about Role-based Permissions on Exchange Online.

Note: This is a read-only role. It allows ContactMonkey to see mailbox and group memberships but does not grant permission to modify settings, delete data, or read email content.

2. Update API Permission (IT Admin)

Your IT Administrator must add the ContactMonkey - Exchange Online Admin API Enterprise App in the Microsoft Entra ID (Azure AD) portal. Using the Consent Links listed below, the enterprise app and the following scopes will be added automatically:

To add the enterprise app and subsequently enable the Exchange.ManageV2 permission, please use the Admin Consent URL for the region your ContactMonkey data is stored in:

1. US Region
2. CA Region
3. EU Region
4. AU Region

You will be redirected to a login screen—you are not required to enter your credentials if you do not have a ContactMonkey account.

3. Utility Account Connection (ContactMonkey Admin)

1. Click your name at the top right of the ContactMonkey dashboard
2. Click Settings
3. Click Integrations
4. Sign in to the Exchange Admin Utility Account tile using the service account created by your IT team (recommended) or your own account

4. Run a Test Count

1. Click Show Details in the Exchange Admin Utility Account tile
2. In the Distribution List field, enter one or more distribution list email addresses (comma-separated)
3. Click Test Count
4. Results will be emailed to you

4.1 Interpret Results

✅ Success: The recipient count matches your expected number

• Your expansion is configured correctly
• All users in your organization can now send tracked emails to distribution lists

❌ Inaccurate Count: The number doesn't match expectations

• Click here for diagnostic steps
• You may need to modify the distribution list type
• Consider alternative approaches like CSV upload or List Management

⚠️ Account Shows "Inactive":

• This typically means OAuth tokens have expired
• Running a test count should reactivate the account
• If it remains inactive, sign out and sign back in
• Click here for more details

5. Remove EWS Utility Account from ContactMonkey (ContactMonkey Admin)

1. Click your name at the top right of the ContactMonkey dashboard
2. Click Settings
3. Click Integrations
4. Sign out of the EWS Utility Account tile so it is disconnected

6. Remove EWS Enterprise App (IT Admin)

1. Open the Entra Admin Center
2. Click Enterprise Apps
3. Open ContactMonkey EWS-Utility
4. Click Properties
5. Click Delete

See Also

• Setting Up Distribution List Expansion
• Distribution List Types and Expansion Support