Office 365 REST API - Mail, Calendar, Contacts Update RRS feed

  • General discussion

  • UPDATE: We have announced General Availability of our REST APIs. The refreshed documentation which covers all the changes and much more is now available here.

    I wanted to share an update on our Mail, Calendar, Contacts REST API. Over the last few months we have been heads down updating the APIs. Most of the changes are a direct result of all the great feedback that we have received from customers like you and we are very excited about sharing these changes.  These changes are starting to light up in the service and we have already received questions/comments about them from some of you.

    Some of these changes are not backward compatible.   Due to versioning not yet implemented (but coming soon!), and these API’s being in preview, they might require simple updates to your code.   Once versioning is in place, introducing non-backward compatible changes won’t impact your existing code.  Stay tuned for a full list of these changes along with the refreshed documentation and client libraries. 

    We have received a number of questions on some specific changes which I wanted to share a workaround for:

    1. Folder names after ../ews/odata/Me, such as Inbox, SentItems, DeletedItems, Drafts will additionally require a “Folders” in front of them in the URL.


    Before  :

    Now      :

    .Net code sample:

                var messageResultsBefore = await (from i in client.Me.Inbox.Messages select i).ExecuteAsync();

                var messageResultsNow = await (from i in client.Me.Folders.GetById("Inbox").Messages select i).ExecuteAsync();

    2. The Namespace has been updated from "#Microsoft.Exchange.Services.OData.Model" to “Microsoft.OutlookServices” and hence the fully qualified type names have to be updated to reflect that. In most cases though, you do not need to provide the odata.type property as we can infer it based on where you make the post. For example, if you POST to ../Me/Contacts, we know you are trying to create a contact.

    3. Contacts changes: To make the API easier to use, we have replaced EmailAddress1, EmailAddress2, EmailAddress3 with a collection of a new type called EmailAddress. We have similarly also changed BusinessPhones, HomePhones to collections.

    Sample payload showing how to create a contact with EmailAddresses and BusinessPhones:

    "GivenName": "John",  
    "EmailAddresses": [       
        "Address": "", 
        "Name": "John"
    "BusinessPhones": [

    4. Event Changes: The property Attendees now includes the type “EmailAddress”.

    Sample Event payload showing how to create an Event.

    {  "Subject": "Discuss the Calendar REST API",  "Body": {    "ContentTyp

    e": "HTML",    "Content": "I think it will meet our requirements!"  },  "Start": "2014-07-02T18:00:00Z",  "End": "2014-07-02T19:00:00Z",  "Location": {      "DisplayName": "Conference Room 1"    },  "ShowAs": "Busy",  "Attendees": [    {      "EmailAddress": { "Name":"Alex Darrow", "Address": "" },      "Type": "Required"    },    {      "EmailAddress": { "Name": "Anne Wallace", "Address": "" },      "Type": "Optional"    },    {      "EmailAddress": { "Name": "Conference Room 1", "Address": "" },      "Type": "Resource"    }  ] }

    5. We have introduced a simple API for sending email called SendMail, and have removed the custom parameter MessageDisposition which was difficult to understand and discover.

    The sendmail action, takes two parameters, a required parameter which is the Message itself and an optional parameter, "SaveToSentItems" which by default is set to true.

    Sample Request to create and send email with one call:


      "Subject": "Have you seen this new Mail REST API?",    
      "Importance": "High",    
      "Body": {      
        "ContentType": "HTML",      
        "Content": "It looks awesome!"    
      "ToRecipients": [{          
        "EmailAddress": {            
          "Name": "John Doe",            
          "Address": ""          

    If you are running into any issues please post on stackoverflow here:

    We apologize for any inconvenience and thank you for your continued feedback!


    Tuesday, October 14, 2014 5:40 PM

All replies

  • Hi, 

    I was trying to create and update the calendar event using [POST] and [PATCH]<eventId> respectively.

    When i try with poster or postman, I get this error

    {error: {code: "ErrorInvalidRequest" message: "Cannot read the request body."} }

    its not working . Any help will be appreciated.

    Note: GET events and DELETE Events are working. I think the API with payload is not working.

    Friday, January 2, 2015 7:46 AM
  • That error generally means there's a problem with your payload. Please post this in a new thread and include the payload you're using.
    Friday, January 2, 2015 2:47 PM