In this article

Overview of using the Outlook REST APIs

04/26/2017

7 minutes to read

Contributors

In this article

Tip

Try out sample REST calls in the Graph Explorer. You can use your own account, or one of our test accounts. Once you're done exploring the API, come back here and select your favorite platform on the left. We'll guide you through the steps to write a simple application to retrieve messages from your inbox.

If your preferred platform isn't listed yet, continue reading on this page. We'll go through the same set of steps using raw HTTP requests.

The purpose of this guide is to walk through the process of calling the Outlook Mail API to retrieve messages in Office 365 and Outlook.com. Unlike the platform-specific getting started guides, this guide focuses on the OAuth and REST requests and responses. It will cover the sequence of requests and responses that an app uses to authenticate and retrieve messages.

This tutorial will use Microsoft Graph to call the Mail API. Microsoft recommends using Microsoft Graph to access Outlook mail, calendar, and contacts. You should use the Outlook APIs directly (via https://outlook.office.com/api) only if you require a feature that is not available on the Graph endpoints.

With the information in this guide, you can implement this in any language or platform capable of sending HTTP requests.

Use OAuth2 to authenticate

In order to call the Mail API, the app requires an access token from Azure Active Directory. In order to do that, the app implements one of the supported OAuth flows in the Azure v2.0 endpoint. However, before this will work, the app must be registered in the Application Registration Portal.

Needs to access other Office 365 workloads besides Outlook (such as OneDrive for Business or SharePoint)

Bear in mind that apps registered using the Azure Management Portal will not be compatible with Outlook.com, and will not be able to dynamically request permissions scopes.
Existing app registrations that were created in the Azure Management Portal will continue to work for Office 365 only. These registrations do not show up in the Application Registration Portal and must be managed in the Azure Management Portal.

Account requirements

In order to use the Application Registration Portal, you need either an Office 365 work or school account, or a Microsoft account. If you don't have either of these, you have a number of options:

For example, an application that requires read access to mail would put all of those together to generate a request URL like the following:

Authorization code request

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<CLIENT ID>&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_type=code&scope=openid+Mail.Read

The user will be presented with a sign in screen that displays the name of the app. Once they sign in, if it is their first time using the app, the user will be presented with a list of the app permissions the app requires and asked to allow or deny. Assuming they allow the required access, the browser will be redirected to the redirect URI specified in the initial request.

Access token response

The access token is found in the access_token field of the JSON payload. The app uses this value to set the Authorization header when making REST calls to the API.

Calling the Mail API

Once the app has an access token, it's ready to call the Mail API. The Mail API Reference has all of the details. Since the app is retrieving messages, it will use an HTTP GET request to the https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages URL. This will retrieve messages from the inbox.

Refining the request

Apps can control the behavior of GET requests by using OData query parameters. It is recommended that apps use these parameters to limit the number of results that are returned and to limit the fields that are returned for each item. Let's look at an example.

Consider an app that displays messages in a table. The table only displays the subject, sender, and the date and time the message was received. The table displays a maximum of 25 rows, and should be sorted so that the most recently received message is at the top.

To achieve this, the app uses the following query parameters:

The $select parameter is used to specify only the subject, from, and receivedDateTime fields.

The $top parameter is used to specify a maximum of 25 items.

The $orderby parameter is used to sort the results by the receivedDateTime field.

Now that you've seen how to make calls to the Mail API, you can use the API reference to construct any other kinds of calls your app needs to make. However, bear in mind that your app needs to have the appropriate permissions configured on the app registration for the calls it makes.

Feedback

We'd love to hear your thoughts. Choose the type you'd like to provide: