Exchange contacts synchronization with Graph API

Microsoft now manages contacts in Exchange differently. Previously, administrators managed them using EWS and PowerShell. Today, in the cloud, Microsoft relies on Microsoft Graph. EWS remains relevant only for on-premises Exchange servers. For modern automation and synchronization, like exchange contacts sychronisation, Graph is the new standard.

Architecture and interfaces

Exchange stores contacts in a user’s mailbox. These personal contacts are not the same as entries in the Global Address List (GAL).

• Administrators manage GAL contacts centrally in Entra ID.
• Personal contacts, by contrast, reside in the same container as emails, calendar items, or tasks.

This separation also remains in the cloud.

Previously, personal contacts were accessed via EWS. EWS is a SOAP API and could do everything: read, create, modify, and delete contacts. Administrators often used it for scripts, migrations, or CRM integrations. With Microsoft 365, the focus has shifted to REST endpoints, which Microsoft consolidates in Graph.

Microsoft Graph is more than a successor to EWS. It is a unified platform for Microsoft 365, Entra ID, Teams, SharePoint, Intune, and Windows services. Graph provides access to data using a consistent authentication model. The API is based on open standards: OAuth 2.0 for authentication, OData for filtering, and JSON for data exchange. As a result, it is not limited to Exchange.

Graph acts as a gateway to all cloud data. Access is provided via REST calls or through the Microsoft Graph PowerShell SDK. This allows administrators to perform the same operations in PowerShell that applications do when using Graph.

Exchange on-premises and Entra Connect

Managing contacts on on-premises Exchange servers still relies on EWS or PowerShell. The connection to the cloud is established through Microsoft Entra Connect (formerly Azure AD Connect). This tool synchronizes users, groups, and contacts from on-premises Active Directory to the cloud, enabling Exchange Online and Teams to use the data in the Global Address List.

Important: Mailbox contents are not synchronized automatically. Personal contacts that a user creates in Outlook or OWA remain local. If these contacts need to be brought into the cloud, a custom interface is required—for example, a script that reads via EWS and writes via Graph.

For hybrid organizations, this means: as long as mailboxes are still on-premises, EWS is indispensable. Only when all users have been migrated to Exchange Online can Microsoft Graph be used exclusively.

Exchange Online and Unified Contacts

In Exchange Online, Microsoft uses a unified contact model. Outlook, Teams, and other services share personal contacts. When you create a contact in Outlook, Teams automatically displays it, allowing you to use it for calls or chats. This approach, called Unified Contacts, lets both applications access the same mailbox object.

This unification affects not only how contacts are displayed, but also how they are stored. Changes in Outlook or Teams are synchronized via Microsoft Graph, preventing duplicate data. This model paves the way for the transition from EWS to Graph.

Access via Graph always requires a valid OAuth token. Error messages such as “Access token is empty” indicate that the token is missing, expired, or that the HTTP header “Authorization” is absent. Graph only accepts requests that include:

Ensure the token is not empty or expired and that Microsoft issues it for the resource “https://graph.microsoft.com”. If you call the API in a browser without authenticating, the service always returns this error.

Getting started with Graph

Graph Explorer

In practice, it is recommended to start with Graph Explorer, as authentication is handled automatically.

• Sign-in is automatic using the Microsoft account

• Permissions such as Contacts.Read or Contacts.ReadWrite can be granted directly

• API calls can be tested immediately, for example:

For automated scripts, the Microsoft Graph PowerShell SDK is a good choice. The following commands establish a delegated connection that retrieves the signed-in user’s contacts using Get-MgUserContact -UserId me.

App-only access (without a user)

When you need application tokens without user context, use app-only authentication:

• Register an app in Entra ID
• Request an access token via Entra ID using a client ID, secret, or certificate
• You cannot use delegated endpoints such as “/me” in this mode; instead, specify the user explicitly:

• The token must include the Application Permission "Contacts.ReadWrite", which must be approved in the tenant beforehand.

Access tokens are valid for one hour by default. Longer-running scripts require token renewal. Scripts should also handle error codes such as 401 (Unauthorized) or 429 (Rate Limit).

Practical examples

The Graph PowerShell SDK provides cmdlets such as Get-MgUserContact and New-MgUserContact to automate the creation, modification, or deletion of contacts.

Install-Module Microsoft.Graph.PersonalContacts -Scope CurrentUser -AllowClobber
Import-Module Microsoft.Graph.PersonalContacts -Force

Typical use cases include:

• Importing centralized organizational contacts into all user mailboxes
• Reading contacts from Microsoft Lists or SharePoint
• Automatically populating new target mailboxes with predefined contacts

A proven approach is to automatically provide a predefined contact list when creating new mailboxes, containing key contacts from HR, IT, or support. The associated script checks whether a contact already exists before inserting it, preventing duplicates. Authentication is handled via an application registered in Entra ID that uses a certificate and has the permissions "Users.Read.All" and "Contacts.ReadWrite". If contact data comes from a Microsoft List, "Sites.Manage.All" or "Sites.Read.All" is additionally required to read the data source.

The article Managing groups in Microsoft 365 with Graph PowerShell provides further practical examples for managing Microsoft 365 groups with Graph PowerShell.

EWS decommissioning and functional gaps in Graph

Microsoft plans to fully block Exchange Web Services (EWS) in Exchange Online starting October 1, 2026. Microsoft will continue to provide EWS access for on-premises Exchange servers, but it will no longer develop it further.

Graph still has some functional gaps that Microsoft plans to close before the shutdown date:

• Access to archive mailboxes, which are currently only accessible via EWS
• Folder Associated Information and User Configuration, i.e., mailbox metadata
• Advanced management features for Exchange Online
• Programmatic access to public folders, which will be restricted to Outlook clients in the future

After October 2026, Microsoft will only allow reading and writing public folders for supported Outlook clients and for large-scale import or export scenarios. APIs for creating or modifying these folders will be removed entirely.

Microsoft recommends that developers:

• review existing integrations early,
• identify affected applications,
• gradually replace all EWS calls with Graph endpoints.

Security, permissions, and automation

Microsoft Graph uses OAuth 2.0 to authenticate applications. This gives administrators granular control over which data each application can read or modify. The system issues access tokens that remain valid for only a limited time. Administrators must store tokens securely and renew them regularly.

For automated processes, there are two options:

• App registrations in Entra ID using secrets or certificates to generate tokens
• Managed Identities in Azure Functions or Logic Apps, which obtain tokens dynamically without storing secrets in code

Services such as Logic Apps, Power Automate, or Azure Automation also use Graph internally. This enables, for example, the automatic updating of central contacts directly within cloud workflows—without manual steps.

Development environment, access tools, and real-world integration

For administrators and developers, choosing the right tools is crucial to using Graph productively.

• Graph Explorer: Browser-based, allows direct testing of API calls, no code required.

• SDKs: Available for .NET, JavaScript, Python, PHP—ideal for local development environments.

• PowerShell: The Microsoft Graph PowerShell SDK exposes all REST endpoints as cmdlets.

Connect-MgGraph establishes the connection, either interactively with user sign-in or app-based via Entra ID.

In complex enterprise scenarios, automation using Azure Functions, Logic Apps, or Power Automate is common. These services also rely on Graph connectors internally. When running long scripts, administrators must consider access token validity. By default, a token lasts one hour, but you can extend it in certain scenarios by renewing the token. For error handling, Microsoft recommends responding to status codes such as 429 (Rate Limit) and implementing retry logic.

A major advantage of Graph is that you can access multiple data services through a single endpoint:

• Users from Entra ID,
• Teams contacts,
• SharePoint lists, and
• Exchange mailboxes.

This makes it possible to link information about people, groups, devices, and security events in shared workflows. For example, you can use the Microsoft Graph Security API to aggregate security alerts from Defender, Sentinel, or third-party providers and trigger automated responses via Logic Apps.

Migration and organizational impact

For organizations with hybrid or cloud-only environments, migration to Graph becomes mandatory. This transition affects not only applications, but also permission models, audit processes, and security policies. Graph replaces many legacy APIs such as ActiveSync, EWS, and MAPI/HTTP, bringing all Microsoft 365 services under a unified security model.

Administrators should assess early which internal tools, scripts, or add-ins still rely on EWS. Particularly affected are automations for contact maintenance, CRM synchronization, and helpdesk systems. A successful migration includes re-registering applications in Entra ID, replacing legacy endpoints with Graph calls, and reviewing all permissions.

From an organizational perspective, this also changes where contacts should be managed. Keeping local mailboxes, cloud accounts, and hybrid scenarios in sync requires clearly defined responsibilities. Many organizations move contact management entirely to the cloud to avoid duplicate maintenance and to take advantage of Unified Contacts between Outlook and Teams.

This is where the my-IAM platform can help: it consolidates identity and contact data from Active Directory, Entra ID, HR, or CRM systems and makes it available in real time for Exchange Online and Teams. When you change data in one source, all connected systems immediately reflect the update, no scripts or manual reconciliation required. With PeopleConnect, you can display this data centrally in Teams, Outlook, or in the browser.

Strategic outlook

The deprecation of EWS marks the transition to a new era of integration. Microsoft Graph unifies Exchange, Teams, SharePoint, and Entra ID into a single platform that not only delivers data, but also integrates context, security, and intelligence.

Administrators can combine contact management, automation, and compliance within a consistent system. The shift is more than a technical change—it transforms how organizations model their communication structures. Contacts are no longer isolated objects; they now form part of a connected cloud ecosystem.

The follow-up article “Contacts in Exchange on-premises and online: best practices for modern organizations” shows which models work best for centralized contact management, explains how organizations can harmonize cloud and on-premises directories, and outlines the governance structures needed to operate the new architecture sustainably.

Conclusion

Migration to Microsoft Graph is not just a technical switch, but an opportunity to make contact management more modern, secure, and automated. With platforms like my-IAM, organizations can centrally manage internal and external contacts, automate workflows, and ensure compliance.

Those who plan early, replace legacy EWS integrations, and adopt Graph lay a solid foundation for the future and benefit from Unified Contacts, dynamic groups, and real-time synchronization.

What topic should we cover next? Send us your ideas, and we’ll pick them up in our upcoming articles.

Send ideas