EWS to Microsoft Graph: The API Migration Every Outlook Add-In Developer Must Complete by October 2026
Microsoft has confirmed that Exchange Web Services will cease to accept connections from Outlook add-ins on 1 October 2026. That date is not a soft deprecation with a grace period — it is a hard enforcement boundary. Add-ins that still call EWS after that date will fail for users on Exchange Online. If your Outlook add-in relies on EWS for mail retrieval, calendar operations, contact management, or task synchronisation, the migration to Microsoft Graph is not optional.
This guide is specifically for development teams and IT architects who need to plan and execute the migration from EWS to Microsoft Graph. If you are looking for a guide to building a new Outlook add-in with Microsoft Graph from scratch, we cover that in our article on building an Outlook add-in with Microsoft Graph API. This article focuses on the distinct engineering challenge of migrating an existing EWS-dependent codebase to Graph equivalents — a challenge compounded, for many teams, by the simultaneous pressure of the VSTO migration deadline in April 2026.
The Deprecation Timeline and Key Dates
Understanding the full timeline is essential for migration planning. EWS deprecation is not a single event — it is a staged enforcement that has already begun.
| Date | Event |
|---|---|
| October 2023 | Microsoft announced EWS deprecation for Exchange Online. No new feature development for EWS from this point. |
| March 2026 | EWS blocked for frontline and kiosk licences (F1, F3). Add-ins making EWS calls on behalf of these users will receive errors. |
| October 1, 2026 | EWS fully blocked for all Exchange Online licence types. All EWS connections from Outlook add-ins to Exchange Online will be refused. |
The March 2026 enforcement event deserves specific attention. If your add-in serves users on Microsoft 365 F1 or F3 licences — common in retail, field service, healthcare, and manufacturing — those users will encounter failures before the broader October deadline. Organisations with mixed licence estates may see the problem surface in a subset of users first, which can complicate support and root-cause analysis if teams have not planned for the staged rollout.
It is also worth clarifying what EWS deprecation does and does not affect. The deprecation applies to Exchange Online only. If your add-in connects to Exchange Server on-premises, EWS remains available — Microsoft has made no announcement of on-premises EWS deprecation. However, given Microsoft’s trajectory, planning your add-in architecture around on-premises EWS as a long-term foundation carries obvious risk.
Understanding the Scope of Your EWS Usage
Before planning your migration, map every EWS call in your codebase. EWS usage in Outlook add-ins typically falls into several categories:
Direct EWS calls from add-in code. These are explicit HTTP requests to the Exchange Web Services endpoint, typically using a SOAP envelope. Search your codebase for references to https://outlook.office365.com/EWS/Exchange.asmx or similar EWS endpoint patterns.
EWS via the Managed API. The Exchange Web Services Managed API (Microsoft.Exchange.WebServices) is a .NET wrapper around EWS. It is particularly common in VSTO add-ins and older web add-in backends.
Server-side EWS calls from add-in backends. Many Outlook add-ins use EWS not in the browser-side Office.js code, but in server-side components that synchronise mailbox data, run background tasks, or process mail server-side. These backend EWS dependencies need migration alongside the client-side code.
EWS through Office.js makeEwsRequestAsync. The Office.js API exposes a makeEwsRequestAsync method that allows add-in code running in the browser to make EWS calls proxied through the Office host. This method will also stop working when EWS is blocked.
Creating a complete inventory before estimating migration effort will prevent unpleasant surprises mid-project.
API Surface Comparison: EWS vs Microsoft Graph
Microsoft Graph has reached near-complete functional parity with EWS for the operations that Outlook add-ins commonly need. The table below maps the most common EWS operations to their Microsoft Graph equivalents.
Mail Operations
| EWS Operation | EWS Approach | Microsoft Graph Equivalent |
|---|---|---|
| Retrieve messages | GetItem / FindItem on folder | GET /me/messages or GET /me/mailFolders/{id}/messages |
| Get message details | GetItem with message shape | GET /me/messages/{id} |
| Create message | CreateItem | POST /me/messages |
| Send message | SendItem | POST /me/sendMail |
| Reply to message | CreateItem with ReplyToItem action | POST /me/messages/{id}/reply |
| Move message | MoveItem | POST /me/messages/{id}/move |
| Copy message | CopyItem | POST /me/messages/{id}/copy |
| Delete message | DeleteItem | DELETE /me/messages/{id} |
| Search messages | FindItem with search restriction | GET /me/messages?$filter=... or POST /me/messages/search |
| Get attachments | GetAttachment | GET /me/messages/{id}/attachments |
| Add attachment | CreateAttachment | POST /me/messages/{id}/attachments |
| Subscribe to push notifications | Subscribe with push subscription | POST /subscriptions |
| Streaming notifications | GetStreamingEvents | Graph change notifications with webhooks |
Calendar Operations
| EWS Operation | EWS Approach | Microsoft Graph Equivalent |
|---|---|---|
| List calendar events | FindItem on calendar folder | GET /me/events or GET /me/calendars/{id}/events |
| Get event details | GetItem on calendar item | GET /me/events/{id} |
| Create event | CreateItem in calendar | POST /me/events |
| Update event | UpdateItem | PATCH /me/events/{id} |
| Delete event | DeleteItem | DELETE /me/events/{id} |
| Accept/decline meeting | CreateItem with AcceptItem | POST /me/events/{id}/accept or /decline |
| Get free/busy | GetUserAvailability | POST /me/calendar/getSchedule |
| Get calendar view | FindItem with calendar view | GET /me/calendarView?startDateTime=...&endDateTime=... |
| List calendars | FindFolder on calendar root | GET /me/calendars |
| Create calendar | CreateFolder | POST /me/calendars |
Contacts Operations
| EWS Operation | EWS Approach | Microsoft Graph Equivalent |
|---|---|---|
| List contacts | FindItem on contacts folder | GET /me/contacts |
| Get contact details | GetItem | GET /me/contacts/{id} |
| Create contact | CreateItem | POST /me/contacts |
| Update contact | UpdateItem | PATCH /me/contacts/{id} |
| Delete contact | DeleteItem | DELETE /me/contacts/{id} |
| Search contacts | FindItem with name filter | GET /me/contacts?$filter=displayName eq '...' |
| Get contact photo | GetUserPhoto | GET /me/contacts/{id}/photo/$value |
| List contact folders | FindFolder | GET /me/contactFolders |
Tasks Operations
EWS tasks — stored in the Exchange Tasks folder — map to Microsoft Graph’s To Do API. Note that this is a more significant shift than the mail and calendar migrations: the underlying data model differs, and the Graph To Do API represents a substantially richer capability set than what EWS tasks provided.
| EWS Operation | EWS Approach | Microsoft Graph Equivalent |
|---|---|---|
| List tasks | FindItem on tasks folder | GET /me/todo/lists/{id}/tasks |
| Get task details | GetItem | GET /me/todo/lists/{id}/tasks/{taskId} |
| Create task | CreateItem | POST /me/todo/lists/{id}/tasks |
| Update task | UpdateItem | PATCH /me/todo/lists/{id}/tasks/{taskId} |
| Complete task | UpdateItem (set status) | PATCH /me/todo/lists/{id}/tasks/{taskId} with status: completed |
| Delete task | DeleteItem | DELETE /me/todo/lists/{id}/tasks/{taskId} |
| List task lists | FindFolder on tasks root | GET /me/todo/lists |
Authentication Changes
The authentication architecture change from EWS to Microsoft Graph is one of the most impactful aspects of the migration.
EWS Authentication Methods
EWS in legacy Outlook add-ins used one of two primary authentication approaches:
Basic authentication. Username and password sent with each SOAP request. Microsoft deprecated basic authentication for EWS in Exchange Online in 2021 — if your add-in still uses basic auth, it has already stopped working for most tenants.
Exchange impersonation with service accounts. Server-side EWS applications commonly use a service account with the ApplicationImpersonation RBAC role, allowing the service to make EWS calls on behalf of arbitrary mailboxes. Certificate-based authentication or client credentials were typically used to authenticate the service account.
Microsoft Graph OAuth 2.0 via MSAL
Microsoft Graph authentication uses OAuth 2.0 mediated by Microsoft Entra ID (formerly Azure AD). The recommended library is MSAL (Microsoft Authentication Library).
For delegated permission flows — where the add-in acts on behalf of the signed-in user — the typical flow uses the authorisation code grant with PKCE:
import { PublicClientApplication } from '@azure/msal-browser';
const msalConfig = {
auth: {
clientId: 'your-app-client-id',
authority: 'https://login.microsoftonline.com/common',
redirectUri: 'https://your-add-in-domain.com/auth-callback'
}
};
const msalInstance = new PublicClientApplication(msalConfig);
const loginRequest = {
scopes: ['Mail.Read', 'Calendars.ReadWrite', 'Contacts.ReadWrite']
};
// Initiate sign-in
const authResult = await msalInstance.loginPopup(loginRequest);
const accessToken = authResult.accessToken;
For application permission flows — where a server-side component accesses multiple mailboxes without a signed-in user — use the client credentials grant:
import { ConfidentialClientApplication } from '@azure/msal-node';
const cca = new ConfidentialClientApplication({
auth: {
clientId: 'your-app-client-id',
authority: 'https://login.microsoftonline.com/your-tenant-id',
clientCertificate: {
thumbprint: 'cert-thumbprint',
privateKey: fs.readFileSync('./cert.key', 'utf8')
}
}
});
const tokenResponse = await cca.acquireTokenByClientCredential({
scopes: ['https://graph.microsoft.com/.default']
});
Application permissions replace the ApplicationImpersonation pattern from EWS. Instead of a service account with impersonation rights, you register an Entra ID application with the Mail.Read / Mail.ReadWrite (and equivalent) application permissions, which are granted by a tenant administrator.
The key practical difference: application permissions in Microsoft Graph require admin consent from each tenant that deploys your add-in. This is a change in your onboarding and deployment process, not just your code.
Migration Strategies for Add-Ins Using Both EWS and Office.js
Modern Outlook web add-ins typically use Office.js for item context (accessing the currently-selected email, composing messages in the active compose window) alongside EWS or Microsoft Graph for operations that Office.js does not directly support, such as accessing other mailbox folders, searching the mailbox, or synchronising data.
The migration approach depends on where EWS is being called:
Strategy 1: Replace EWS Calls with Microsoft Graph Calls Directly
For add-ins where EWS calls are made from add-in JavaScript code (including via makeEwsRequestAsync), the migration involves replacing each EWS SOAP operation with the equivalent Microsoft Graph REST call. The Microsoft Graph SDK for JavaScript simplifies this:
import { Client } from '@microsoft/microsoft-graph-client';
import { TokenCredentialAuthenticationProvider } from '@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials';
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
scopes: ['https://graph.microsoft.com/.default']
});
const graphClient = Client.initWithMiddleware({ authProvider });
// Replace EWS FindItem with Graph messages query
const messages = await graphClient
.api('/me/messages')
.filter("isRead eq false")
.select('id,subject,from,receivedDateTime,bodyPreview')
.top(25)
.get();
Strategy 2: Move EWS Logic to a Server-Side Component, Then Migrate
For complex EWS operations, it can be pragmatic to first consolidate all EWS calls into a single server-side service layer, then migrate that layer to Microsoft Graph. This avoids scattering Graph migration work across multiple client-side code paths and makes testing more tractable — you can run EWS and Graph implementations side by side, comparing outputs before switching.
Strategy 3: Use the Office.js REST API for Delegated Operations Where Possible
For simpler delegated operations — reading the current message, accessing basic mail properties — the Office.js Office.context.mailbox.makeRestRequestAsync method provides a simplified path to call the Outlook REST API (a subset of Microsoft Graph) without managing OAuth tokens directly in the add-in code. This method handles token acquisition automatically for the signed-in Outlook user.
// Get the current item's REST ID
const itemId = Office.context.mailbox.convertToRestId(
Office.context.mailbox.item.itemId,
Office.MailboxEnums.RestVersion.v2_0
);
// Call Graph via makeRestRequestAsync (token handled automatically)
Office.context.mailbox.makeRestRequestAsync(
`https://outlook.office.com/api/v2.0/me/messages/${itemId}`,
'GET',
null,
null,
function(result) {
if (result.status === Office.AsyncResultStatus.Succeeded) {
const message = JSON.parse(result.value);
// Process message
}
}
);
This approach is limited to the current user’s context and the Outlook REST API surface, but it eliminates the authentication complexity for the most common add-in operations.
The Dual Migration Challenge
Teams that are simultaneously managing the VSTO migration deadline (April 2026) and the EWS deprecation deadline (October 2026) face compounding complexity. The two migrations interact in important ways:
VSTO add-ins almost certainly use the EWS Managed API. If your migration path involves rewriting VSTO add-ins as web add-ins, you are not just changing the platform — you are also changing the API layer. A VSTO add-in built on the EWS Managed API needs its data access layer rebuilt using Microsoft Graph.
The authentication models differ significantly. VSTO add-ins authenticate using Windows identity (typically NTLM or Kerberos for on-premises Exchange, or Windows-integrated credentials for Exchange Online). Microsoft Graph uses OAuth 2.0 via Entra ID. Migrating both adds-in type and API simultaneously means your developers need to understand both the Office.js API surface and the Microsoft Graph API surface, plus MSAL-based token management — a significant knowledge uplift.
Testing scope doubles. You cannot validate the VSTO-to-web-add-in migration independently of the EWS-to-Graph migration if both are happening in the same codebase. Test plans must cover both dimensions.
The practical recommendation for teams facing both deadlines: prioritise the VSTO migration first (April 2026 is the nearer deadline), but design the web add-in with Microsoft Graph from the outset rather than implementing EWS as a temporary measure in the new web add-in. Building EWS into a newly-created web add-in, only to migrate it again before October 2026, is engineering effort you cannot afford.
The AppID AllowList: A Temporary Measure, Not a Solution
Microsoft has provided an AppID AllowList mechanism for organisations that cannot complete their EWS migration by the October 2026 deadline. This allows specific Entra ID application registrations to be added to an allowlist, temporarily exempting them from the EWS block.
The AppID AllowList is not a permanent solution. Microsoft has been explicit that it exists to provide a short grace period for genuine migration completion, not as an indefinite workaround. Organisations granted AllowList status will still be required to complete migration — the enforcement mechanism will simply be deferred rather than waived.
Consider the AllowList only if:
- Your migration is underway and you have a concrete completion date beyond October 2026.
- You have a documented migration plan and resource commitment in place.
- The components requiring AllowList coverage are genuinely complex (for example, server-side EWS integrations with legacy enterprise systems that have external dependencies).
Do not use the AllowList as an excuse to defer migration planning. The process for requesting AllowList inclusion is not automatic — it requires engagement with Microsoft and documentation of your migration progress. Starting that engagement before October 2026 is advisable.
Testing Your Microsoft Graph Migration
Validating that the migrated Microsoft Graph implementation is behaviourally equivalent to the EWS implementation requires a structured approach:
Functional Equivalence Testing
For each migrated operation, create tests that verify the Microsoft Graph response contains the expected data fields. Be aware that field names differ between EWS and Graph: for example, EWS PR_INTERNET_MESSAGE_ID becomes internetMessageId in Graph, and EWS DateTimeReceived becomes receivedDateTime.
Pagination Handling
EWS uses FindItem with IndexedPageItemView for pagination. Microsoft Graph uses OData $top and $skip parameters, or nextLink cursors for server-side pagination. Migrated code must handle Graph’s pagination model, which differs from EWS’s offset-based approach.
// Graph pagination using nextLink
async function getAllMessages(graphClient) {
const messages = [];
let response = await graphClient
.api('/me/messages')
.top(100)
.get();
messages.push(...response.value);
while (response['@odata.nextLink']) {
response = await graphClient
.api(response['@odata.nextLink'])
.get();
messages.push(...response.value);
}
return messages;
}
Permissions Validation
Test your add-in with users who have different permission levels and licence types. Pay particular attention to:
- Users whose mailboxes are hosted in specific Exchange Online regions (Graph endpoint routing differs by region).
- Guest users, where Graph permissions behave differently from EWS impersonation.
- Shared mailboxes, which require specific Graph permission configurations.
Change Notification Testing
If your add-in uses EWS streaming or push notifications to detect new mail or calendar changes, the migration to Microsoft Graph change notifications (webhooks) requires specific testing. Graph change notifications are delivered via HTTPS POST to a webhook endpoint, and your add-in’s notification processing infrastructure will need to be rebuilt to receive and validate these messages.
Performance Benchmarking
EWS SOAP requests and Microsoft Graph REST calls have different performance characteristics. If your add-in performs bulk operations — retrieving large numbers of messages, processing calendar ranges — benchmark the Graph implementation under production-representative load before go-live.
Registering Your Application in Microsoft Entra ID
Before your add-in can make Microsoft Graph calls, you must register it in Microsoft Entra ID. The app registration is foundational to the migration:
- In the Azure portal, navigate to Microsoft Entra ID > App registrations > New registration.
- Provide a name and set the supported account types (single tenant, multitenant, or personal accounts as appropriate for your add-in audience).
- Configure the redirect URI to your add-in’s authentication callback.
- Under API permissions, add the Microsoft Graph permissions required for your operations. Use delegated permissions for user-context operations and application permissions for service-to-service access.
- For application permissions, submit an admin consent request — or, during development, use the “Grant admin consent” button in the portal if you have the appropriate Entra ID role.
- Generate a client secret (for development) or configure certificate credentials (for production).
Document the required permissions clearly. When your add-in is deployed to a new tenant, an administrator must consent to those permissions. Unexpected permission scopes discovered during deployment will stall your rollout.
Get Expert Help with Your EWS Migration
The convergence of migration deadlines in 2026 — VSTO in April, EWS in October — means that Outlook add-in development teams are facing an unusually compressed planning window. The technical scope of an EWS-to-Graph migration is often underestimated: the API surface change, the authentication architecture change, the pagination model change, and the shift in how permissions are granted all require careful design and thorough testing.
For organisations managing both the VSTO migration deadline and the EWS deprecation simultaneously, the complexity compounds further. Getting the sequencing wrong — building EWS into a new web add-in, or migrating to Graph before the VSTO migration is stable — creates rework that Q1 and Q2 2026 timelines simply cannot absorb.
McKenna Consultants is a UK-based Office add-in development consultancy with deep expertise in both Office.js web add-in development and Microsoft Graph API integration. We have guided clients through API migrations across the Microsoft 365 platform and understand the sequencing decisions that make the difference between a smooth migration and a costly rework.
If you are planning your EWS-to-Microsoft-Graph migration and need architectural guidance, implementation support, or an independent review of your migration plan, contact McKenna Consultants to discuss your requirements. We can help you reach October 2026 with a fully migrated, Graph-native add-in — without disrupting users in the process.
