Share via

[DEPRECATED] Use the Outlook REST API (beta)

  • Article

Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Note

The beta version of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. Consequently, the beta REST endpoint is also deprecated and will be fully decommissioned in November 2022. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

The Outlook REST API includes the following subsets to allow access to users' mailbox data in Office 365, Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.

The following table lists the first version that the core functionality of each subset was made available. Note that within a subset, new features and API can be subsequently added to a later version.

API subset Available versions
Batching multiple API calls v2.0, beta
Calendar API v2.0, v1.0, beta
Contacts API v2.0, v1.0, beta
Data Extensions API v2.0, beta
Extended Properties API v2.0, beta
Mail API v2.0, v1.0, beta
Push Notifications API v2.0, beta
Streaming Notifications API (preview) beta
People API beta
Task API v2.0, beta
User Photo API v2.0, beta

Note

The rest of this article describes common information applicable to all subsets of the Outlook REST API. For simplicity of reference, the rest of this article uses Outlook.com to include accounts in the domains Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.

Register and authenticate your app

To use the Outlook REST API to access a user's mailbox data, your app should handle registration and user authorization:

  1. First, register your app to get access to the Outlook REST API. You can then implement the API calls in your app.

  2. At runtime, get authorization from the user and make REST API requests to access the user's mailbox.

There are currently two approaches to handle app registration and user authorization:

Azure AD v2 authentication endpoint

The Azure AD v2 authentication endpoint simplifies building an app that works with both Microsoft organizational and personal accounts. It enables work, school, and personal account users to sign in with a single button.

This converged programming model is the latest approach and is comprised of the following:

This approach gives you a seamless app registration and user authorization experience to get the appropriate tokens to access users' mailbox data on Office 365 and/or Outlook.com. If you are developing an app for Outlook.com, you must use this approach.

Instead of requesting permissions during app registration, the v2 authentication endpoint lets you dynamically prompt and request the necessary permissions based on corresponding user actions at runtime.

This converged programming model consists of several components, so if you use one component, you should use the others as well.

To learn more, see examples on getting started, and Authenticate Office 365 and Outlook.com APIs using the the v2 authentication endpoint.

Important

As you create or update an app, make sure your app can handle Outlook.com mailboxes that have been enabled and you can access using the Outlook REST API, and those mailboxes that are waiting to be enabled. Find out more about testing and handling such Outlook.com scenarios.

Register and authenticate using Azure AD and OAuth

This is an earlier approach to access mailbox data on only Office 365. If you're planning to access data on Outlook.com, or create a new app for Office 365, use the v2 authentication endpoint instead.

For the time being, to access Office 365 mailbox data, you can continue to register an app in Azure AD as before, specifying the permissions at the appropriate scope that your app requires. At runtime, your app can continue to use Azure AD and OAuth to authenticate application requests. You can find details at Office 365 app authentication concepts. You should plan for an upgrade path.

With this approach, you can choose to access the Outlook REST API by calling it directly in your Office 365 apps, or by using the Office 365 client libraries.

Upgrade path

The v2 authentication endpoint has been promoted from preview to Generally Available (GA) status for Outlook and Outlook.com developers.

