[DEPRECATED] Use the Outlook REST API (beta)

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

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.

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:

• Use Azure AD v2 authentication endpoint
• Use Azure Active Directory and OAuth

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:

• Microsoft Application Registration Portal
• v2 authorization scopes
• v2 authentication endpoints
  • https://login.microsoftonline.com/common/oauth2/v2.0/authorize
  • https://login.microsoftonline.com/common/oauth2/v2.0/token
• v2 ADAL libraries

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.

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.

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.

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.

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.

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:

• iOS
• Android
• JavaScript
• .NET

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:

• Mail API reference
• Calendar API reference
• Contacts API reference
• Task REST API
• Resource reference for the Mail, Calendar, Contacts, and Task REST APIs
• People API reference
• Data Extensions API reference
• Extended Properties API reference
• Push Notifications REST API reference
• Streaming Notifications REST API reference (preview)
• User Photo REST API reference
• Batch Outlook REST requests