Office.Ews interface

Package:

outlook

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Provides methods to determine if Exchange Web Services (EWS) callback tokens are supported in an organization.

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important: Legacy Exchange Online user identity tokens and callback tokens are no longer supported and are turned off across all Microsoft 365 tenants. If an Outlook add-in requires delegated user access or user identity, we recommend using MSAL (Microsoft Authentication Library) and nested app authentication (NAA). Exchange user identity tokens are still supported for Exchange on-premises. For more information, see Nested app authentication FAQ.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/99-preview-apis/get-token-status.yaml

Office.context.mailbox.diagnostics.ews.getTokenStatusAsync({ isRest: false }, (result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.log(result.error.message);
    return;
  }
  const status = result.value;
  switch (status) {
    case Office.MailboxEnums.TokenStatus.Enabled:
      console.log("EWS callback tokens are enabled.");
      break;
    case Office.MailboxEnums.TokenStatus.Disabled:
      console.log("EWS callback tokens are disabled.");
      break;
    case Office.MailboxEnums.TokenStatus.Removed:
      console.log(
        "The organization has an Exchange Online environment. Legacy Exchange tokens are no longer supported.",
      );
      break;
  }
});

Methods

getTokenStatusAsync(options, callback)	Gets the status of EWS callback tokens in an organization.
getTokenStatusAsync(callback)	Gets the status of EWS callback tokens in an organization.

Method Details

getTokenStatusAsync(options, callback)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Gets the status of EWS callback tokens in an organization.

getTokenStatusAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<MailboxEnums.TokenStatus>) => void): void;

Parameters

options

Office.AsyncContextOptions & { isRest?: boolean }

An object literal that contains one or more of the following properties. asyncContext: Any data you want to access in the callback function. isRest: Identifies whether the token needed is for EWS or Outlook REST APIs. By default, the isRest property is set to false.

callback

(asyncResult: Office.AsyncResult<Office.MailboxEnums.TokenStatus>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The asyncResult.value property returns the token status, which can be Office.MailboxEnums.TokenStatus.Enabled, Office.MailboxEnums.TokenStatus.Disabled, or Office.MailboxEnums.TokenStatus.Removed. A Office.MailboxEnums.TokenStatus.Removed status indicates that the mailbox is hosted in an Exchange Online environment where legacy Exchange tokens are turned off and are no longer supported.

Returns

void

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

• The getTokenStatusAsync method is available for preview in Outlook on the web and on Windows (new and classic (Version 2510, Build 19328.20000 and later)).

• The getTokenStatusAsync method isn't supported if you load an add-in in an Outlook.com or Gmail mailbox.

• Calling the getTokenStatusAsync method in compose mode requires you to have saved the item. The saveAsync method requires a minimum permission level of read/write item.

getTokenStatusAsync(callback)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Gets the status of EWS callback tokens in an organization.

getTokenStatusAsync(callback: (asyncResult: Office.AsyncResult<MailboxEnums.TokenStatus>) => void): void;

Parameters

callback

(asyncResult: Office.AsyncResult<Office.MailboxEnums.TokenStatus>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The asyncResult.value property returns the token status, which can be Office.MailboxEnums.TokenStatus.Enabled, Office.MailboxEnums.TokenStatus.Disabled, or Office.MailboxEnums.TokenStatus.Removed. A Office.MailboxEnums.TokenStatus.Removed status indicates that the mailbox is hosted in an Exchange Online environment where legacy Exchange tokens are turned off and are no longer supported.

Returns

void

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

• The getTokenStatusAsync method is available for preview in Outlook on the web and on Windows (new and classic (Version 2510, Build 19328.20000 and later)).

• The getTokenStatusAsync method isn't supported if you load an add-in in an Outlook.com or Gmail mailbox.

• Calling the getTokenStatusAsync method in compose mode requires you to have saved the item. The saveAsync method requires a minimum permission level of read/write item.