If you have an in-production app that accesses Office 365 mailbox data, or if you are creating a new app for Office 365 or Outlook.com, plan to use the v2 authentication endpoint together with the latest Outlook endpoint (https://outlook.office.com/, see more below) to take advantage of writing just one set of code for both organizational Office 365 and personal Outlook.com users.

If you have an in-production app that uses Windows Live API to access Outlook.com mailbox data, you must rewrite the app to use the the v2 authentication endpoint and the Outlook REST API. Because Windows Live API is being deprecated for Outlook.com, and Outlook.com users get their mailboxes enabled for the Outlook REST API, these users will get HTTP 404 errors when attempting to run such Windows Live API apps.

On the other hand, the Outlook REST API opens up new opportunities for you—you can choose from a list of common languages such as Node, Python, Swift, Java, and so on, write the app once, and capture both Outlook.com and Office 365 users on the web, iOS, Android, or Windows devices.

Note

If you intend your in-production app to continue to access only Outlook.com mailbox data, you can continue to use the same Windows Live scopes to access most of the Outlook REST API. For more information, see Using Windows Live scopes and Outlook REST API to access Outlook.com mailbox data.

Regardless of the approach you use for app registration and user authorization, or whether your app targets Office 365 or Outlook.com mailbox data, the latest Outlook REST endpoint is in production and you can start using it in your REST API calls whenever you are ready:

https://outlook.office.com/api/{version}/{user_context}

The following Outlook REST endpoint will continue to work for a while for only Office 365 mailbox data:

https://outlook.office365.com/api/{version}/{user_context}

See more about supported REST actions, endpoints and versions below.

Important

  • Basic authorization is no longer supported by the Outlook REST API endpoint https://outlook.office.com. Use the v2 authentication endpoint or Azure AD to do authorization and authentication for an app that uses the new Outlook REST API endpoint.
  • For optimal performance when using the new Outlook REST endpoint, add an x-AnchorMailbox header for every request and set it to the user's email address. For example: x-AnchorMailbox:john@contoso.com
  • Because enabling mailboxes on Outlook.com for the Outlook REST API happens over a period of time, your existing Outlook.com account may take a while to get enabled. To test your app accessing data on Outlook.com mailboxes that have already been enabled, you can request a new, enabled Outlook.com developer preview account by emailing outlookdev@microsoft.com.
  • If your app accesses Outlook.com mailbox data, it should handle scenarios where the user's mailbox has not yet been enabled for the Outlook REST API. In such situations, when you make a REST request, you would get an error like the following:
    • HTTP error: 404
    • Error code: MailboxNotEnabledForRESTAPI or MailboxNotSupportedForRESTAPI
    • Error message: “REST API is not yet supported for this mailbox.
  • For code samples that use the v2 authentication endpoint, see dev.outlook.com.

Using Windows Live scopes and Outlook REST API to access Outlook.com mailbox data

If your in-production app for Outlook.com uses Windows Live scopes, and you don't intend to target Office 365 mailbox data, you can continue to use these Windows Live scopes with most of the Outlook REST API. The table below shows how Windows Live scopes map to the Outlook REST API scopes. Note that there isn't a Windows Live scope direct mapping for Mail.Read; your app can use wl.imap to access those Outlook REST API operations that require Mail.Read.

Windows Live scopes Outlook REST API scopes
wl.basic User.Read, Contacts.Read
wl.calendars Calendars.Read
wl.calendars_update Calendars.ReadWrite
wl.contacts_create Contacts.ReadWrite
wl.contacts_calendars Calendars.Read
wl.emails User.Read
wl.events_create Calendars.ReadWrite
wl.imap Mail.ReadWrite, Mail.Send

Supported REST actions and endpoints

To interact with the Outlook REST API, you send HTTP requests that use a supported method: GET, POST, PATCH, or DELETE. POST and PATCH request bodies and server responses are sent in JSON payloads.

The path URL resource names and query parameters are case insensitive. However, values you assign, entity IDs, and other base64 encoded values are case sensitive.

All Outlook REST API requests use the following new root URL format:

https://outlook.office.com/api/{version}/{user_context}

With the appropriate user authorization, the REST API in this root URL provides access to mailbox data on Office 365 and Outlook.com. The rest of this article describes REST API in this endpoint.

If you have code that uses the pre-existing root URL https://outlook.office365.com/api/{version}/{user_context}, your code will continue to work for a while for Office 365, but you should plan to switch to the new root URL.

Important

For optimal performance, when making a REST request using the new root URL, add an x-AnchorMailbox header and set it to the user's email address. Also, handle the case where an Outlook.com user's mailbox has not yet been enabled for the Outlook REST API; check for the error codes MailboxNotEnabledForRESTAPI and MailboxNotSupportedForRESTAPI. See more information here.

Notes for developers in China

  • If you are developing apps for Office 365 in China, you should continue to use the API endpoints of Office 365 for China.

  • If you are creating apps for Outlook.com in China, try the v2 authentication endpoint, and use the following new Outlook REST endpoint: https://outlook.office.com/api/{version}/{user_context}.

Supported versions of API

{version} represents the version of the Outlook REST API in the specified root URL. You can specify one of the following values:

  • v1.0. The is the earliest version in General Availability (GA) status and can be used in production code. An example URL is http://outlook.office.com/api/v1.0/me/events.

  • v2.0. This version is also in GA status and can be used in production code. An example URL is http://outlook.office.com/api/v2.0/me/events. This version includes changes that may break v1.0, and additional API sets that have matured and been promoted from preview to GA status.

  • beta. This version is in preview status and should not be used in production code. An example URL is http://outlook.office.com/api/beta/me/events. This version includes the latest API in GA, as well as additional API sets that are in preview, and that may change prior to finalization.

The majority of the REST operations in the Outlook REST API is supported and behaves the same way as described across the above listed versions.

Target user

With the exception of the User Photo REST API, {user_context} is the currently signed-in user, as the Outlook REST API requests are always performed on behalf of the current user.

For the User Photo REST API, {user_context} can be the signed-in user, or a user specified by a user ID.

Regardless of the set of Outlook REST API, you can specify {user_context} in REST requests in one of the following ways:

  • With the me shortcut: /api/{version}/me. The root URL becomes https://outlook.office.com/api/{version}/me.

  • With the users/{upn} format to pass the UPN or a proxy address of the signed-in user, such as: /api/beta/users/sadie@contoso.com. In this example, the root URL would become https://outlook.office.com/api/beta/users/sadie@contoso.com.

  • With the users/{AAD_userId@AAD_tenandId} format, utilizing the user ID and tenant ID in Azure Active Directory. For example, users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77. The root URL would become https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77.

Usage is a matter of preference.

In server responses, the user context is identified in this format: users/{AAD_userId@AAD_tenandId}.

Accessing item in a collection

The Outlook REST API supports two ways of specifying an item in an entity collection. They are evaluated identically, so usage is a matter of preference.

  • In the URL segment after the collection, for example: /api/{version}/me/events/AAMkAGI3...

  • In parentheses as a quoted string, for example: /api/{version}/me/events('AAMkAGI3...')

Use a client library to access the Outlook REST API

The Office 365 API client libraries make it easier to interact with the REST API:

They help manage authentication tokens and simplify the code needed to query and consume data on Office 365.

Shutting down of earlier preview endpoint

If you are already using https://outlook.office.com/api or https://outlook.office365.com/api as the root URL to access Outlook REST API, this deprecation doesn't affect you. Read on if you are still using the earlier preview endpoint https://outlook.office365.com/ews/odata.

The Outlook REST API moved from its initial preview to v1.0 general availability in October 2014. To complete this transition, we shut down the old preview endpoint https://outlook.office365.com/ews/odata on October 15, 2015.

We required all apps and services using the old endpoint https://outlook.office365.com/ews/odata to move to https://outlook.office.com/api/v1.0 by October 15, 2015. v1.0 was the minimum general availability (GA) endpoint to move to by that date.

Alternatively, you can use the preferred GA endpoint v2.0 (https://outlook.office.com/api/v2.0), or the preview endpoint (https://outlook.office.com/api/beta) to try the latest APIs in preview status. Keep in mind that in general, API in preview status may change before finalization. If you use them, be prepared to verify features in your app and make appropriate changes. When in-preview APIs get finalized, you will be able to access these enhancements in a GA endpoint as well.

Next steps

Proceed to use the Outlook REST API: