@types/office-js-preview 1.0.521 → 1.0.522

office-js-preview/README.md

@@ -8,7 +8,7 @@ This package contains type definitions for office-js-preview (https://github.com
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/office-js-preview.
 
 ### Additional Details
- * Last updated: Tue, 15 Oct 2024 17:07:26 GMT
+ * Last updated: Thu, 17 Oct 2024 17:36:59 GMT
  * Dependencies: none
 
 # Credits

office-js-preview/index.d.ts

@@ -10090,6 +10090,12 @@ declare namespace Office {
          * [Api set: Mailbox 1.3]
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
+         *
+         * **Important**: The Outlook REST v2.0 and beta endpoints are now deprecated. However, privately released and AppSource-hosted add-ins are able to use the REST service
+         * until extended support ends for Outlook 2019 on October 14, 2025. Traffic from these add-ins is automatically identified for exemption. This exemption also
+         * applies to new add-ins developed after March 31, 2024. Although add-ins are able to use the REST service until 2025, we highly encourage you to migrate your
+         * add-ins to use {@link https://learn.microsoft.com/outlook/rest#outlook-rest-api-via-microsoft-graph | Microsoft Graph}. For guidance, see
+         * {@link https://learn.microsoft.com/outlook/rest/compare-graph | Compare Microsoft Graph and Outlook REST API endpoints}.
          */
         enum RestVersion {
             /**
@@ -10938,14 +10944,11 @@ declare namespace Office {
          */
         getInitializationContextAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
-         * Asynchronously gets the ID of a saved item.
+         * Asynchronously gets the {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}
+         * of a saved item.
          *
          * When invoked, this method returns the item ID via the callback function.
          *
-         * **Note**: If your add-in calls `getItemIdAsync` on an item in compose mode (e.g., to get an `itemId` to use with EWS or the REST API),
-         * be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server.
-         * Until the item is synced, the `itemId` is not recognized and using it returns an error.
-         *
          * @remarks
          * [Api set: Mailbox 1.8]
          *
@@ -10953,6 +10956,15 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Organizer
          *
+         * **Important**:
+         *
+         * - The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
+         *
+         * - If your add-in calls `getItemIdAsync` (for example, to get an item ID to use with EWS or the REST API),
+         * be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server.
+         * Until the item is synced, the item ID isn't recognized and using it returns an error.
+         *
          * **Errors**:
          *
          * - `ItemNotSaved`: The ID can't be retrieved until the item is saved.
@@ -10960,18 +10972,15 @@ declare namespace Office {
          * @param options - An object literal that contains one or more of the following properties:-
          *        `asyncContext`: Developers can provide any object they wish to access in the callback function.
          * @param callback - When the method completes, the function passed in the `callback` parameter is called with a single parameter
-         *                   of type `Office.AsyncResult`.
+         *                   of type `Office.AsyncResult`. The EWS item ID of the item is returned in the `asyncResult.value` property.
          */
         getItemIdAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
-         * Asynchronously gets the ID of a saved item.
+         * Asynchronously gets the {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}
+         * of a saved item.
          *
          * When invoked, this method returns the item ID via the callback function.
          *
-         * **Note**: If your add-in calls `getItemIdAsync` on an item in compose mode (e.g., to get an `itemId` to use with EWS or the REST API),
-         * be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server.
-         * Until the item is synced, the `itemId` is not recognized and using it returns an error.
-         *
          * @remarks
          * [Api set: Mailbox 1.8]
          *
@@ -10979,12 +10988,21 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Organizer
          *
+         * **Important**:
+         *
+         * - The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
+         *
+         * - If your add-in calls `getItemIdAsync` (for example, to get an item ID to use with EWS or the REST API),
+         * be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server.
+         * Until the item is synced, the item ID isn't recognized and using it returns an error.
+         *
          * **Errors**:
          *
          * - `ItemNotSaved`: The ID can't be retrieved until the item is saved.
          *
          * @param callback - When the method completes, the function passed in the `callback` parameter is called with a single parameter
-         *                   of type `Office.AsyncResult`.
+         *                   of type `Office.AsyncResult`. The EWS item ID of the item is returned in the `asyncResult.value` property.
          */
         getItemIdAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
@@ -11271,7 +11289,12 @@ declare namespace Office {
          * - When working with HTML-formatted content, it's important to note that the Outlook client may modify the content. This means that
          * subsequent calls to methods like `Body.getAsync`, `Body.setAsync`, and even `saveAsync` may not result in the same content.
          *
-         * - If your add-in calls `saveAsync` on an item in compose mode in order to get an item ID to use with EWS or the REST API, be aware that
+         * - The identifier returned is the same as the
+         * {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}.
+         * The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
+         *
+         * - If your add-in calls `saveAsync` to get an item ID to use with EWS or the REST API, be aware that
          * when Outlook is in cached mode, it may take some time before the item is actually synced to the server.
          * Until the item is synced, using the item ID will return an error.
          *
@@ -11286,7 +11309,7 @@ declare namespace Office {
          * @param options - An object literal that contains one or more of the following properties:-
          *        `asyncContext`: Developers can provide any object they wish to access in the callback function.
          * @param callback - When the method completes, the function passed in the `callback` parameter is called with a single parameter, `asyncResult`,
-         *                   which is an `Office.AsyncResult` object. The appointment ID is returned in the `asyncResult.value` property.
+         *                   which is an `Office.AsyncResult` object. The EWS appointment ID is returned in the `asyncResult.value` property.
          */
         saveAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
@@ -11311,7 +11334,12 @@ declare namespace Office {
          * - When working with HTML-formatted content, it's important to note that the Outlook client may modify the content. This means that
          * subsequent calls to methods like `Body.getAsync`, `Body.setAsync`, and even `saveAsync` may not result in the same content.
          *
-         * - If your add-in calls `saveAsync` on an item in compose mode in order to get an item ID to use with EWS or the REST API, be aware that
+         * - The identifier returned is the same as the
+         * {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}.
+         * The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
+         *
+         * - If your add-in calls `saveAsync` to get an item ID to use with EWS or the REST API, be aware that
          * when Outlook is in cached mode, it may take some time before the item is actually synced to the server.
          * Until the item is synced, using the item ID will return an error.
          *
@@ -11324,7 +11352,7 @@ declare namespace Office {
          * - `InvalidAttachmentId`: The attachment identifier does not exist.
          *
          * @param callback - When the method completes, the function passed in the `callback` parameter is called with a single parameter, `asyncResult`,
-         *                   which is an `Office.AsyncResult` object. The appointment ID is returned in the `asyncResult.value` property.
+         *                   which is an `Office.AsyncResult` object. The EWS appointment ID is returned in the `asyncResult.value` property.
          */
         saveAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
@@ -11690,24 +11718,23 @@ declare namespace Office {
          */
         itemClass: string;
         /**
-         * Gets the {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services item identifier}
-         * for the current item.
-         *
-         * The `itemId` property is not available in compose mode.
-         * If an item identifier is required, the `saveAsync` method can be used to save the item to the store, which will return the item identifier
-         * in the `asyncResult.value` parameter in the callback function.
-         *
-         * **Note**: The identifier returned by the `itemId` property is the same as the
-         * {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services item identifier}.
-         * The `itemId` property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API.
-         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
-         * For more details, see {@link https://learn.microsoft.com/office/dev/add-ins/outlook/use-rest-api#get-the-item-id | Use the Outlook REST APIs from an Outlook add-in}.
+         * Gets the {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}
+         * of the current item.
          *
          * @remarks
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Attendee
+         *
+         * **Important**:
+         *
+         * - The `itemId` property isn't available in compose mode.
+         * If an item identifier is required, the `Office.context.mailbox.item.saveAsync` method can be used to save the item to the store, which will return the item identifier
+         * in the `asyncResult.value` parameter in the callback function. If the item is already saved, you can call the `Office.context.mailbox.item.getItemIdAsync` method instead.
+         *
+         * - The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
          */
         itemId: string;
         /**
@@ -15080,15 +15107,6 @@ declare namespace Office {
         /**
          * Gets the URL of the REST endpoint for this email account.
          *
-         * Your app must have the **read item** permission specified in its manifest to call the `restUrl` member in read mode.
-         *
-         * In compose mode you must call the `saveAsync` method before you can use the `restUrl` member.
-         * Your app must have **read/write item** permissions to call the `saveAsync` method.
-         *
-         * However, in delegate or shared scenarios, you should instead use the `targetRestUrl` property of the
-         * {@link Office.SharedProperties | SharedProperties} object (introduced in requirement set 1.8). For more information,
-         * see the {@link https://learn.microsoft.com/office/dev/add-ins/outlook/delegate-access | shared folders and shared mailbox} article.
-         *
          * @remarks
          * [Api set: Mailbox 1.5]
          *
@@ -15096,7 +15114,21 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
          *
-         * The `restUrl` value can be used to make {@link https://learn.microsoft.com/outlook/rest/ | REST API} calls to the user's mailbox.
+         * **Important**:
+         *
+         * - The Outlook REST v2.0 and beta endpoints are now deprecated. However, privately released and AppSource-hosted add-ins are able to use the REST service
+         * until extended support ends for Outlook 2019 on October 14, 2025. Traffic from these add-ins is automatically identified for exemption. This exemption also
+         * applies to new add-ins developed after March 31, 2024. Although add-ins are able to use the REST service until 2025, we highly encourage you to migrate your
+         * add-ins to use {@link https://learn.microsoft.com/outlook/rest#outlook-rest-api-via-microsoft-graph | Microsoft Graph}. For guidance, see
+         * {@link https://learn.microsoft.com/outlook/rest/compare-graph | Compare Microsoft Graph and Outlook REST API endpoints}.
+         *
+         * - Your add-in must have the **read item** permission specified in its manifest to call the `restUrl` member in read mode.
+         *
+         * - In compose mode you must call the `saveAsync` method before you can use the `restUrl` member.
+         * Your add-in must have **read/write item** permissions to call the `saveAsync` method.
+         * However, in delegate or shared scenarios, you should instead use the `targetRestUrl` property of the
+         * {@link Office.SharedProperties | SharedProperties} object (introduced in requirement set 1.8). For more information,
+         * see the {@link https://learn.microsoft.com/office/dev/add-ins/outlook/delegate-access | shared folders and shared mailbox} article.
          */
         restUrl: string;
         /**
@@ -15159,10 +15191,17 @@ declare namespace Office {
          *
          * **Important**:
          *
+         * - In October 2024, legacy Exchange {@link https://learn.microsoft.com/office/dev/add-ins/outlook/authentication#exchange-user-identity-token | user identity} and
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/authentication#callback-tokens | callback} tokens will be turned off by default for all Exchange Online tenants.
+         * This is part of {@link https://blogs.microsoft.com/on-the-issues/2023/11/02/secure-future-initiative-sfi-cybersecurity-cyberattacks/ | Microsoft's Secure Future Initiative},
+         * which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises.
+         * Nested app authentication is the recommended approach for tokens going forward. For more information, see our {@link https://aka.ms/NAApreviewblog | blog post} and
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/faq-nested-app-auth-outlook-legacy-tokens | FAQ page}.
+         *
          * - This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
          * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis | Outlook JavaScript APIs supported in Outlook on mobile devices}.
          *
-         * - Item IDs retrieved via a REST API (such as the Outlook Mail API or the Microsoft Graph) use a different format than the format used by EWS.
+         * - Item IDs retrieved via a REST API (such as {@link https://graph.microsoft.io/ | Microsoft Graph}) use a different format than the format used by EWS.
          * The `convertToEwsId` method converts a REST-formatted ID into the proper format for EWS.
          *
          * @param id - The ID to be converted into EWS format. This string can be an item ID formatted for the Outlook REST APIs or a conversation ID retrieved from
@@ -15206,10 +15245,8 @@ declare namespace Office {
          * - This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
          * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis | Outlook JavaScript APIs supported in Outlook on mobile devices}.
          *
-         * - Item IDs retrieved via Exchange Web Services (EWS) or via the `itemId` property use a different format than the format used by REST APIs (such as the
-         * {@link https://learn.microsoft.com/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations | Outlook Mail API}
-         * or the {@link https://graph.microsoft.io/ | Microsoft Graph}).
-         * The `convertToRestId` method converts an EWS-formatted ID into the proper format for REST.
+         * - Item IDs retrieved via Exchange Web Services (EWS) or via the `itemId` property use a different format than the format used by REST APIs (such as
+         * {@link https://graph.microsoft.io/ | Microsoft Graph}). The `convertToRestId` method converts an EWS-formatted ID into the proper format for REST.
          *
          * @param id - The ID to be converted into REST format. This string can be an item ID formatted for EWS that's usually retrieved from
          *             `Office.context.mailbox.item.itemId`, a conversation ID retrieved from `Office.context.mailbox.item.conversationId`, or a
@@ -15678,6 +15715,12 @@ declare namespace Office {
          * Nested app authentication is the recommended approach for tokens going forward. For more information, see our {@link https://aka.ms/NAApreviewblog | blog post} and
          * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/faq-nested-app-auth-outlook-legacy-tokens | FAQ page}.
          *
+         * - The Outlook REST v2.0 and beta endpoints are now deprecated. However, privately released and AppSource-hosted add-ins are able to use the REST service
+         * until extended support ends for Outlook 2019 on October 14, 2025. Traffic from these add-ins is automatically identified for exemption. This exemption also
+         * applies to new add-ins developed after March 31, 2024. Although add-ins are able to use the REST service until 2025, we highly encourage you to migrate your
+         * add-ins to use {@link https://learn.microsoft.com/outlook/rest#outlook-rest-api-via-microsoft-graph | Microsoft Graph}. For guidance, see
+         * {@link https://learn.microsoft.com/outlook/rest/compare-graph | Compare Microsoft Graph and Outlook REST API endpoints}.
+         *
          * - This method isn't supported if you load an add-in in an Outlook.com or Gmail mailbox.
          *
          * - This method is only supported in read mode in Outlook on Android and on iOS. For more information on supported APIs in Outlook mobile, see
@@ -17249,14 +17292,11 @@ declare namespace Office {
          */
         getItemClassAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
-         * Asynchronously gets the ID of a saved item.
+         * Asynchronously gets the {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}
+         * of a saved item.
          *
          * When invoked, this method returns the item ID via the callback function.
          *
-         * **Note**: If your add-in calls `getItemIdAsync` on an item in compose mode (e.g., to get an `itemId` to use with EWS or the REST API),
-         * be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server.
-         * Until the item is synced, the `itemId` is not recognized and using it returns an error.
-         *
          * @remarks
          * [Api set: Mailbox 1.8]
          *
@@ -17264,6 +17304,15 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Compose
          *
+         * **Important**:
+         *
+         * - The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
+         *
+         * - If your add-in calls `getItemIdAsync` (for example, to get an item ID to use with EWS or the REST API),
+         * be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server.
+         * Until the item is synced, the item ID isn't recognized and using it returns an error.
+         *
          * **Errors**:
          *
          * - `ItemNotSaved`: The ID can't be retrieved until the item is saved.
@@ -17271,18 +17320,15 @@ declare namespace Office {
          * @param options - An object literal that contains one or more of the following properties:-
          *        `asyncContext`: Developers can provide any object they wish to access in the callback function.
          * @param callback - When the method completes, the function passed in the `callback` parameter is called with a single parameter
-         *                   of type `Office.AsyncResult`.
+         *                   of type `Office.AsyncResult`. The EWS item ID of the item is returned in the `asyncResult.value` property.
          */
         getItemIdAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
-         * Asynchronously gets the ID of a saved item.
+         * Asynchronously gets the {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}
+         * of a saved item.
          *
          * When invoked, this method returns the item ID via the callback function.
          *
-         * **Note**: If your add-in calls `getItemIdAsync` on an item in compose mode (e.g., to get an `itemId` to use with EWS or the REST API),
-         * be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server.
-         * Until the item is synced, the `itemId` is not recognized and using it returns an error.
-         *
          * @remarks
          * [Api set: Mailbox 1.8]
          *
@@ -17290,12 +17336,21 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Compose
          *
+         * **Important**:
+         *
+         * - The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
+         *
+         * - If your add-in calls `getItemIdAsync` (for example, to get an item ID to use with EWS or the REST API),
+         * be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server.
+         * Until the item is synced, the item ID isn't recognized and using it returns an error.
+         *
          * **Errors**:
          *
          * - `ItemNotSaved`: The ID can't be retrieved until the item is saved.
          *
          * @param callback - When the method completes, the function passed in the `callback` parameter is called with a single parameter
-         *                   of type `Office.AsyncResult`.
+         *                   of type `Office.AsyncResult`. The EWS item ID of the item is returned in the `asyncResult.value` property.
          */
         getItemIdAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
@@ -17626,7 +17681,12 @@ declare namespace Office {
          * - When working with HTML-formatted content, it's important to note that the Outlook client may modify the content. This means that
          * subsequent calls to methods like `Body.getAsync`, `Body.setAsync`, and even `saveAsync` may not result in the same content.
          *
-         * - If your add-in calls `saveAsync` on an item in compose mode in order to get an item ID to use with EWS or the REST API, be aware that
+         * - The identifier returned is the same as the
+         * {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}.
+         * The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
+         *
+         * - If your add-in calls `saveAsync` to get an item ID to use with EWS or the REST API, be aware that
          * when Outlook is in cached mode, it may take some time before the item is actually synced to the server.
          * Until the item is synced, using the item ID will return an error.
          *
@@ -17643,7 +17703,7 @@ declare namespace Office {
          * @param options - An object literal that contains one or more of the following properties:-
          *        `asyncContext`: Developers can provide any object they wish to access in the callback function.
          * @param callback - When the method completes, the function passed in the `callback` parameter is called with a single parameter, `asyncResult`,
-         *                   which is an `Office.AsyncResult` object. The message ID is returned in the `asyncResult.value` property.
+         *                   which is an `Office.AsyncResult` object. The EWS message ID is returned in the `asyncResult.value` property.
          */
         saveAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
@@ -17664,7 +17724,12 @@ declare namespace Office {
          * - When working with HTML-formatted content, it's important to note that the Outlook client may modify the content. This means that
          * subsequent calls to methods like `Body.getAsync`, `Body.setAsync`, and even `saveAsync` may not result in the same content.
          *
-         * - If your add-in calls `saveAsync` on an item in compose mode in order to get an item ID to use with EWS or the REST API, be aware that
+         * - The identifier returned is the same as the
+         * {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}.
+         * The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
+         *
+         * - If your add-in calls `saveAsync` to get an item ID to use with EWS or the REST API, be aware that
          * when Outlook is in cached mode, it may take some time before the item is actually synced to the server.
          * Until the item is synced, using the item ID will return an error.
          *
@@ -17679,7 +17744,7 @@ declare namespace Office {
          * - `InvalidAttachmentId`: The attachment identifier does not exist.
          *
          * @param callback - When the method completes, the function passed in the `callback` parameter is called with a single parameter, `asyncResult`,
-         *                   which is an `Office.AsyncResult` object. The message ID is returned in the `asyncResult.value` property.
+         *                   which is an `Office.AsyncResult` object. The EWS message ID is returned in the `asyncResult.value` property.
          */
         saveAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;
         /**
@@ -17969,24 +18034,23 @@ declare namespace Office {
          */
         itemClass: string;
         /**
-         * Gets the {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services item identifier}
-         * for the current item.
-         *
-         * The `itemId` property is not available in compose mode.
-         * If an item identifier is required, the `saveAsync` method can be used to save the item to the store, which will return the item identifier
-         * in the `asyncResult.value` parameter in the callback function.
-         *
-         * **Note**: The identifier returned by the `itemId` property is the same as the
-         * {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services item identifier}.
-         * The `itemId` property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API.
-         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
-         * For more details, see {@link https://learn.microsoft.com/office/dev/add-ins/outlook/use-rest-api#get-the-item-id | Use the Outlook REST APIs from an Outlook add-in}.
+         * Gets the {@link https://learn.microsoft.com/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange | Exchange Web Services (EWS) item identifier}
+         * of the current item.
          *
          * @remarks
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Read
+         *
+         * **Important**:
+         *
+         * - The `itemId` property isn't available in compose mode.
+         * If an item identifier is required, the `Office.context.mailbox.item.saveAsync` method can be used to save the item to the store, which will return the item identifier
+         * in the `asyncResult.value` parameter in the callback function. If the item is already saved, you can call the `Office.context.mailbox.item.getItemIdAsync` method instead.
+         *
+         * - The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API.
+         * Before making REST API calls using this value, it should be converted using `Office.context.mailbox.convertToRestId`.
          */
         itemId: string;
         /**

office-js-preview/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/office-js-preview",
-    "version": "1.0.521",
+    "version": "1.0.522",
     "description": "TypeScript definitions for office-js-preview",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/office-js-preview",
     "license": "MIT",
@@ -45,7 +45,7 @@
     },
     "scripts": {},
     "dependencies": {},
-    "typesPublisherContentHash": "a3542c6db6962acb403934f7a69a923bbe5eda9457d0995666898b3c22fe463e",
+    "typesPublisherContentHash": "83834c7b28bf4e61dfea9c8a5245488657f680721bad1588fac8278fb33127ca",
     "typeScriptVersion": "4.8",
     "nonNpm": true
 }