Old behavior

HTTP/1.1 503 Service Unavailable

{
  "error": {
    "code": "MailboxInfoStale",
    "message": "Mailbox info is stale."
  }
}

New behavior

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "ErrorIncorrectRoutingHint",
    "message": "The x-anchor mailbox 'jason@contoso.com' does not match the target of the request."
  }
}

Handling the error

GET https://outlook.office.com/api/v2.0/me

{
  "Id": "3c7f0e3a-623b-85ae-4032-07d41531beff@7aeb6117-c342-4861-bec7-f8803ae85e41",
  "EmailAddress": "jason@contoso.onmicrosoft.com",
  "DisplayName": "Jason Johnston",
  "Alias": "jason",
  "MailboxGuid": "fece2b65-3577-4972-bf3d-5594fc9c9f9e"
}

GET https://outlook.office.com/api/v2.0/me/messages

X-AnchorMailbox: fece2b65-3577-4972-bf3d-5594fc9c9f9e

Limitations

• You cannot use Exchange Web Services (EWS) to access items in the Gmail mailbox. This means that you cannot use makeEwsRequestAsync or use an EWS callback token from getCallbackTokenAsync to make EWS calls directly. Instead, you can get the same type of access to the items in the mailbox by using the Outlook REST APIs.
• You cannot get a single-sign-on token using getAccessTokenAsync. Instead, you can use the Exchange identity token.

New API features

Note: This property is currently only implemented in Outlook 2016 for Mac.

Get access to the preview

Call to action

Rules

Get inbox rules

Create inbox rule

Categories

Get master category list

Create category

Message headers

Get message headers

Meeting rooms

Get room lists

Get rooms

Time zones

Languages

Try these new APIs out today, either in your code, or on the Outlook OAuth Sandbox. Leave feedback on these new APIs on UserVoice.

Meeting rooms

One of the top-requested features for the Outlook REST API was the ability to list meeting rooms in an organziation. We've added the ability to find both rooms and room lists.

Get room lists

Request

GET https://outlook.office.com/api/beta/me/findroomlists

Response

{
  "value": [
    {
      "Name": "Building 1 Rooms",
      "Address": "Building1Rooms@contoso.onmicrosoft.com"
    },
    {
      "Name": "Building 2 Rooms",
      "Address": "Building2Rooms@contoso.onmicrosoft.com"
    }
  ]
}

Get rooms

Request (all rooms)

GET https://outlook.office.com/api/beta/me/findrooms

Request (rooms in a room list)

GET https://outlook.office.com/api/beta/me/findrooms(roomlist='Building1Rooms@contoso.onmicrosoft.com')

Response

{
  "value": [
    {
      "Name": "Conf Room Adams",
      "Address": "Adams@contoso.onmicrosoft.com"
    },
    {
      "Name": "Conf Room Crystal",
      "Address": "Crystal@contoso.onmicrosoft.com"
    },
    {
      "Name": "Conf Room Stevens",
      "Address": "Stevens@contoso.onmicrosoft.com"
    }
  ]
}

Time zones

The API has support for specifying a time zone via the Prefer header to get back date times in the requested time zone. However, figuring out which time zones are supported has been a little tricky. Now, apps can request a list of all supported time zones from the server, in either Windows or IANA format.

Request

GET https://outlook.office.com/api/beta/me/SupportedTimeZones(TimeZoneStandard='Windows')

Response

{
  "value": [
    {
      "Alias": "Dateline Standard Time",
      "DisplayName": "(UTC-12:00) International Date Line West"
    },
    {
      "Alias": "Samoa Standard Time",
      "DisplayName": "(UTC+13:00) Samoa"
    },
    {
      "Alias": "UTC-11",
      "DisplayName": "(UTC-11:00) Coordinated Universal Time-11"
    },
    {
      "Alias": "Aleutian Standard Time",
      "DisplayName": "(UTC-10:00) Aleutian Islands"
    },
    ...
  ]
}

Languages

You can also request a list of supported languages from the server.

Request

GET https://outlook.office.com/api/beta/me/SupportedLanguages

Response

{
  "value": [
    {
      "Locale": "af-ZA",
      "DisplayName": "Afrikaans (Suid-Afrika)"
    },
    {
      "Locale": "am-ET",
      "DisplayName": "አማርኛ (ኢትዮጵያ)"
    },
    {
      "Locale": "ar-AE",
      "DisplayName": "العربية (الإمارات العربية المتحدة)"
    },
    {
      "Locale": "ar-BH",
      "DisplayName": "العربية (البحرين)"
    },
    ...
  ]
}

Learn about the Outlook platform

Collaborative documentation

• A Locations property as part of the Event resource
• A LocationType property to the Location complex type, with an enumeration of possible locations types

Note: These are schema additions and the existing Location property that represents a single location for an event has not been removed, to allow for an easier transition. If your REST client is already using Location, your client doesn't break. However, be aware that in the future, the Location property will be removed, and apps will need to be updated.

<EntityType Name="Event" BaseType="Microsoft.OutlookServices.Item">
    ...
    <Property Name="Start" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
    <Property Name="OriginalStart" Type="Edm.DateTimeOffset" />
    <Property Name="End" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
    <Property Name="Location" Type="Microsoft.OutlookServices.Location" />
    <Property Name="Locations" Type="Collection(Microsoft.OutlookServices.Location)" />
    <Property Name="Start" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
    <Property Name="OriginalStart" Type="Edm.DateTimeOffset" />
    <Property Name="End" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
    ...
</EntityType>

<ComplexType Name="Location">
    <Property Name="DisplayName" Type="Edm.String" />
    <Property Name="LocationEmailAddress" Type="Edm.String" />
    <Property Name="Address" Type="Microsoft.OutlookServices.PhysicalAddress" />
    <Property Name="Coordinates" Type="Microsoft.OutlookServices.GeoCoordinates" />
    <Property Name="LocationUri" Type="Edm.String" />
    <Property Name="LocationType" Type="Microsoft.OutlookServices.LocationType" />
</ComplexType>

<EnumType Name="LocationType">
    <Member Name="Default" Value="0" />
    <Member Name="ConferenceRoom" Value="1" />
    <Member Name="HomeAddress" Value="2" />
    <Member Name="BusinessAddress" Value="3" />
    <Member Name="GeoCoordinates" Value="4" />
    <Member Name="StreetAddress" Value="5" />
    <Member Name="Hotel" Value="6" />
    <Member Name="Restaurant" Value="7" />
    <Member Name="LocalBusiness" Value="8" />
    <Member Name="PostalAddress" Value="9" />
</EnumType>

Using multiple locations and location types in the Outlook Rest API

Get events

GET https://outlook.office.com/api/beta/me/events?$select=Subject,Organizer,Start,End,Locations,Location

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events(Subject,Organizer,Start,End,Locations,Location)",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI28tEyDAAA=')",
      "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAA/LpDWw==\"",
      "Id": "AAMkAGI28tEyDAAA=",
      "Subject": "Scrum",
      "Start": {
        "DateTime": "2017-11-28T08:00:00",
        "TimeZone": "Pacific Standard Time"
      },
      "End": {
        "DateTime": "2017-11-28T09:00:00",
        "TimeZone": "Pacific Standard Time"
      },
      "Organizer": {
        "EmailAddress": {
          "Name": "Adele Vance",
          "Address": "adelev@contoso.onmicrosoft.com"
        }
      },
      "Location": {
        "DisplayName": "Conf Room 3; Fourth Coffee; Home Office",
        "LocationType": "Default"
      },
      "Locations": [
        {
          "DisplayName": "Conf Room 3",
          "LocationType": "ConferenceRoom"
        },
        {
          "DisplayName": "Fourth Coffee",
          "Address": {
            "Street": "4567 Main St",
            "City": "Redmond",
            "State": "WA",
            "CountryOrRegion": "US",
            "PostalCode": "32008"
          },
          "Coordinates": {
            "Latitude": 47.672,
            "Longitude": -102.103
          },
          "LocationType": "LocalBusiness"
        },
        {
          "DisplayName": "Home Office",
          "LocationType": "Default"
        }
      ]
    }
  ]
}

Create an event with multiple locations

POST https://outlook.office.com/api/beta/me/events
Content-Type: application/json

{
  "Subject": "Discuss the Event in Multiple Locations REST API",
  "Start": {
    "DateTime": "2017-06-06T08:00:00",
    "TimeZone": "Pacific Standard Time"
  },
  "End": {
    "DateTime": "2017-06-06T09:00:00",
    "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "janets@contoso.onmicrosoft.com",
        "Name": "Janet Schorr"
      },
      "Type": "Required"
    }
  ],
  "Locations": [
    {
      "DisplayName": "Conf Room 3",
      "LocationType": "ConferenceRoom"
    },
    {
      "DisplayName": "Fourth Coffee",
      "Address": {
        "Street": "4567 Main St",
        "City": "Redmond",
        "State": "WA",
        "CountryOrRegion": "US",
        "PostalCode": "32008"
      },
      "Coordinates": {
        "Latitude": 47.672,
        "Longitude": -102.103
      },
      "LocationType": "LocalBusiness"
    }
  ]
}

Update an event with multiple locations

PATCH https://outlook.office.com/api/beta/me/events/{event-id}
Content-Type: application/json

{
  "Locations": [
    {
      "DisplayName": "Conf Room 3",
      "LocationType": "ConferenceRoom"
    },
    {
      "DisplayName": "Fourth Coffee",
      "Address": {
        "Street": "4567 Main St",
        "City": "Redmond",
        "State": "WA",
        "CountryOrRegion": "US",
        "PostalCode": "32008"
      },
      "Coordinates": {
        "Latitude": 47.672,
        "Longitude": -102.103
      },
      "LocationType": "LocalBusiness"
    },
    {
      "DisplayName": "Conf Room 2 (New York)",
      "LocationType": "ConferenceRoom"
    }
  ]
}

Behavior with Location property

Read

Write

What's the limit?

What APIs are subject to this limit?

Outlook APIs

• Mail API
• Calendar API
• Contacts API
• Tasks API
• People API
• Photo API

Microsoft Graph

• User resources
• Photo resources
• Mail resources
• Calendar resources (users and groups)
• Contact resources
• Attachment resources
• Group conversations
• People and social resources

Can I track my usage?

Note: Only the Outlook REST API endpoints return these rate limit tracking headers. The Microsoft Graph endpoint does not return these headers.

What happens if my app exceeds the limit?

How do I avoid being throttled?

• Increasing page size: Using the $top parameter to increase the number of items returned per page when requesting a set of items. The default page size if the $top parameter is omitted is 10, which isn't very efficient if you're requesting a large number of items. You can increase this limit up to 1000.
• Reduce number of GET for single items: As much as possible, get the data your app needs from lists (such as GET /me/messages) rather than requesting each individual entity (such as GET /me/messages/{message-id}). Using the $select parameter to request the fields your app needs can help you control what data is returned back in lists.

Call to action

Updating the manifest

<Control xsi:type="Button" id="Contoso.Button0">
  <Label resid="residTaskpaneButton"></Label>
  <Tooltip>
    <Title resid="residTipTitle"></Label>
    <Description resid="residTipDescription"></Label>
  </Tooltip>

  <Icon>
    <bt:Image size="16" resid="functionIcon" />     
    <bt:Image size="32" resid="functionIcon" />
    <bt:Image size="80" resid="functionIcon" />
  </Icon>

  <Action xsi:type="ShowTaskPane">
    <SourceLocation resid="residTaskpaneUrl"/>
    <SupportsPinning>true</SupportsPinning>
  </Action>
</Control>

Registering for the ItemChanged Event

Office.context.mailbox.addHandlerAsync(
  Office.EventType.ItemChanged,
  function(eventArgs) {
    // This is the event handler. Do something here.
  },
  function(asyncResult) {
    // This is callback for addHandlerAsync. This will be called ONCE when the event is registered.
  }
);