Edit

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 runs 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 through Microsoft Graph.

Get started

To call Microsoft Graph from your add-in, implement the nested app authentication (NAA) solution to get an access token. NAA uses the Microsoft Authentication Library (MSAL) to silently acquire a token for the signed-in user without requiring a redirect to a sign-in page. The token is scoped to the Microsoft Graph API endpoints your add-in needs.

Important

Legacy Exchange Online user identity tokens and callback tokens are no longer supported and 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. Exchange user identity tokens are still supported for Exchange on-premises.

Call the Microsoft Graph API

Once you have an access token, use it to call Microsoft Graph by passing it as a Bearer token in the Authorization header.

The Microsoft Graph API uses the following endpoint pattern.

  • version specifies v1.0 (stable) or beta (preview).
  • resource specifies the resource your add-in interacts with, such as a user, group, or site.
  • query_parameters are optional parameters to filter, sort, or paginate results.
https://graph.microsoft.com/[version]/[resource]?[query_parameters]

The following example shows how to get the signed-in user's messages using the Fetch API after acquiring an access token.

// Call the Microsoft Graph API to get the user's messages.
const response = await fetch('https://graph.microsoft.com/v1.0/me/messages', {
    headers: {
        'Authorization': 'Bearer ' + accessToken
    }
});
const data = await response.json();
console.log(data.value); // Array of message objects

For more information on the Microsoft Graph API and its components, see Use the Microsoft Graph API.

See also

  • Last updated on