[Outlook] Update REST and Graph articles (#4971)

* Update REST deprecation note

* Draft MS Graph article

* Apply minor fixes

* Update TOC

* Apply suggestions from review

Co-authored-by: Linda Cannon <[email protected]>

* Apply suggestions from review

Co-authored-by: David Chesnut <[email protected]>

* Apply suggestions from review and update include

---------

Co-authored-by: Linda Cannon <[email protected]>
Co-authored-by: David Chesnut <[email protected]>

Author: 3 people

docs/includes/legacy-exchange-token-deprecation.md

@@ -1,2 +1,2 @@
 > [!IMPORTANT]
-> Legacy Exchange tokens are deprecated. Starting February 2025, we'll begin to turn off legacy Exchange  [user identity](../outlook/authentication.md#exchange-user-identity-token) and [callback](../outlook/authentication.md#callback-tokens) tokens for Exchange Online tenants. For the timeline and details, see our [FAQ page](../outlook/faq-nested-app-auth-outlook-legacy-tokens.md). This is part of [Microsoft's Secure Future Initiative](https://blogs.microsoft.com/on-the-issues/2023/11/02/secure-future-initiative-sfi-cybersecurity-cyberattacks/), 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.
+> Legacy Exchange tokens are deprecated. Legacy Exchange [user identity](../outlook/authentication.md#exchange-user-identity-token) and [callback](../outlook/authentication.md#callback-tokens) tokens have been turned off for most Exchange Online tenants. Administrators can reenable legacy tokens for tenants and add-ins until June 2025. In October 2025, legacy tokens will be completely turned off for all tenants. For the timeline and details, see our [FAQ page](../outlook/faq-nested-app-auth-outlook-legacy-tokens.md). This is part of [Microsoft's Secure Future Initiative](https://blogs.microsoft.com/on-the-issues/2023/11/02/secure-future-initiative-sfi-cybersecurity-cyberattacks/), 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.

docs/outlook/microsoft-graph.md

@@ -0,0 +1,40 @@
+---
+title: Use the Microsoft Graph REST API from an Outlook add-in
+description: Learn how to use the Outlook mail REST API from an Outlook add-in with Microsoft Graph.
+ms.date: 04/22/2025
+ms.topic: how-to
+ms.localizationpriority: medium
+---
+
+# Use the Microsoft Graph REST API from an Outlook add-in
+
+The Outlook JavaScript API (Office.js) retrieves the properties of messages and appointments and run operations on these items in your add-in. However, there may be instances where the data you need isn't available through the API. For example, your add-in may need to implement single sign-on or identify messages in a user's mailbox that originated from the same sender. To get the information you need, use the [Outlook mail REST API](/graph/api/resources/mail-api-overview) through [Microsoft Graph](/graph/overview).
+
+## Get started
+
+To make calls to the Microsoft Graph API in Office Add-ins, implement the [nested app authentication (NAA)](../develop/enable-nested-app-authentication-in-your-add-in.md) solution to request a token.
+
+[!INCLUDE [legacy-exchange-token-deprecation](../includes/legacy-exchange-token-deprecation.md)]
+
+## Call the Microsoft Graph API
+
+Once you have an access token, you can then use it to call Microsoft Graph.
+
+The Microsoft Graph API consists of the v1.0 and beta endpoints. Note the following about the endpoint pattern.
+
+- `version` specifies the `v1.0` or `beta` API.
+- `resource` specifies the resource your add-in interacts with, such as a user, group, or site.
+- `query_parameters` specifies parameters to customize your request. For example, you can filter the messages returned to only those from a specific sender.
+
+```http
+https://graph.microsoft.com/[version]/[resource]?[query_parameters]
+```
+
+For more information on the Microsoft Graph API and its components, see [Use the Microsoft Graph API](/graph/use-the-api).
+
+## See also
+
+- [Microsoft Graph REST API v1.0 endpoint reference](/graph/api/overview)
+- [Outlook mail API overview](/graph/outlook-mail-concept-overview)
+- [Use the Outlook mail REST API](/graph/api/resources/mail-api-overview)
+- [Enable SSO in an Office Add-in using nested app authentication (preview)](../develop/enable-nested-app-authentication-in-your-add-in.md)

docs/outlook/use-rest-api.md

@@ -1,7 +1,7 @@
 ---
 title: Use the Outlook REST APIs from an Outlook add-in
 description: Learn how to use the Outlook REST APIs from an Outlook add-in to get an access token.
-ms.date: 02/12/2024
+ms.date: 04/22/2025
 ms.topic: how-to
 ms.localizationpriority: medium
 ---
@@ -11,14 +11,16 @@ ms.localizationpriority: medium
 The [Office.context.mailbox.item](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item) namespace provides access to many of the common fields of messages and appointments. However, in some scenarios an add-in may need to access data that isn't exposed by the namespace. For example, the add-in may rely on custom properties set by an outside app, or it needs to search the user's mailbox for messages from the same sender. In these scenarios, the [Outlook REST APIs](/outlook/rest) is the recommended method to retrieve the information.
 
 > [!IMPORTANT]
-> **Outlook REST v2.0 and beta endpoints deprecation**
+> **Outlook REST v2.0 and beta endpoints are deprecated**
 >
-> The Outlook REST v2.0 and beta endpoints will be [fully deprecated on March 31, 2024](https://devblogs.microsoft.com/microsoft365dev/outlook-rest-api-v2-0-and-beta-endpoints-decommissioning-update/). 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](/lifecycle/end-of-support/end-of-support-2025). Traffic from these add-ins is automatically identified for exemption. This exemption also applies to new add-ins developed after the decommission date.
+> The Outlook REST v2.0 and beta endpoints are now [deprecated](https://devblogs.microsoft.com/microsoft365dev/final-reminder-outlook-rest-api-v2-0-and-beta-endpoints-decommissioning/). However, privately released and AppSource-hosted add-ins are still able to use the REST service until [extended support ends for Outlook 2019 on October 14, 2025](/lifecycle/end-of-support/end-of-support-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 [Microsoft Graph](/outlook/rest#outlook-rest-api-via-microsoft-graph). For guidance, see [Compare Microsoft Graph and Outlook REST API endpoints](/outlook/rest/compare-graph).
+> Although add-ins are able to use the REST service until October 2025, we highly encourage you to migrate your add-ins to use [Microsoft Graph](microsoft-graph.md).
 
 ## Get an access token
 
+[!INCLUDE [legacy-exchange-token-deprecation](../includes/legacy-exchange-token-deprecation.md)]
+
 The Outlook REST APIs require a bearer token in the `Authorization` header. Typically apps use OAuth2 flows to retrieve a token. However, add-ins can retrieve a token without implementing OAuth2 by using the new [Office.context.mailbox.getCallbackTokenAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox#methods) method introduced in the Mailbox requirement set 1.5.
 
 By setting the `isRest` option to `true`, you can request a token compatible with the REST APIs.
@@ -117,5 +119,5 @@ function getCurrentItem(accessToken) {
 
 ## See also
 
-- For an example that calls the REST APIs from an Outlook add-in, see [command-demo](https://github.com/OfficeDev/outlook-add-in-command-demo) on GitHub.
-- Outlook REST APIs are also available through the Microsoft Graph endpoint but there are some key differences, including how your add-in gets an access token. For more information, see [Outlook REST API via Microsoft Graph](/outlook/rest/index#outlook-rest-api-via-microsoft-graph).
+- [Add-in Command sample](https://github.com/OfficeDev/outlook-add-in-command-demo)
+- [Use the Microsoft Graph REST API from an Outlook add-in](microsoft-graph.md)

docs/toc.yml

@@ -780,6 +780,8 @@ items:
       href: outlook/extension-module-outlook-add-ins.md
     - name: On-send add-ins
       href: outlook/outlook-on-send-addins.md
+    - name: Call the Microsoft Graph API
+      href: outlook/microsoft-graph.md
     - name: Call Outlook REST APIs
       href: outlook/use-rest-api.md
     - name: Call Exchange web services