Upcoming API Deprecations in Exchange Web Services for Exchange Online
Published Oct 05 2021 10:05 AM 130K Views

Update 1/20/2022: We have edited this post for clarity based on customer feedback.

Over the last few years, we have invested heavily in Microsoft Graph to enable developers to access the rich data available in Microsoft 365. Microsoft Graph, along with OAuth 2.0, provides increased security and seamless integration with other Microsoft cloud services.

In August 2018, we announced that we were no longer going to actively invest in Exchange Web Services (EWS) APIs for Exchange Online. We also gave a strong recommendation to start migrating to Microsoft Graph for Exchange Online data access.

Today we are announcing the deprecation of the 25 least used APIs of EWS for Exchange Online (as determined by the call volume into the service). We are deprecating these APIs to begin the process of reducing the surface area of the EWS protocol for maintenance and security purposes. Support for these APIs will no longer exist after March 31, 2022.

The list of deprecated APIs is at the end of this post. We will introduce sunset headers in the response for these APIs that are marked for deprecation.

We have already sent Message Center posts to tenants using these low volume, and now deprecated APIs. If you did not already receive a Message Center post, you will not be impacted by this change.

Over time, we will identify additional APIs for deprecation when and where we see adequate parity with Microsoft Graph APIs. We are also working hard on addressing feature gaps and building parity between EWS and Microsoft Graph APIs. We strongly urge our ecosystem partners accessing Exchange Online data to migrate to Microsoft Graph APIs.

We previously announced that we planned to prevent registration of new apps in Azure with EWS permissions, but based on your feedback we have decided to postpone this plan for the time being.

EWS is a legacy API surface that has served us well, but no longer meets the security and manageability needs of modern app development. We strongly urge our ecosystem partners accessing Exchange Online data to migrate to Microsoft Graph APIs.

APIs scheduled for deprecation:

The_Exchange_Team_0-1633453136023.png

The Exchange Team and Microsoft Graph Team

78 Comments
Steel Contributor

Way to go! Are there any plans to provide insights if these particular API:s are in use in our tenant(s) so we know if we will be affected of these depreciations?

Copper Contributor

Hello, the main issue we face today is that graph API does not cover all methods covered by EWS. It will be easier to move to graph API if we did not miss some of it. We are now in a situation where we need to do heavy developments using Graph API and EWS. knowing that we will need to do some more developments when those missing features will be covered by graph API. Hope we can use Graph API fully soon. thanks

Steel Contributor

@Renaud_B If you could add what particular methods are missing, I think that would help. Not only Microsoft but also us who talk to customers and vendors so we are aware what is missing and not. Since there is actually no "User Voice" anymore and this Tech Community is one place where Microsoft wants us to provide feedback.

Iron Contributor

I agree with Jonas, Microsoft needs to provide reporting so that we can easily identify the apps that are utilising the impacted EWS APIs (and EWS more generally). I don’t think we can rely on the Azure AD Sign-In logs as they only allow you to filter on Client App, which for EWS is only listed for Basic Authentication connections.

 

Also how do these changes impact the Outlook for Windows and Outlook for Mac clients, since it’s my understanding that both clients still utilise EWS to connect to Exchange Online for some functionality (especially Outlook for Mac - current version, not the new UI version which uses Microsoft Sync Technology).

Brass Contributor

What does that mean, "Today, we are announcing that we are going to remove the ability to create new EWS apps starting September 30, 2022."?

You mean you can't create Azure AD apps anymore with EWS permissions? You're kidding, right?

Brass Contributor

Completely agree wit @Jonas Back and @stukey 

 

Microsoft needs to provide reporting so that we can easily identify the apps that are utilizing the impacted EWS APIs (and EWS more generally). I don’t think we can rely on the Azure AD Sign-In logs as they only allow you to filter on Client App, which for EWS is only listed for Basic Authentication connections.

Brass Contributor

This is a major announcement and has the potential to impact every Microsoft customer from the point onward where no new EWS App Registrations are possible.

 

Right now, the Exchange Web Services API is the only way to get full-fidelity (preserving all properties) email information into and out of Office 365 (see MS-OXWSBTRF). Without this capability, 3rd Party applications addressing backup, eDiscovery, and migration (including Tenant-to-Tenant) will simply not be possible anymore! Also, even if the Graph API is extended to support the missing methods, will MSFT switch to the same "paid" model to use the Graph API as with Teams?  

 

Imagine the implications of an acquisition or divestiture scenario, where one needs to consolidate tenants and/or on- or offboard legacy data. Cost and Time implications might get enormous, and a lot of restructuring projects will never reach an ROI if suddenly the project costs and timelines multiply.

Copper Contributor

I think it would be good for Microsoft to provide some more clarification on the following statement "Today, we are announcing that we are going to remove the ability to create new EWS apps starting September 30, 2022.". Does it mean we can no longer add the "EWS.AccessAsUser.All" permission to new Azure Active Directory apps? If so, does it apply to both UI and API operations? How does Microsoft propose developers deal with needing to support both Exchange Online and Exchange On-premises ?

Copper Contributor

For those looking for a text-based list of these APIs:

 

CopyFolder
CreateUMPrompt
DeleteBookingService
DeleteBookingStaff
DeleteUMPrompts
FindAvailableMeetingTimes
FindMessageTrackingReport
GetDiscoverySearchConfiguration
GetPeopleInsights
GetUMCallDataRecords
GetUMCallSummary
GetUMPin
GetUMPromptNames
NewBookingMailbox
PerformReminderAction
PlayOnPhone
RemoveDelegate
RemoveImGroup
ResetUMMailbox
SetBookingCalendarPublishing
SetUserPhoto
StartXrmSession
UpdateBookingCustomer
UpdateDelegate
UpgradeDistributionGroup

Steel Contributor

@The_Exchange_Team Care to comment on the request for providing more insights in which APIs used by what? Or do we have to guess? :smiling_face_with_smiling_eyes:

Microsoft

@stukey ,  @Tom_R_ , @Jonas Back  - We will send Message Center posts to impacted tenants with a list of applications using any of these 25 EWS APIs mentioned in the blog post. As for the question on Outlook usage – currently we have announced only a small subset of EWS APIs for upcoming deprecation, not EWS all up. Outlook very much still uses EWS, but none of the APIs included in this announcement. Outlook (win and mac) moving off EWS is beyond the scope of this announcement.

 

@MichelZCF , @WGroenestein - As mentioned in the blog, creation of new apps using EWS is planned to be blocked from September 30th, 2022. So, yes, new Azure AD apps can’t be created using EWS permission scopes. Existing apps using EWS apps permissions will however continue to function beyond this date & not be impacted. This is only relevant for Exchange Online.

Apps running on Exchange On-Prem won’t be affected by any of this announcement and will not need to change. New solutions should actively look into on-boarding to Microsoft Graph directly for Exchange Online.

Copper Contributor

From my Point of View the impact of this is huge. In my little world almost every 3rd Party ExO solution I can think of uses these EWS permissions. 

When it comes to the EWS API itself (which will still be there but you cant register the app) and the ability to just replace it with graph API is just not true. 

We believed in graphAPI as a replacement for EWS in 2018 and ended up with a lot of issues which - to my knowledge  - are still not sorted. EWS is complete. graphAPI is not when it comes to a full featured Exchange API.

So, when you depend on streaming subscriptions and full featured object handling (create, update, delete notes, contacts, appointments, stickynotes and folders, etc) 

you end up with a mixture of graphAPI and Outlook REST API and still miss features.   This can all be true because of my limited knowledge, so if anyone at MS is reading this: 

a real migration guide which EWS feature can be (fully)  replaced with which graphAPI feature and how to do it with samples and stuff would be incredibly great.

Also a clear statement what’s just not available atm. Or take the easy way and just drop the idea of deprecating the EWS APP registration.

Copper Contributor

I am very techno-ignorant; I have a solo counseling practice and I just want my MS365 Business to function. I have had trouble linking the correct email account with the Zoom Add-In for Outlook. Randomly, emails do not go out to attendees. I just want to focus on my clients...Please Get All This Launched and FIXED so ALL your consumers can access and use All the features for which we are paying. 

Copper Contributor

@Abheek_Das, thank you for providing extra info

Steel Contributor

So just to confirm again as @WGroenestein asked earlier (and I do see it was responded to), after the stated date, no new apps will be able to be granted the EWS.AccessAsUser.All API permission?  Seeing as that permission is so universal and we're only talking about a small portion of API's being deprecated, this particular step seems like going too far, and in parallel, barely calling attention to this.

 

When I'm using EWS Managed API, I'm doing all kinds to basic EWS stuff that isn't part of any one of those API's.  Like Folder.FindItems, or ExchangeService.FindItems, or Folder.Emtpy, etc.  I don't even know what sub-API these fall into.  My understanding was the the API in this case is Exchange Web Services, though I realize EWS (the web service) has the SOAP/XML interface that is the main function (as opposed to the 'managed API').

 

I just don't get why you're selling this as though you're deprecating a few of the EWS API's, but then you're taking away any net new ability to setup new apps to use the non-deprecated API's.  Seems less than open book and more like trying to pull something off without getting called out before it happens.

Brass Contributor

Super. I only use Set-UserPhoto via Powershell 40 times a day via a profile photo update process. :( 

Copper Contributor

As a small business customer, we chose Exchange Online to meet our mail client needs rather than using on-prem Exchange.     Our entire business depends and runs on e-mail.  I would hope that Microsoft would evaluate these changes and publish information as to exactly how this is going to affect our mail clients. Minor changes have had drastic impacts on our mail clients in the past.  In many cases, the small business customer is only using the mail and we would not know how might impact our mails system, without paying our IT contractors overtime to figure it out.  Please provide documentation that is customer-centered and please do not make any changes that prevent our clients from connecting to Exchange and performing the expected tasks (Using Mail, Calendar, Contacts, Shared Folders, Delegation, etc.)

Copper Contributor

We are officially requesting the ability to check tenants for all calls that include EWS and Microsoft Graph, than you 

@TammyK5 - Zoom own that add-in, I think you need to talk to them about it. 

@Gregor_Stefka We're working hard trying to get parity in Graph, so you can use just Graph - and we're discussing how to publish a comparison chart/doc on EWS vs Graph to help you and others see how one relates to the other. 

@SPQR1981 Reporting on API usage is something we are working on too. 

@Jeremy Bradshaw (and others) - correct, these are two separate, but related things. 25 APIs are being completely deprecated. Additionally, we're going to end the ability to create new apps that use EWS permissions. Apps registered before that cut-off, or that use any of many other APIs EWS has, are not currently affected. EWS is not the future, so creating net new apps on it, is just creating work down the road for the developer. We know it's as long road to get these apps to Graph, but it has to start somewhere. 

@Nick_765 Unless you write your own code, or use some third-party apps that integrate into Exchange Online, chances are this has no impact on you. If you are using Exchange for email and calendar, and are using Outlook, you don't need to worry about the content of this post. 

Brass Contributor

@Greg Taylor - EXCHANGE 

It‘s not about net new apps, we have a mature app that our customers want to use. They need their own app regs to be able to use it.

Copper Contributor

@Greg Taylor - EXCHANGE we use the Graph API Ecosystem to integrate our software's scheduling module with published calendars created for our customers. I am almost certain that we are strictly using Graph API but would like to verify it. Thanks. 

Brass Contributor

@The_Exchange_Team Set-UserPhoto was a one line command that simplified the overly complex photo sync process. I've spent hours trying to get the GraphAPI to work for this in Powershell and keep getting 401 errors. [30,1: Invoke-RestMethod] The remote server returned an error: (401) Unauthorized.

 

What permissions are needed for the App Registration and the Powershell connection scope? 

 

Connect-MgGraph -Scopes "User.ReadWrite.All"

$AzAppSecret = '###########################'
$AzAppId = '###########################'
$AzTenantId = '#######################'

# Request token
$tokenRequestBody = @{

Grant_Type = "client_credentials"
Scope = "https://graph.microsoft.com/.default"
Client_Id = $AzAppID
Client_Secret = $AzAppSecret
}

$tokenRequestUri = [String]::Format('https://login.microsoftonline.com/{0}/oauth2/v2.0/token', $AzTenantId)
$tokenResponse = Invoke-RestMethod -Uri $tokenRequestUri -Method 'POST' -Body $tokenRequestBody -ErrorAction Stop
$accessToken = $tokenResponse.access_token
$AzUserUPN = 'username@example.com'
$AzUserImage = 'S:\samplepic.jpg'

$uri = [String]::Format('https://graph.microsoft.com/v1.0/users/{0}/photo/$value', $AzUserUPN)
$Headers = @{
'Authorization' = [String]::Format('Bearer {0}', $accessToken)
'Content-Type' = 'image/jpeg'
}

Invoke-RestMethod -Method Put -Uri $uri -InFile $AzUserImage -Headers $Headers

Steel Contributor

Hi @MGSpaceCaptain , in your code, I don't see what 'Connect-MSGraph -Scopes "User.ReadWrite.All"' is doing, it's just there at the start, but then everything else is an app getting it's own confidential client access token using a client secret.

 

From here Update profilephoto - Microsoft Graph v1.0 | Microsoft Docs - it says that if an app will need to update any user's photo, it needs to have "User.ReadWrite.All" application permission.  So, I think that's where you're getting the idea to do the Connect-MSGraph step.  Instead, go to your app registration in the Azure AD portal and grant it the User.ReadWrite.All application permission and grant it the consent there too.  Then just omit the Connect-MSGraph step from your code, as the scope will already be automatically granted (via the granted/consented API application permission).

 

Edit: PS.  You could give MSGraphPSEssentials a try for your task at hand.  It would be an easy way for you to switch from client secret to certificates, while also making it easy to get your app's access token and then submit your request(s) to update the photo(s).  If you have trouble, I can help through a GitHub discussion (at no guaranteed pace of course).

Copper Contributor

Is there any roadmap for Graph API to gain feature parity with EWS? Or will this be another "too bad" situation like back in the day when the great ExMerge tool was replaced with less functional alternatives?

 

For one, Graph doesn't have a method to copy/move content from one mailbox to a different mailbox (can only copy/move between folders in the same mailbox). Also can't even access an Exchange Online Archive mailbox via Graph.

 

I work for a large company (~50,000), and my Messaging Operations team still has to use the EWS script I wrote many years ago to automate mailbox-to-mailbox and mailbox-to-archive data migrations. I'd gladly rewrite it against Graph, but can't because Graph can't do the job. Using Outlook to do it manually is an unacceptable alternative.

Copper Contributor

We use EWS in a daemon to sync all our user’s appointments and tasks to exchange.  Using EWS this works easily using impersonation.  

 

Graph only allows delegated authorization to access/modify tasks. At several government clients we are not allowed to store user credentials or request permission from users. Graph docs say the only way to possibly do this is to use ROCP auth. Then it says “don’t use ROCP auth.”  Unless access to tasks is allowed on application authorization we can not properly synchronize tasks. 

There are other similar areas.  Until Graph has true parity in these areas it seems wrong to prevent new app registrations.  

Copper Contributor

1. Is there any roadmap for Graph API to gain feature parity with EWS?
2. From the statement:

Today, we are announcing that we are going to remove the ability to create new EWS apps starting September 30, 2022.

Does it mean we can no longer add "full_access_as_app" permission to new AD apps through the following API ?

POST /servicePrincipals/{id}/appRoleAssignedTo

 

Copper Contributor

We are working on EWS > Graph roadmap/comparisons, all of that. We'll have more on that in the future. We're also working on answering the more specific questions asked above, so look out for those soon. 

Copper Contributor

Hi,

I have a particular question rather clarification as our code heavily relies on the EWS Managed API still. The following will greatly help us in our impact analysis, appreciate your patience:

 

1. Do these 25 method calls also affect the EWS Managed API?

2. Some of the API calls will be deprecated on 3/31. Any idea on if that deprecation is merely “no longer supported” or “the API calls will fail”? "We will introduce sunset headers in the response for these APIs that are marked for deprecation."

 

To paraphrase the above:

Meaning to say that after 3/31, calls to the listed methods in the EWS API will not fail, but return a response with the additional "deprecated" header. If we are using the EWS managed API, this will work with the old object model and the introduction of the header will not alter the old object model of the EWS Managed API.

 

2. The least used 25 EWS Api methods are being deprecated

So, to paraphrase:

No other EWS Api / EWS Managed Api method calls apart from the 25 listed above will fail or behave differently. All other EWS Api / EWS Managed Api methods do not internally call the above 25 methods.

 

Many Thanks in advance!!

Regards,

Probir

 

Copper Contributor

Hi,

I have one more follow up question - Is there a way to test that we are ready for this change?

Regards,

Probir

Copper Contributor

Hi @Greg Taylor - EXCHANGE, I am trying to get my head straight regarding the timing of the "deprecation of the 25 least used APIs of EWS for Exchange Online...by March 31, 2022" and the removal of "the ability to register new apps in Azure with EWS permissions starting September 30, 2022. Apps registered before this date, any API not mentioned in this, or subsequent announcements, will not be impacted."

 

My interpretation of the 2 different statements above is that the 25 APIs will no longer be usable after 31st March but it will be possible to register new AAD apps using those APIs up until 30th September.  I feel like I am mis-understanding something here because what is the point of being able to register a new AAD app that uses one of the 25 listed APIs, let's say on 1st April, when the EWS APIs were no longer usable from 31st March?

 

Are you able to clarify the relationship between the 2 different events and the timing of those 2 events please?

 

Thanks in advance, Ian.

Brass Contributor

@Ian_M10 

 

March 31: You can't use those 25 API's, but still every other EWS API (there are lots more)

Sept 30: You can use all EWS API's except the 25 for Apps that have been registered before this date.  If you don't have an app registered by then - you will not be able to use EWS at all.

 

That's my current understanding

@MichelZCF 's understanding is correct. Thanks for posting that. 

 

Just an update, we're working on per-tenant MC posts, indicating usage of the 25 APIs as well. It'll take a bit of time to do, but we're on it. 

Copper Contributor

@Greg Taylor - EXCHANGE 

We are struggling with the conversion from Set-UserPhoto to the Graph equivalent.  Our agency currently employs a PowerShell script to upload new employee photos.  The photos are generated in our security badge system and exported to be used in Microsoft 365.  Switching to a Graph version of the process necessitates the creation of an app, writing additional code and [possibly] editing the photos to fit one of the 9 designated sizes.  There a concern that this will cause a significant increase in administration of what was originally a simple process.

 

In identifying which APIs to 'retire', it seems Microsoft used a metric that is not reflective of the viability of the API.  It is fairly obvious that the Set-UserPhoto API would not be used very frequently but that negates the utility of the command.  I feel it would be prudent to not deprecate the Set-UserPhoto cmdlet until an alternative procedure could be provided.

 

T

 

@Terrell Gilliland - thanks for explaining that. I'll circle back with the team and provide that feedback. 

@Ian_M10 and @MichelZCF  and others. We've updated the plan - We will not block these APIs when we get to March 31, 2022. They can still be used, but are deprecated/not supported, for the time being. 

 

Today we are announcing the deprecation of the 25 least used APIs of EWS for Exchange Online (as determined by the call volume into the service). We are deprecating these APIs to begin the process of reducing the surface area of the EWS protocol for maintenance and security purposes. Support for these APIs will no longer exist after March 31, 2022.

The list of deprecated APIs is at the end of this post. We will introduce sunset headers in the response for these APIs that are marked for deprecation.

Copper Contributor

As a partner writing tools for FreeBusy lookup in Teams, we too are surprised at the speed in which the ability to register an Modern App using EWS calls will be removed. Can we petition that it should not be removed until Graph API calls match the current feature set in EWS?

Thanks,

 

Mark Calleran, BCC (@bcchub.com)

Steel Contributor

Yup, what @mcalleran said.  Not only does A) Graph have to be updated (not even Beta Graph is updated yet), people then have to B) update their skills then C) update their stuff (programs, scripts, products, etc.).   That's a lot to happen in 1 year, 2 months, ~7 days (from right now, where step A isn't even ready).

 

I was holding off on piping up again, but had the clarity to point it out this way, so went with it.  Petition though, pretty well impossible with User Voice gone.  I think this thread is currently the best place to voice the concern.

Thanks for the feedback @mcalleran and @Jeremy Bradshaw - we do hear you I can assure you. 

Copper Contributor

@Greg Taylor - EXCHANGE I have a question. We have our custom application layer that communicates with the EWS using SOAP protocol. I inspected all the traffic going between the endpoints and do not see that any of the deprecated APIs mentioned above appears in the the XML bodies of the requests. Is this enough to make sure we are not affected by the change? If not, what is the proper way to investigate this? In other words how do we know that we are not using deprecated API commands?  

 

Copper Contributor

Hi,

1. What if we already have a multi-tenant app already registered with EWS permissions under the app registration in our tenant.
2. But then we need our clients (other azure-ad tenants) to add the app under the enterprise applications and provide admin consent for EWS related scopes.

The changes on September 30st affect 1 but not 2. Meaning as long as we have our application registered by then (and it's a multi-tenant app), other azure-ad tenants will be able to create a service principal under enterprise app and grant admin consent for the EWS scopes - even after September 30th

Is my understanding correct?

Brass Contributor

@Probir_Chatterjee : I doubt that any larger customer would accept a multi-tenant ews app with full impersonation access to all their mailboxes...

I work mostly with larger customers and enterprises and the app registration for EWS is usually done in the tenant of the client. 

Copper Contributor

Hi Peter / All,

 

Many Thanks for that perspective, seems to be quite true! So, if we currently provide SaaS by means of EWS app registered in client-tenant, we will just have to use basic auth directly on EWS then? No more modern auth via Azure-Ad?

 

Regards,

Probir

Brass Contributor

@Probir_Chatterjee 

You can't and shouldn't use Basic Auth anymore (https://techcommunity.microsoft.com/t5/exchange-team-blog/basic-authentication-and-exchange-online-f...) as its unsecure and depreciated. 

 

We are in the same situation as you trying to find a suitable solution that our customers would accept. Until we have the full functionality in the GRAPH API there's not much we can do except encourage our customers to provide "feedback" to MSFT and hope that the September 2022 date is postponed if enough customers and partners act.  In our case we do a lot of very large volume email migrations (sometimes PB's of email data) either from onprem to O365 or from one O365 tenant to another. EWS gives us everything we need, to be able to push up to 35 TB per day into Exchange Online. 

37TB.png

 

Let's hope once the complete set of functionalities is ported to graph that we will be able to do the same or more :)  

 

 

Copper Contributor

I can't for the life of me find any documentation on this endpoint: FindAvailableMeetingTimes. We have a multi-tenant app with some EWS interaction that was build (by somebody else) quite a while ago. We do use the GetUserAvailability, but I can't find out those are related. But I can't find this 'FindAvailableMeetingTimes' endpoint anywhere, so I have no clue what this refers to.

Copper Contributor

We are producing an Outlook Addin that is supposed to run with Office365 and with on prem Exchange.

We are using Outlook REST API for some stuff office.js doesn't offer (getting the MIME content of a message).

With the deprecation of Outlook REST API in Office365 we would need to switch to Graph. But this isn't possible for on prem Exchange.

 

What is the recommended approach?

Do we really need to support both API's and switch depending on the kind of server?

 

Copper Contributor

We are working on EWS > Graph roadmap for our product which integrates with Online Exchange.
Currently, it uses EWS Aggregate Streaming Subscriptions / Notification Mechanism for syncing the updates/changes from Online Exchange.
Is there anything similar in Graph ?

 

What is the recommended Notification Mechanism with Graph ? 

@DivyaSharma - I checked with someone who provided this;

 

For syncing updates in mailbox we have 2 alternatives in Graph –

  1. Pull Model – Delta Sync capability: Use delta query to track changes in Microsoft Graph data - Microsoft Graph | Microsoft Docs
  2. Push Model – Change notifications via webhooks: Set up notifications for changes in user data - Microsoft Graph | Microsoft Docs . We are trying to get a dedicated page set for EXO Change Notification in our public docs
Copper Contributor

Please note Microsoft's very sensible and pragmatic change of approach. The existing schedule for March remains the same, but further changes will only happen when Graph API functionality has parity or improvement over the EWS equivalent. Great to see Microsoft listening to our feedback and that of other EWS users.

 

https://techcommunity.microsoft.com/t5/exchange-team-blog/upcoming-api-deprecations-in-exchange-web-...

 

Brass Contributor

I see a bunch of references to "Today, we are announcing that we are going to remove the ability to create new EWS apps starting September 30, 2022." in the comments of this post, but nowhere is this reflected in the original post. I do see it has been edited, so does this mean MSFT has pulled back on removing the ability to create new EWS apps?

 

AFAIK there is no Graph API for public folder access, something that we can access via EWS API so the functionality parity is missing...

Co-Authors
Version history
Last update:
‎Jan 20 2022 01:28 PM
Updated by: