EWS to Microsoft Graph Migration

The deprecation timeline

Microsoft will permanently block Exchange Web Services (EWS) for Exchange Online on October 1, 2026, with full removal on April 1, 2027. The deprecation affects over 400 million Microsoft 365 commercial seats worldwide. Microsoft first announced the retirement in September 2023 and has tightened the schedule three times since then.

According to Microsoft's official deprecation page, the key dates are:

If you do nothing, your EWS-based code returns errors starting October 2026. The TechCommunity announcement confirms that Microsoft will set EWSEnabled=False on tenants that haven't opted in.

On-premises Exchange: not affected

The EWS deprecation applies only to Exchange Online (Microsoft 365). Exchange Server 2016 and 2019 running on-premises keep full EWS support with no end-of-life date announced. Organizations running hybrid Exchange -- which Microsoft estimates at roughly 40% of enterprise Exchange deployments -- face a split: cloud mailboxes must migrate to Graph API while on-prem mailboxes continue using EWS.

This dual-protocol reality means hybrid environments need two authentication flows and two API surfaces, or an abstraction layer that routes requests to the correct protocol based on mailbox location.

Auth model: NTLM/Basic to OAuth 2.0

Migrating from EWS to Microsoft Graph requires replacing NTLM, Kerberos, or Basic Auth with OAuth 2.0 through Azure AD (now Entra ID) app registrations. Microsoft deprecated Basic Auth for Exchange Online in October 2022, and Graph API has required OAuth 2.0 since launch. Access tokens expire every 60-90 minutes, and refresh tokens last 90 days before requiring re-authentication.

• Register an Azure AD app with Mail.Read, Mail.Send, Calendars.ReadWrite, or other scopes
• Choose a flow: authorization code (delegated) for user context, client credentials (application) for daemon/service apps
• Handle token lifecycle: access tokens expire in 60-90 minutes, refresh tokens in 90 days
• Admin consent: application-level permissions need tenant admin approval

The code below shows the difference between EWS Basic Auth and Graph OAuth 2.0 authentication. EWS required as few as 3 lines to connect, while Graph needs an Azure AD app registration with the correct scopes configured before any API call can succeed.

# EWS (old) - Basic Auth or NTLM
$cred = Get-Credential
$service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService
$service.Credentials = $cred
$service.Url = "https://outlook.office365.com/EWS/Exchange.asmx"

# Graph API (new) - OAuth 2.0 with MSAL
Connect-MgGraph -Scopes "Mail.Read","Mail.Send"
$messages = Get-MgUserMessage -UserId "me" -Top 10

Feature parity gaps (as of April 2026)

Microsoft Graph API covers core mail, calendar, and contacts operations but still lacks full parity with EWS in at least 4 areas: archive mailbox access, public folder CRUD, mailbox import/export, and recurring event delta queries. Microsoft has been closing gaps on a quarterly release cadence since 2024, yet has not committed to a date for complete feature parity.

The table below maps each EWS feature to its Graph API status. The data comes from Microsoft's TechCommunity update and covers the 10 most commonly referenced EWS capabilities:

Microsoft released the Exchange Admin API as a temporary bridge for some gaps. But there's no firm date for when all parity gaps close.

Three migration paths

Organizations moving off EWS have three options: migrate directly to Microsoft Graph API, register for a temporary AppID AllowList extension, or adopt a provider-agnostic abstraction layer. The right choice depends on timeline, hybrid Exchange requirements, and how many providers your application supports. Most teams need 2-6 months for a direct Graph migration, according to Microsoft's own planning guidance.

Path 1: Migrate to Microsoft Graph API

The official path replaces every EWS call with its Graph equivalent. Microsoft provides an EWS code analyzer that scans your codebase and maps EWS operations to Graph API equivalents. The analyzer outputs a CSV report listing each EWS method, its call count, and the corresponding Graph endpoint.

# EWS: Find emails by subject
$view = New-Object Microsoft.Exchange.WebServices.Data.ItemView(50)
$filter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+ContainsSubstring(
  [Microsoft.Exchange.WebServices.Data.ItemSchema]::Subject, "invoice")
