Transition your app from Live APIs to Outlook REST APIs
As you might know, we have a new v2 auth model that supports sign-on and access to Microsoft Graph and Outlook APIs for consumer, work, and school accounts. In case you missed it, here is the v2 auth model GA announcement and here is the link to the new v2 auth model protocol specs.
Together with the Outlook APIs that work for both Office 365 and Outlook.com users that have been upgraded to Office 365, this gives a very powerful story for those of you who are developing apps. When I say Outlook.com users, this also includes all other domains supported in Outlook.com such as Hotmail.com, msn.com, Live.com and so on.
The fantastic story: One single Auth and API model for both the consumers and business users!
Before the v2 app model came along, this story was not always so nice. So, I want to write about how you might get to the new fantastic story. Especially if you have an existing application that works against Outlook.com using the Live Connect APIs, Exchange Active Sync (EAS), or IMAP, and use the Live OAuth2 protocol, this blog will be of interest for you. You can use this as a starting point to transition your app from using Live APIs to using Outlook REST APIs.
First of all, there is no need to worry that your existing application will break, even if an Outlook.com user is upgraded to Office 365. IMAP and EAS protocols continue to work the same way as it worked before the upgrade.
Now, let's think about a possible transition. I broke the migration down to three stages as my simple mind has trouble remembering more than 3 distinct steps or stages :-).
Stage 1: Leave it as it is - no benefit but it just continues to work
"Doh!" you might say, but it's always good to ensure a starting point that requires no changes and understand its impact. In this stage, your application uses the LiveID OAuth2 protocol and Live APIs to run against Outlook.com mailboxes. Your application will continue to run fine even if the mailbox of the user hasn’t yet been upgraded to Office 365.
So what's the downside? Your application continues to work. However, once mailboxes are migrated to Office 365 you can't take advantage of all the rich features Office 365 provides today and plans to provide in the future. You're literally stuck with the existing functionality while all innovations in Office 365 will be out of reach for your application. You're also not able to access work or school accounts.
Stage 2: Switch the API - benefit from new Office 365 features
Now, as soon as an Outlook.com user is upgraded to Office 365, you have more options with v2 Auth model, and Outlook REST APIs. You are not constrained by the limitations of the Live SDK and can take advantage of Office 365 innovations and additional services and functionalities.
This all happens in what I call "Stage 2". In this stage, your application continues to work for Outlook.com mailboxes like before, but you start to integrate with the Outlook REST APIs for migrated mailboxes. As part of this integration, you don’t need to change the authentication protocol. Your users will not be prompted again for consent, even when they are upgraded to Office 365 (unless of course you extend your app beyond existing functionality that might require more permissions).
Take a look at the table below, it shows how the LiveID OAuth2 scopes map to the new Outlook REST API scopes that are listed in Outlook API documentation.
| LiveID OAuth2 WL scope | Outlook Rest API scope |
|---|---|
| wl.basic | User.Read, Contacts.Read |
| wl.calendars | Calendars.Read |
| wl.calendars_update | Calendars.ReadWrite |
| wl.contacts_create | Contacts.ReadWrite |
| wl.contacts_calendars | Calendars.Read |
| wl.emails | User.Read |
| wl.events_create | Calendars.ReadWrite |
| wl.imap | Mail.ReadWrite, Mail.Send |
The general pattern in this stage is that your application tries to first access the mailbox using the Outlook REST APIs. In case the user hasn’t yet been upgraded to Office 365, Outlook REST APIs will return a very specific message back to your application as a signal to use the Live APIs:
- Http Error: 404
- Error code: MailboxNotEnabledForRESTAPI
- Error message: “REST API is not yet enabled for this mailbox.”
OR
- Http Error: 404
- Error code: MailboxNotSupportedForRESTAPI
- Error message: “REST API is not yet supported for this mailbox.”
To summarize this stage was all about starting and taking advantage of the new Outlook Rest APIs, while continuing to support Outlook.com users who haven’t yet been upgraded to Office 365. However, so far your application is still bound to the consumer world. The opportunity of reaching tens of millions of business users in Office 365 is just one step away.
Stage 3: Switch the Auth model - Unleash your application to reach new horizons
In this final stage, you switch your application from using LiveID OAuth2 protocol to the new v2 Auth model OAuth2 protocol.
Now, there is a caveat: When you do this, your consumer users will be re-prompted for consent, as only the Outlook REST API scopes apply to consumer and business accounts.
However, this might be a small price to pay considering your application is now ready to transparently target Office 365 users, in addition to the users you are already servicing.
After you're done with this stage, you arrived at the point where your application can work the same way for consumer and business mailboxes, and it is also ready to take advantage of new capabilities of Office 365. It can even start integrating with the Microsoft Graph to integrate with OneDrive or other Office 365 services. The possibilities to build a much better and richer application and make it available to all Office 365 users is very exciting...in my opinion. :-)
With this said, I hope I gave a good starting point about how you can transform your application to Office 365. A big thank you for reading and as always, feedback, questions, etc. are very much appreciated!
Please use Stack Overflow for questions, and be sure to tag your post with outlook-restapi or MicrosoftGraph.
And as always, visit https://developer.microsoft.com/en-us/outlook/ for the latest and greatest news, updates, samples and reference materials on our Outlook APIs.
Thank you!
Matthias Leibmann
Comments
- Anonymous
April 12, 2016
Matthias, I have a couple of outlook.com accounts that give the "MailboxNotEnabledForRESTAPI" error. So, as I understand your blog, I should build my app for both the new and the old sets of APIs as users are being migrated. Is that correct? - Anonymous
May 15, 2016
Hi Matthias,Thanks for your blog. Had a query regarding the new api's. Using the new outlook rest api's to import contacts from outlook/hotmail email accounts. There is a minor glitch though, once the user clicks the import contacts button and the initial MS auth dialog pops up (url - login.microsoftonline.com), as soon as the user finishes entering their email address, the page suddenly redirects to login.live.com. This is bad because i) this happens without any warning (user could be in middle of entering their password for example) ii) what's the point of using the new api's if the auth is still being handled by the old live connect api endpoint.Would like to know if there is anyway to prevent this redirect from happening? Maybe I am missing some param which needs to passed in to the initial auth url? - Anonymous
July 16, 2016
Hi Matthias,Thanks for the read, I found it while searching for info on the API REST setup, I have the work flow functional and can import contacts through the new system, although like Mitch (1st comment), my main personal email is an @outlook.com and hasn't yet been migrated to allow API access; I had to setup a new email account to test and use with the service.Has Microsoft stated when they're going to complete the roll over so the API is available to all @live/hotmail/msn, etc. accounts?I feel it's wrong to roll out all this functionality for my clients, knowing that it's only going to work for some of them.Is their any fall-over that can be implemented to pick up the non-migrated accounts?In my new website, customers will be forwarding links to their friends to help further promote our site... so doing us a favour by even clicking the share via Outlook.com link; I don't want to reward them with an error screen 'sorry, but you can't do that'.Thanks for your time,Anthony- Anonymous
August 02, 2016
Thanks for your interest Anthony! We do not have a specified date for completion of the migration. The fallback for non-migrated accounts would be the Live SDK.
- Anonymous
- Anonymous
August 30, 2016
Hi Matthias, Could you possibly point me to a sample to show how to create a weblink to set up an internet calendar subscription. In the old outlook.com model, I would usehttp://calendar.live.com/calendar/calendar.aspx?rru=addsubscription&url=ICAL_SUBSCRIPTION_URL&name=YOUR_CALENDAR_NAME and from what I understand now, I need to use a new API but I cannot find any documentation on this. Yet in O365 Calendar, the option for "Add Calendar, From Internet" is clearly there and working.I don't go poking around the documentation on APIs very often. It is pretty overwhelming.