Building Taskwillow with Microsoft Outlook REST API

There is much more to the API than what meets the eye

Image for post
Image for post
https://www.taskwillow.com

In building Taskwillow, I was faced with an interesting challenge. I wanted Taskwillow to remind me to respond to emails that were important.

But, at the same time , I also wanted Taskwillow to NOT remind me about emails that I had already responded to.

It was simple, I thought. I was integrating with Microsoft’s robust and secure REST API — of course, the API would expose a property that will tell me if an email was replied to.

Nope.

The Message Collection exposed by Microsoft Outlook REST API returns an array of messages (or emails ) from your inbox had every imaginable property that one could need, but the one property that would tell me — whether or not a certain message had been replied to — was nowhere in sight.

I knew it had to be there lurking somewhere in the docs…how else could my outlook client API mark an email as replied to ?

Before we get into the weeds here, let us all get a few things in order.

Interacting with the Microsoft REST API — the basics

To be able to send requests to the api and receive a response, an app must be recognized and authorized by Microsoft REST API. I am not going to go into details on how to connect and authorize an app with Microsoft — because here is a great tutorial from Microsoft for NodeJS.

Build Node.js Express apps with Microsoft Graph.

Another great way to interact with APIs is Postman. This thing makes it really easy to learn, test and play around with APIs but more importantly, helps you plan how to handle a response from an API. Just like an app, however, Postman should also be set up and authorized first before it can send and receive API requests/responses. here’s how.

Using Postman with the Microsoft Graph API

So I set up Postman and tested the API. I wanted to poll the top 10 emails in my inbox, with the size of any email not exceeding 500KB.

Here’s the api request for that.

My hope was that the response will contain the top 10 emails in my inbox and each email will have all the required properties — one of which will be a flag that will tell me whether or not the email in question had been replied to.

But upon seeing the response from the API below, I couldn't find a flag that would let me do what I wanted to do.

So how was my outlook email client doing it?

Image for post
Image for post
here again..

Enter Outlook Extended Properties REST API

After some looking, I learnt about Outlook’s Extended Properties REST API — which basically exposes, in a ‘not so easy to understand’ way, a LOT of properties that the regular REST API doesn’t expose. You can learn about the Extended properties here.

Remember, I am looking for a flag /property that will help me figure out if an email has been replied to.

Ok, so with the Extended Properties REST API there is a lot going on — but it basically boils down to this. The extended properties enable you to request for additional (or extended) properties along with the regular API request like the one that we made earlier.

In other words, you can ask MS Outlook API to expand the usual response and return additional properties like the one below.

The API call above requests Microsoft API to return the following

  1. The top 10 emails from the logged in users inbox
  2. For each email, expand the response to return an additional property called “SingleValueExtendedProperties”
  3. but more specifically when returning the SingleValueExtendedProperties, only return the one with Id Integer 0x1081.

Understanding #3 above is what is key here.

You see there are many extended properties that are available with an email message — including a property called PidTagLastVerbExecuted Property — which identifies the last verb executed for the message item — or in other words, displays the last operation performed on an email message. This is the property what we need.

We are getting close….

Here’s the response that we receive when we request the above API call.

As you can see, there is a new JSON block called singleValueExtendedProperties@odata.context. This JSON block has a property “id(Integer ) 0x1081” which is basically the property we are looking for — the PidTagLastVerbExecuted property.

As you can see — the value of this property is 103. What does the Value 103 mean?

Boom! its the ReplyToAll property — which means this particular email was responded to. 🎉🎉.

PidTagLastVerbExecuted, in fact, can give you any action that has been taken on an outlook email message. You can find the action and the corresponding values in the message here.

So there we go. This property is what Taskwillow uses to identify emails that it no longer needs to remind you about.

Thanks for reading! If you want to receive these articles straight to your inbox just subscribe to my newsletter below.

Written by

Building Taskwillow. Notes about building things and selling them. Sometimes other stuff too. I am on Twitter @chakrvyuh.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store