Add Ins Connectors REST APIs Actionable Messages Feedback Blog Code Samples Videos

Get Started with Mail, Calendar, and Contacts REST APIs

Try out a sample REST call in our Outlook OAuth Sandbox. 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.

Note: Outlook APIs for Office 365 and Outlook.com are also available via Microsoft Graph.

Getting Started with the Outlook Mail API and REST

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.

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 the Authorization Grant Flow. However, before this will work, the app must be registered in the Application Registration Portal.

Registering an app

You can use the Application Registration Portal to quickly register an app that uses any of the Outlook APIs.

New app registrations should be created and managed in the new Application Registration Portal to be compatible with Outlook.com. Only create new app registrations in the Outlook Dev Center App Registration Tool or the Azure Management Portal if your app:

  • Uses the OAuth2 Client Credentials Grant Flow, or
  • Needs to access other Office 365 workloads besides Outlook (such as OneDrive for Business or SharePoint)

Bear in mind that apps registered using the Outlook Dev Center App Registration Tool or 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 Outlook Dev Center App Registration Tool or 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:

  • Sign up for a new Microsoft account here.
  • You can obtain an Office 365 subscription in a couple of different ways:

REST API availability

The REST API is currently enabled on all Office 365 accounts that have Exchange Online, and some Outlook.com accounts. Microsoft accounts with Outlook.com mailboxes (including Outlook.com, Hotmail.com, Live.com, MSN.com, and Passport.com) are in the process of being upgraded to enable the REST APIs. During this process, making API calls to mailboxes that are not yet upgraded will return a MailboxNotEnabledForRESTAPI or MailboxNotSupportedForRESTAPI error code.

If you want to use the REST APIs with your existing Outlook.com mailbox and you are receiving a MailboxNotEnabledForRESTAPI or MailboxNotSupportedForRESTAPI error code, your account has not yet been upgraded. Rest assured that your account will be upgraded in a future batch. In the meantime, you can sign up for a new account here. All new accounts are enabled for the REST API immediately!

Once you register the app, you will have a client ID and secret. These are used in the Authorization Grant Flow.

Getting an authorization code

The first step in the Authorization Grant Flow is to get an authorization code. That code is returned to the app by Azure when the user logs on and consents to the level of access the app requires.

First the app constructs a logon URL for the user. This URL must be opened in a browser so that the user can login and provide consent.

The base URL for logon looks like:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize

The app appends query parameters to this base URL to let Azure know what app is requesting the logon, and what permissions it is requesting.

  • client_id: the client ID generated by registering the app. This lets Azure know which app is requesting the logon.
  • redirect_uri: the location that Azure will redirect to once the user has granted consent to the app. This value must correspond to the value of Redirect URI used when registering the app.
  • response_type: the type of response the app is expecting. For the Authorization Grant Flow, this should always be code.
  • scope: a space-delimited list of access scopes that your app requires. For a full list of Outlook scopes, see Authenticate Office APIs using the "v2.0" endpoints.

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=https%3A%2F%2Foutlook.office.com%2Fmail.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.

Redirect request after successful sign in

GET  HTTP/1.1 302 Found
Location: http://localhost/myapp/?code= AwABAAAA...cZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE

The value of the code query parameter in the URL is the authorization code. The next step is to exchange that code for an access token.

Getting an access token

To get an access token, the app posts form-encoded parameters to the token request URL, which is always:

https://login.microsoftonline.com/common/oauth2/v2.0/token

The app includes the following parameters.

  • client_id: the client ID generated by registering the app.
  • client_secret: the client secret generated by registering the app.
  • code: the authorization code obtained in the prior step.
  • redirect_uri: this value must be the same as the value used in the authorization code request.
  • grant_type: the type of grant the app is using. For the Authorization Grant Flow, this should always be authorization_code.

These parameters are encoded to the application/x-www-form-urlencoded content type and sent to the token request URL.

Access token request

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AwABAAAA...cZZ6IgAA&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&client_id=<CLIENT ID>&client_secret=<CLIENT SECRET>

Azure responds with a JSON payload which includes the access token.

Access token response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "access_token":"eyJ0eXAi...b66LoPVA",
  "scope":"https://outlook.office.com/mail.read",
}

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://outlook.office.com/api/v2.0/me/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.

This results in the following request.

Mail API request for messages in the inbox

GET https://outlook.office.com/api/v2.0/me/messages?$select=Subject,From,ReceivedDateTime&$top=25&$orderby=ReceivedDateTime%20DESC

Accept: application/json
Authorization: Bearer eyJ0eXAi...b66LoPVA
X-AnchorMailbox: jason@contoso.onmicrosoft.com

Mail API Response

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages(Subject,From,DateTimeReceived)",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('jason@contoso.onmicrosoft.com')/Messages('AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABufW1UAAA=')",
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABufX4i\"",
      "Id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABufW1UAAA=",
      "Subject": "Ruby on Rails tutorial",
      "From": {
        "EmailAddress": {
          "Address": "jason@contoso.onmicrosoft.com",
          "Name": "Jason Johnston"
        }
      },
      "DateTimeReceived": "2015-01-29T20:44:53Z"
    },
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('jason@contoso.onmicrosoft.com')/Messages('AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABMirSeAAA=')",
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABSzmz4\"",
      "Id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABMirSeAAA=",
      "Subject": "Trip Information",
      "From": {
        "EmailAddress": {
          "Address": "jason@contoso.onmicrosoft.com",
          "Name": "Jason Johnston"
        }
      },
      "DateTimeReceived": "2014-12-09T21:55:41Z"
    },
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('jason@contoso.onmicrosoft.com')/Messages('AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABAblZoAAA=')",
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABzxiLG\"",
      "Id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABAblZoAAA=",
      "Subject": "Multiple attachments",
      "From": {
        "EmailAddress": {
          "Address": "jason@contoso.onmicrosoft.com",
          "Name": "Jason Johnston"
        }
      },
      "DateTimeReceived": "2014-11-19T20:35:59Z"
    },
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('jason@contoso.onmicrosoft.com')/Messages('AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAAA9x_8YAAA=')",
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAAA9yBBa\"",
      "Id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAAA9x_8YAAA=",
      "Subject": "Attachments",
      "From": {
        "EmailAddress": {
          "Address": "jason@contoso.onmicrosoft.com",
          "Name": "Jason Johnston"
        }
      },
      "DateTimeReceived": "2014-11-18T20:38:43Z"
    }
  ]
}

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.