From 597c2c3843651eb43c7d5b00993f7969e12129ff Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Fri, 7 Nov 2025 17:24:47 -0800 Subject: [PATCH 1/5] Add guidance about getTokenStatusAsync --- docs/outlook/web-services.md | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/docs/outlook/web-services.md b/docs/outlook/web-services.md index fc3ae009e..d49c6a541 100644 --- a/docs/outlook/web-services.md +++ b/docs/outlook/web-services.md @@ -1,7 +1,7 @@ --- title: Use Exchange Web Services (EWS) from an Outlook add-in in Exchange on-premises description: Provides an example that shows how an Outlook add-in in an Exchange on-premises environment can request information from Exchange Web Services. -ms.date: 11/06/2025 +ms.date: 11/11/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -16,16 +16,42 @@ The way you call a web service varies based on where the web service is located. |Web service location|Way to call the web service| |:-----|:-----| -|The Exchange server that hosts the client mailbox|Use the [mailbox.makeEwsRequestAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox#methods) method to call EWS operations that add-ins support. The Exchange server that hosts the mailbox also exposes EWS.| +|The Exchange server that hosts the client mailbox|Call the [Office.context.mailbox.makeEwsRequestAsync](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-makeewsrequestasync-member(1)) method to run EWS operations that add-ins support. The Exchange server that hosts the mailbox also exposes EWS.| |The web server that provides the source location for the add-in UI|Call the web service by using standard JavaScript techniques. The JavaScript code in the UI frame runs in the context of the web server that provides the UI. Therefore, it can call web services on that server without causing a cross-site scripting error.| |All other locations|Create a proxy for the web service on the web server that provides the source location for the UI. If you don't provide a proxy, cross-site scripting errors will prevent your add-in from running. One way to provide a proxy is by using JSON/P. For more information, see [Privacy and security for Office Add-ins](../concepts/privacy-and-security.md).| -## Using the makeEwsRequestAsync method to access EWS operations +## Determine if EWS tokens are enabled in an organization (preview) + +> [!NOTE] +> The `getTokenStatusAsync` method is currently in preview in Outlook on the web, on Windows (new and classic), and on Mac. Features in preview shouldn't be used in production add-ins as they may change based on feedback we receive. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the "Office Add-ins feedback" section at the end of this page). + +To determine if EWS tokens are enabled in an organization, call [Office.context.mailbox.diagnostics.ews.getTokenStatusAsync](/javascript/api/outlook/office.messagecompose?view=outlook-js-preview&preserve-view=true#outlook-office-ews-gettokenstatusasync-member(1)). The call returns one of the following token status values: +- **Enabled**: EWS tokens are allowed in the organization. +- **Disabled**: EWS tokens are turned off in the organization. +- **Removed**: The organization is using Exchange Online. Legacy Exchange tokens are no longer supported and are turned off. + +The following example shows how to call `getTokenStatusAsync` in your add-in code. + +```javascript +Office.context.mailbox.diagnostics.ews.getTokenStatusAsync((asyncResult) => { + if (asyncResult.status === Office.AsyncResultStatus.Failed) { + console.log(asyncResult.error.message); + return; + } + + const tokenStatus = asyncResult.value; + if (tokenStatus === "Enabled") { + // Add your EWS requests here. + } +}); +``` + +## Call the makeEwsRequestAsync method to access EWS operations > [!IMPORTANT] > EWS calls and operations aren't supported in add-ins running in Outlook on Android and on iOS. -You can use the [mailbox.makeEwsRequestAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox#methods) method to make an EWS request to the on-premises Exchange server that hosts the user's mailbox. +To make an EWS request to the on-premises Exchange server that hosts the user's mailbox, call [Office.context.mailbox.makeEwsRequestAsync](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-makeewsrequestasync-member(1)). EWS supports different operations on an Exchange server; for example, item-level operations to copy, find, update, or send an item, and folder-level operations to create, get, or update a folder. To perform an EWS operation, create an XML SOAP request for that operation. When the operation finishes, you get an XML SOAP response that contains data that's relevant to the operation. EWS SOAP requests and responses follow the schema defined in the **Messages.xsd** file. Like other EWS schema files, the **Message.xsd** file is located in the IIS virtual directory that hosts EWS. From a39d5493d7421df7b5a3e2f555b152b3af1f97a5 Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Wed, 12 Nov 2025 17:38:16 -0800 Subject: [PATCH 2/5] Update supported platforms --- docs/outlook/outlook-mobile-apis.md | 3 ++- docs/outlook/web-services.md | 8 ++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/outlook/outlook-mobile-apis.md b/docs/outlook/outlook-mobile-apis.md index 8922a26ca..11d712bcc 100644 --- a/docs/outlook/outlook-mobile-apis.md +++ b/docs/outlook/outlook-mobile-apis.md @@ -1,7 +1,7 @@ --- title: Outlook JavaScript APIs supported in Outlook on mobile devices description: Learn which Outlook JavaScript APIs are supported in Outlook on mobile devices. -ms.date: 08/06/2025 +ms.date: 11/13/2025 ms.localizationpriority: medium --- @@ -15,6 +15,7 @@ The following table lists a subset of APIs from requirement sets beyond 1.5 that |API|Minimum requirement set|Supported Outlook modes|Supported Outlook on mobile clients| |---|---|---|---| +|[Office.context.mailbox.diagnostics.ews.getTokenStatusAsync](/javascript/api/outlook/office.ews?view=outlook-js-preview&preserve-view=true#outlook-office-ews-gettokenstatusasync-member(1)) (preview)|Mailbox preview||| |[Office.context.mailbox.getIsIdentityManaged](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-getisidentitymanaged-member(1))|Not applicable||| |[Office.context.mailbox.getIsOpenFromLocationAllowed](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-getisopenfromlocationallowed-member(1))|Not applicable||| |[Office.context.mailbox.getIsSaveToLocationAllowed](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-getissavetolocationallowed-member(1))|Not applicable||| diff --git a/docs/outlook/web-services.md b/docs/outlook/web-services.md index d49c6a541..06b28e5e2 100644 --- a/docs/outlook/web-services.md +++ b/docs/outlook/web-services.md @@ -1,7 +1,7 @@ --- title: Use Exchange Web Services (EWS) from an Outlook add-in in Exchange on-premises description: Provides an example that shows how an Outlook add-in in an Exchange on-premises environment can request information from Exchange Web Services. -ms.date: 11/11/2025 +ms.date: 11/13/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -23,10 +23,10 @@ The way you call a web service varies based on where the web service is located. ## Determine if EWS tokens are enabled in an organization (preview) > [!NOTE] -> The `getTokenStatusAsync` method is currently in preview in Outlook on the web, on Windows (new and classic), and on Mac. Features in preview shouldn't be used in production add-ins as they may change based on feedback we receive. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the "Office Add-ins feedback" section at the end of this page). +> The `getTokenStatusAsync` method is currently in preview in Outlook on the web, on Windows (new and classic), and on mobile devices. Features in preview shouldn't be used in production add-ins as they may change based on feedback we receive. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the "Office Add-ins feedback" section at the end of this page). -To determine if EWS tokens are enabled in an organization, call [Office.context.mailbox.diagnostics.ews.getTokenStatusAsync](/javascript/api/outlook/office.messagecompose?view=outlook-js-preview&preserve-view=true#outlook-office-ews-gettokenstatusasync-member(1)). The call returns one of the following token status values: -- **Enabled**: EWS tokens are allowed in the organization. +To determine if EWS tokens are enabled in an organization, call [Office.context.mailbox.diagnostics.ews.getTokenStatusAsync](/javascript/api/outlook/office.messagecompose?view=outlook-js-preview&preserve-view=true#outlook-office-ews-gettokenstatusasync-member(1)). The call returns one of the following [token status values](/javascript/api/outlook/office.mailboxenums.tokenstatus?view=outlook-js-preview&preserve-view=true): +- **Enabled**: EWS tokens are supported in the organization. - **Disabled**: EWS tokens are turned off in the organization. - **Removed**: The organization is using Exchange Online. Legacy Exchange tokens are no longer supported and are turned off. From 59893ada4f7a2a0792d8abeaa936cf5f3a338a4e Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Thu, 13 Nov 2025 13:35:58 -0800 Subject: [PATCH 3/5] Remove mobile platform and update code snippet --- docs/outlook/outlook-mobile-apis.md | 3 +-- docs/outlook/web-services.md | 10 +++++----- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/outlook/outlook-mobile-apis.md b/docs/outlook/outlook-mobile-apis.md index 11d712bcc..8922a26ca 100644 --- a/docs/outlook/outlook-mobile-apis.md +++ b/docs/outlook/outlook-mobile-apis.md @@ -1,7 +1,7 @@ --- title: Outlook JavaScript APIs supported in Outlook on mobile devices description: Learn which Outlook JavaScript APIs are supported in Outlook on mobile devices. -ms.date: 11/13/2025 +ms.date: 08/06/2025 ms.localizationpriority: medium --- @@ -15,7 +15,6 @@ The following table lists a subset of APIs from requirement sets beyond 1.5 that |API|Minimum requirement set|Supported Outlook modes|Supported Outlook on mobile clients| |---|---|---|---| -|[Office.context.mailbox.diagnostics.ews.getTokenStatusAsync](/javascript/api/outlook/office.ews?view=outlook-js-preview&preserve-view=true#outlook-office-ews-gettokenstatusasync-member(1)) (preview)|Mailbox preview||| |[Office.context.mailbox.getIsIdentityManaged](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-getisidentitymanaged-member(1))|Not applicable||| |[Office.context.mailbox.getIsOpenFromLocationAllowed](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-getisopenfromlocationallowed-member(1))|Not applicable||| |[Office.context.mailbox.getIsSaveToLocationAllowed](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-getissavetolocationallowed-member(1))|Not applicable||| diff --git a/docs/outlook/web-services.md b/docs/outlook/web-services.md index 06b28e5e2..d9cfedfec 100644 --- a/docs/outlook/web-services.md +++ b/docs/outlook/web-services.md @@ -23,12 +23,12 @@ The way you call a web service varies based on where the web service is located. ## Determine if EWS tokens are enabled in an organization (preview) > [!NOTE] -> The `getTokenStatusAsync` method is currently in preview in Outlook on the web, on Windows (new and classic), and on mobile devices. Features in preview shouldn't be used in production add-ins as they may change based on feedback we receive. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the "Office Add-ins feedback" section at the end of this page). +> The `getTokenStatusAsync` method is currently in preview in Outlook on the web and on Windows (new and classic (Version 2510, Build 19328.20000)). Features in preview shouldn't be used in production add-ins as they may change based on feedback we receive. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the "Office Add-ins feedback" section at the end of this page). To determine if EWS tokens are enabled in an organization, call [Office.context.mailbox.diagnostics.ews.getTokenStatusAsync](/javascript/api/outlook/office.messagecompose?view=outlook-js-preview&preserve-view=true#outlook-office-ews-gettokenstatusasync-member(1)). The call returns one of the following [token status values](/javascript/api/outlook/office.mailboxenums.tokenstatus?view=outlook-js-preview&preserve-view=true): -- **Enabled**: EWS tokens are supported in the organization. -- **Disabled**: EWS tokens are turned off in the organization. -- **Removed**: The organization is using Exchange Online. Legacy Exchange tokens are no longer supported and are turned off. +- `Office.MailboxEnums.TokenStatus.Enabled`: EWS tokens are supported in the organization. +- `Office.MailboxEnums.TokenStatus.Disabled`: EWS tokens are turned off in the organization. +- `Office.MailboxEnums.TokenStatus.Removed`: The organization is using Exchange Online. Legacy Exchange tokens are no longer supported and are turned off. The following example shows how to call `getTokenStatusAsync` in your add-in code. @@ -40,7 +40,7 @@ Office.context.mailbox.diagnostics.ews.getTokenStatusAsync((asyncResult) => { } const tokenStatus = asyncResult.value; - if (tokenStatus === "Enabled") { + if (tokenStatus === Office.MailboxEnums.TokenStatus.Enabled) { // Add your EWS requests here. } }); From c688476bab822f7bcfce1127f3d0dd78a8ce541b Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Thu, 13 Nov 2025 13:37:30 -0800 Subject: [PATCH 4/5] Update ms.date --- docs/outlook/web-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/outlook/web-services.md b/docs/outlook/web-services.md index d9cfedfec..f821d7b2c 100644 --- a/docs/outlook/web-services.md +++ b/docs/outlook/web-services.md @@ -1,7 +1,7 @@ --- title: Use Exchange Web Services (EWS) from an Outlook add-in in Exchange on-premises description: Provides an example that shows how an Outlook add-in in an Exchange on-premises environment can request information from Exchange Web Services. -ms.date: 11/13/2025 +ms.date: 11/14/2025 ms.topic: how-to ms.localizationpriority: medium --- From e0f90b5fda924d0a88ae50dc867b85e4979f382d Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Thu, 13 Nov 2025 14:30:08 -0800 Subject: [PATCH 5/5] Clarify supported versions --- docs/outlook/web-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/outlook/web-services.md b/docs/outlook/web-services.md index f821d7b2c..073a2f68a 100644 --- a/docs/outlook/web-services.md +++ b/docs/outlook/web-services.md @@ -23,7 +23,7 @@ The way you call a web service varies based on where the web service is located. ## Determine if EWS tokens are enabled in an organization (preview) > [!NOTE] -> The `getTokenStatusAsync` method is currently in preview in Outlook on the web and on Windows (new and classic (Version 2510, Build 19328.20000)). Features in preview shouldn't be used in production add-ins as they may change based on feedback we receive. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the "Office Add-ins feedback" section at the end of this page). +> The `getTokenStatusAsync` method is currently in preview in Outlook on the web and on Windows (new and classic (Version 2510, Build 19328.20000 and later)). Features in preview shouldn't be used in production add-ins as they may change based on feedback we receive. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the "Office Add-ins feedback" section at the end of this page). To determine if EWS tokens are enabled in an organization, call [Office.context.mailbox.diagnostics.ews.getTokenStatusAsync](/javascript/api/outlook/office.messagecompose?view=outlook-js-preview&preserve-view=true#outlook-office-ews-gettokenstatusasync-member(1)). The call returns one of the following [token status values](/javascript/api/outlook/office.mailboxenums.tokenstatus?view=outlook-js-preview&preserve-view=true): - `Office.MailboxEnums.TokenStatus.Enabled`: EWS tokens are supported in the organization.