Migrate Exchange Folder Agent to Graph API

Introduction

Microsoft has announced the retirement (end of life) of Exchange Web Services (EWS) in Exchange Online. Microsoft plans to start disabling EWS on 1 October 2026 and complete the rollout by 1 April 2027. Organizations using EWS-based Exchange Folder Agents should migrate supported Exchange Online mailbox-folder scenarios to Microsoft Graph before EWS is disabled.

See Microsoft's EWS retirement documentation for the current schedule.

Use this guide to migrate existing Exchange Online user or shared mailbox contact-folder agents from EWS to Microsoft Graph.

Exchange Online public folders: Microsoft Graph cannot read their contacts. An Exchange administrator must copy required contacts to a user or shared mailbox before EWS becomes unavailable. PeopleSync does not move these contacts. Keep the public-folder source until the replacement has been verified and approved.

Choose the correct path

After an upgrade of PeopleSync to version 26.8, existing agents remain on EWS; newly created agents default to Microsoft Graph.

PeopleSync uses only the API selected in Exchange API and does not fall back automatically. The EWS URL is hidden and ignored when Graph is selected.

Before you start

• Confirm that the installed PeopleSync version is at least 26.8

• Record each agent's mailbox, folder path, Is Public Folder value, API, action account, EWS URL, destination address list, enabled state, and schedule

• Classify every agent using the table above and resolve Exchange Online public folders first

• Create the Entra action account using client-secret authentication or a PeopleSync-generated certificate as specified in the PeopleSync Setup and documentation guide, chapter Exchange Folder Agent > Configuration for Office 365 Exchange Online > Microsoft Graph API.

• Configure scoped Application Contacts.Read authorization by following PeopleSync Setup and documentation guide, chapter Action Account

• Verify one allowed mailbox and one existing mailbox outside the scope

• Choose one non-critical mailbox as the pilot

Do not grant tenant-wide Microsoft Graph application permission Contacts.Read when PeopleSync requires only selected mailboxes. Do not place client-secret values, private keys, or actual contact data in migration records, tickets, or screenshots.

Migrating Exchange Folder Agents

Migrate the pilot agent

• Disable the agent. Avoid source-folder changes until the EWS and Graph results have been compared.

• Manually run the agent successfully with EWS. Record source and destination contact counts, representative mapped values, and the current API, action account, EWS URL, mailbox, and folder path.

• Retain the previous EWS action account, credential, permissions, and endpoint until the Graph migration is accepted.

• Open the existing Exchange Folder Agent.

• Select the prepared Entra ID App or Entra ID App Certificate action account and set Exchange API to Microsoft Graph.

• Confirm Mailbox Name / Email Address and Folder Path.

• Save and run the agent, then complete the verification checklist below.

• Contact values must remain unchanged; raw vCard formatting may differ.

Verify and roll out

• The agent run completes without authentication, authorization, retrieval, or mapping errors

• With the source unchanged, source and destination contact counts match the EWS baseline

• Representative names, companies, email addresses, postal addresses, phone numbers, notes, photos, and custom mapped values match.

• No unexpected contacts are added, removed, or duplicated.

• A scheduled execution completes successfully after the agent is re-enabled.

• Agent logging and failure notifications remain operational

• Any difference is documented and approved before cutover

If Graph retrieval or contact mapping fails, PeopleSync fails the complete export and reports the error in the backend log of PeopleSync Console. Do not accept an errored run as a successful partial migration.

After the pilot passes every check, migrate the remaining supported agents. Repeat the verification steps for each agent, and monitor its next scheduled execution. Retain EWS rollback access until all migrated agents are accepted.

Rollback

While EWS remains available for the tenant:

1. Pause the affected agent's schedule and restore the recorded EWS action account and endpoint.

2. Set Exchange API to Exchange Web Services (EWS), save, and run the agent.

3. Correct and retest Graph before attempting cutover again.

PeopleSync does not fall back automatically. Rollback requires the retained EWS credential and permission and is unavailable after Microsoft disables EWS for the tenant.

Migration troubleshooting