Exchange Web Services is gone. As of 1 October 2026, Microsoft has retired EWS for Exchange Online, and the bridges that many Outlook add-ins quietly relied upon — makeEwsRequestAsync, callback tokens, streaming notifications against your own mailbox subscriptions — are no longer something you can build on. If your team has completed, or is in the final stages of, its EWS to Microsoft Graph migration, the pressing question is no longer “how do we get off EWS?” It is “now that we are Graph-only, what does a well-designed Outlook add-in actually look like?”
This article is about the durable target architecture. Not the mechanics of porting calls one by one, but the patterns that Microsoft Graph Outlook add-in development makes natural — patterns the EWS era made awkward, expensive, or impossible. The goal is to design something that will still be sound in 2027 and beyond: cleanly authenticated, event-driven, throttling-aware, testable, and ready for Copilot and agent extensibility to be layered on without a rewrite.
If you treated the migration purely as a like-for-like swap, you have likely carried forward habits that no longer serve you. The Graph-only world rewards a different shape of system. Here is how we think about it.
Identity and Token Flow: Nested App Authentication and On-Behalf-Of
The single biggest architectural shift is how an add-in proves who the user is and acquires the right to call services on their behalf. Under EWS, many add-ins leaned on Exchange callback tokens and identity tokens issued by the host — a convenient but increasingly constrained model that Microsoft has deprecated. The Graph-only replacement is built around modern OAuth 2.0 flows, and getting this layer right is foundational because everything else depends on it.
For new and modernised Outlook add-ins, nested app authentication (NAA) is the recommended approach. NAA lets your add-in acquire tokens through MSAL while running nested inside the Outlook host, without the brittleness of the older dialog-based single sign-on flow and its pop-up fallbacks. The add-in obtains a token for Microsoft Graph, or for your own API, using the user’s existing Outlook session as the basis for silent authentication. The user experience is seamless and, critically, the token acquisition logic lives in well-supported library code rather than bespoke plumbing.
Where your add-in needs to call Graph from a backend service — and as we will argue below, it usually should — the on-behalf-of (OBO) flow is the pattern that ties the front end to the back end securely. The add-in acquires an access token scoped to your API, sends it to your backend, and the backend exchanges that token for a Graph token representing the same user. The user’s delegated permissions flow through cleanly; your backend never sees a password, and you never store long-lived user credentials.
Designing this layer well means being deliberate about scopes. Request the least privilege you need — Mail.Read rather than Mail.ReadWrite if you only read, Calendars.Read where calendar write is not required — and document why each scope exists. Admin consent conversations with your customers’ IT teams go far more smoothly when your permission set is minimal and justified. It also means deciding early whether a given operation should run as the signed-in user (delegated) or as the application (application permissions) — for example, a background reconciliation job that runs without a user present needs application permissions and a separate, carefully governed consent path.
The architectural payoff is significant. By centralising identity on NAA and OBO, you decouple the question “who is this user and what may they do?” from the question “what does this feature do?” That separation is exactly what the callback-token era made hard.
Change Notifications Instead of Polling: Webhooks and Subscriptions
The EWS world gave you streaming and pull subscriptions to know when a mailbox changed. Add-ins and companion services that needed to react to new mail or calendar updates either held open streaming connections or polled on a timer. Both approaches were operationally heavy and scaled poorly.
Microsoft Graph replaces this with change notifications — webhooks driven by subscriptions. You create a subscription against a resource, such as /me/messages, /users/{id}/events, or a specific mail folder, and Graph posts a notification to your HTTPS endpoint whenever a matching change occurs. This is a fundamentally better fit for a modern add-in architecture, but it has its own design discipline.
A few patterns are worth building in from the start:
- Validate and renew subscriptions deliberately. Graph subscriptions have a maximum lifetime that varies by resource (commonly measured in days for mail and calendar), so your backend needs a renewal job that extends subscriptions before they expire. Treat subscription lifecycle as first-class infrastructure, not an afterthought.
- Acknowledge fast, process asynchronously. Your notification endpoint should validate the incoming notification, enqueue the work, and return
202quickly. Doing real work inline risks timeouts and missed notifications. A lightweight queue between the webhook and your processing logic absorbs bursts and isolates failures. - Treat notifications as hints, not payloads. A change notification tells you something changed; for anything beyond trivial cases, fetch the current state from Graph using the resource ID rather than trusting the notification body. Use
clientStateto verify authenticity and consider rich notifications with resource data and encryption only where the payload genuinely saves a round trip. - Design for delta. For mailbox and calendar synchronisation, pair notifications with Graph delta queries (
/me/messages/delta) so that when you do reconcile, you pull only what changed since your last sync token. This is the natural successor to the synchronisation gymnastics EWS required.
The result is an event-driven backbone: Graph tells you when something happens, your service reacts, and your add-in surface stays responsive because it is not the thing doing the polling.
Designing for Throughput: JSON Batching and Throttling-Aware Patterns
EWS had its own throttling policies, but they were opaque and inconsistent. Graph throttling is, by contrast, well-documented and predictable — which means you can and should design for it explicitly rather than discovering limits in production.
Two techniques belong in every serious Microsoft Graph Outlook add-in development effort.
JSON batching lets you combine up to twenty individual requests into a single HTTP call to the $batch endpoint. When your add-in needs to read a message, fetch the sender’s profile photo, and check a calendar in one user interaction, batching turns three round trips into one. It reduces latency, reduces the number of requests counted against your limits, and simplifies error handling because the batch response tells you the status of each sub-request. Be mindful that requests within a batch can be reordered unless you declare dependencies with dependsOn, and that an individual request inside a batch can be throttled even when the batch as a whole succeeds.
Throttling-aware design means treating 429 Too Many Requests as an expected condition, not an error to log and forget. When Graph throttles you it returns a Retry-After header; the correct behaviour is to honour it. Where Retry-After is absent, or where you are issuing many concurrent requests, implement exponential backoff with decorrelated jitter so that retrying clients do not synchronise and hammer the service in lockstep. A retry policy along these lines — respect Retry-After first, otherwise back off with randomised, capped delays, and cap total attempts — keeps your add-in resilient under load and avoids cascading failures.
Crucially, this logic belongs in one place. If retry and batching behaviour is scattered across every Graph call in your add-in’s JavaScript, you will get it subtly wrong somewhere. Centralising it in a shared client — ideally in the backend service discussed next — means you implement it once, test it once, and benefit everywhere.
Lifecycle and Activation: Event-Based Add-Ins and the Unified Manifest
The EWS era’s add-ins were largely defined by buttons that opened task panes. The Graph-only era invites a richer, more integrated lifecycle, and two capabilities are central to designing it well.
Event-based activation lets your add-in run code in response to Outlook events without the user opening a task pane at all. The canonical example is OnMessageSend and OnAppointmentSend handlers that run when a user sends an item — useful for compliance checks, automatic tagging, or recipient validation. Event-based activation runs in a lightweight runtime and is subject to timeouts and constraints, which makes the case for keeping the in-client handler thin and delegating substantive work to your backend even stronger. Smart Alerts built on send events are a far cleaner pattern than the client-side hooks teams used to bolt on.
The unified manifest for Microsoft 365 is the other half of the lifecycle story. It brings Outlook add-ins into the same JSON manifest model used across Microsoft 365 extensibility, replacing the older add-in-only XML manifest. Adopting it positions your add-in for the integrated experiences Microsoft is building around a single app definition — and, importantly, it is the manifest model that Copilot and agent extensibility build on. If you are architecting for 2027, designing against the unified manifest now means you are not facing a second migration when you want to add agent capabilities later.
Think of activation as a spectrum: ribbon commands and task panes for rich interaction, event-based handlers for automation at the moment of action, and a manifest that can grow to describe more than just an add-in. Designing for all three from the outset avoids painting yourself into a corner.
Decoupling Add-In Logic into a Backend Service
Almost every recommendation above points in the same direction: get the heavy lifting out of the add-in’s client-side code and into a backend API service that you own. This is the architectural decision that most distinguishes a robust Graph-only add-in from a fragile one.
Under EWS, logic tended to live in the add-in because that was where the callback token lived. With OBO, that constraint is gone. Your add-in can acquire a token for your API, and your API can do the real work. The benefits compound:
- Testability. Business logic in a backend service can be unit and integration tested with proper tooling, mocked Graph responses, and CI pipelines. Logic trapped in an Outlook task pane is far harder to test and almost impossible to test deterministically against the host.
- Reuse across clients. The same backend can serve your Outlook add-in, a Teams app, a web portal, and a future agent. You implement “summarise this thread” or “file this email against a case” once. Without a backend, you reimplement it per surface.
- Secret handling. Client secrets, certificates, and application permissions must never sit in browser-delivered JavaScript. A backend service is the only correct home for them. This alone is sufficient reason for many features to require a backend.
- Centralised resilience. Batching, retry-with-jitter, subscription management, and delta synchronisation all live in one well-tested layer rather than being duplicated across the front end.
- Auditability and governance. A backend gives you a single place to log Graph access, enforce policy, and satisfy the data-handling requirements that enterprise customers increasingly demand.
The add-in becomes a thin, well-behaved presentation layer: it authenticates the user, renders UI, and calls your API. Your API holds the logic and talks to Graph. This is not over-engineering — it is the shape that makes everything else in this article practical to implement and maintain.
Future-Proofing for Copilot and Agent Extensibility
The most strategic reason to design carefully now is that the Microsoft 365 platform is moving towards AI-assisted and agentic experiences, and the architecture described above is precisely the foundation those experiences need. You do not need to build Copilot integration today. You need to avoid decisions that would prevent it tomorrow.
Three design choices keep that door open.
First, the unified manifest is the same manifest model that declarative agents and agent extensions use. An add-in already defined there is a short step from describing an agent alongside it.
Second, the backend API service is exactly what agent extensibility wants to call. The actions a declarative agent can take, or the operations a Copilot plugin exposes, map naturally onto the endpoints you have already built and tested. If your logic is locked inside an Outlook task pane, an agent cannot reach it; if it is a clean API, the agent simply calls it.
Third, Graph connectors let you bring your organisation’s data into the Microsoft 365 substrate so that Copilot and search can reason over it. If your add-in works with bespoke data — case records, project metadata, line-of-business entities — designing your backend so that the same data can be surfaced through a Graph connector means your add-in and your future AI experiences share one source of truth rather than diverging.
The pattern is consistent: clean identity, an event-driven backbone, centralised resilient Graph access, and a testable backend are not just good hygiene for an add-in. They are the substrate on which Copilot and agents are built. Architect for them now and the AI layer becomes an addition, not a rebuild.
How McKenna Consultants Can Help
McKenna Consultants has spent over twenty-five years building software for UK and international organisations, and Microsoft document integration and Office Add-Ins are core competencies. As an Office add-in development consultancy in the UK, we have helped teams move off Exchange Web Services and, just as importantly, design the architecture that comes next.
If your EWS to Microsoft Graph migration is complete or nearly there, we can review your target architecture against the patterns above — identity and OBO flows, change-notification design, throttling resilience, the unified manifest, backend decoupling, and readiness for Copilot and agent extensibility. Whether you need an architecture review, hands-on development, or a roadmap that sequences these changes around your release plans, we can help you build an Outlook add-in that is sound for 2027 and beyond.
If you would like to discuss your Microsoft Graph Outlook add-in development, we would be glad to talk through your specific situation. Get in touch with the team to start the conversation.