$results = $service.FindItems(
  [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Inbox, $filter, $view)

# Graph: Same operation
$messages = Get-MgUserMessage -UserId "me" -Filter "contains(subject, 'invoice')" -Top 50

Pros: Stays within the Microsoft ecosystem, access to newest features. Cons: Azure AD app registration, OAuth token management, no support for non-Microsoft providers, feature parity gaps.

Path 2: Temporary AppID AllowList

The AllowList extends EWS access by 6 months, from October 2026 to April 1, 2027. Tenant admins must register their application's client ID before August 2026, or the exemption won't take effect. Microsoft's documentation warns that this is a one-time extension with no option to renew beyond April 2027.

# Check current EWS settings
Get-OrganizationConfig | Select-Object EwsEnabled, EwsAllowList

# Add your app to the AllowList
Set-OrganizationConfig -EwsAllowList @{Add="your-app-client-id"}
Set-OrganizationConfig -EwsEnabled $true

Pros: No code changes needed immediately. Cons: Only delays the problem by 6 months. EWS is permanently removed April 1, 2027.

Path 3: Use a unified abstraction

A provider-agnostic abstraction handles EWS and Graph routing internally, so your code doesn't change when Microsoft retires a protocol. Nylas CLI connects to Exchange Online, on-prem Exchange, Gmail, Outlook, Yahoo, iCloud, and IMAP through one interface. The same commands work across all 6 providers without protocol-specific logic.

# Install
brew install nylas/nylas-cli/nylas

# Authenticate (handles OAuth, EWS, Graph internally)
nylas auth config

# Read email -- works regardless of whether the mailbox is
# Exchange Online (Graph), Exchange on-prem (EWS), or Gmail
nylas email list --limit 10

# Search
nylas email search "invoice" --limit 50

# Send
nylas email send \
  --to "colleague@company.com" \
  --subject "Report" \
  --body "Attached." \
  --attach ./report.pdf

Pros: No protocol-specific code, no Azure AD app registration, works across all providers, on-prem and cloud through one interface. Cons: External dependency. Requires Nylas API key.

Side-by-side comparison

The three approaches differ in authentication complexity, provider coverage, and migration effort. EWS supported 3 auth methods (NTLM, Kerberos, Basic), Graph API requires OAuth 2.0 exclusively, and Nylas CLI handles authentication through a single configuration command. The table below compares all three across 7 operational concerns that affect migration planning.

Hybrid Exchange: the dual-codebase problem

Hybrid Exchange environments must maintain two separate codepaths after October 2026: Microsoft Graph for cloud mailboxes and EWS for on-premises Exchange Server. Microsoft Graph has no support for on-prem Exchange Server, which means organizations with split deployments cannot consolidate on a single Microsoft API. According to Microsoft's hybrid documentation, hybrid configurations account for a significant share of enterprise Exchange deployments.

This dual-protocol split forces two authentication flows (Azure AD OAuth for Graph, NTLM or Kerberos for on-prem EWS), two API surfaces, and two sets of error handling in the same application. The Nylas platform handles this routing internally -- it detects whether a mailbox is cloud or on-prem and uses the appropriate protocol without code changes.

Migration checklist

A complete EWS migration touches authentication, API surface, error handling, and testing across all affected license types. Microsoft recommends starting migration at least 3 months before the October 2026 deadline to account for Azure AD app registration, admin consent, and testing cycles. The 6 steps below cover the end-to-end process from audit to production cutover.

1. Audit your EWS usage -- Run Microsoft's EWS code analyzer to inventory every EWS call
2. Check for parity gaps -- Compare your EWS operations against the feature gap table above
3. Register your app before August 2026 -- If you need more time, add your app to the AllowList
4. Test with F1/F3 licenses first -- These were blocked in March 2026, so they're already on the new behavior
5. Plan for hybrid -- If you have on-prem Exchange, decide how to handle the dual-protocol split
6. Monitor Microsoft's updates -- Feature parity gaps are closing quarterly

Frequently asked questions

The EWS deprecation raises questions about timelines, on-premises impact, feature gaps, and migration alternatives. These are the 4 most common questions from developers planning their migration, based on the topics covered in Microsoft's TechCommunity forums and the official deprecation documentation.

When is EWS being retired for Exchange Online?

Microsoft blocks EWS requests from non-Microsoft apps starting October 1, 2026. Tenants that configure an AppID AllowList before August 2026 get a temporary exemption. All EWS access is permanently removed on April 1, 2027.

Is EWS deprecated for on-premises Exchange Server?

No. EWS remains fully supported for Exchange Server 2016 and 2019. The deprecation only affects Exchange Online (Microsoft 365).

What EWS features are missing from Graph API?

As of April 2026, Graph API lacks archive mailbox access, public folder CRUD, mailbox import/export, and full recurring event delta support. Microsoft is closing gaps quarterly but hasn't committed to a date for full parity.

Can I skip the migration entirely?

Yes, if you use an abstraction layer. The Nylas platform connects to Exchange Online, on-prem Exchange, and 4 other providers through a single interface. Provider-side deprecations don't require code changes on your end.

Next steps

After planning your EWS migration path, the guides below cover specific Exchange operations through the Nylas CLI. Each guide includes tested commands, provider-specific troubleshooting, and code examples for the 6 supported providers.

• List Exchange emails from the CLI -- read and search Exchange mailboxes without EWS or Graph
• Manage Exchange calendar from the CLI -- create, update, and delete events
• Replace Send-MgUserMessage -- migrate from Graph PowerShell cmdlets
• Manage Office 365 email from PowerShell -- read, search, and organize your M365 inbox
• Send email from the terminal -- the cross-provider email sending guide
• Full command reference -- every flag and subcommand documented