Posted by on Nov 30, 2015 in #Office365Dev | 0 comments

Sometimes you need to store data on the Exchange item itself, i.e. an appointment or a mail. If you’re connecting any of those items to objects or events within your own service, or just extending the properties of the item – storing properties on the item itself is essential.

You could store an identifier in the subject line or the body of the item if you choose, but that would not be trivial and exposed to human errors. A user might simply remove or modify the identifier and the connection between the item and your service may be broken just like that.

A much better approach is to store these properties as a hidden property bag in the Exchange server. These properties will be specific to your Outlook add-in and the item itself, so it works out well forthese use-cases.

In order to get started, simply call the loadCustomPropertiesAsync ( function on the item object to get the property bag.

Once you have retrieved to the property bag, you can start reading and writing to it. The changes you make to the property bag will only be local, until you call the saveAsync function – which reflects the changes made locally, back to the item in the Exchange server.

Whatever you store in the property bag needs to be stored as a string, do any serialization and deserialization needed with the JSON.stringify(…) and JSON.parse(…) functions.

Getting the property bag

In an Outlook add-in, you can easily get the property bag (custom properties object) like so:

The function is asynchronous, so you’ll get it passed back via the callback function.

Saving properties

In this scenario, I’ll be saving a single JS object named “settings” to the property bag – which will contain all of the properties I need. Each of your custom properties will be stored with a property name (think of the property bag as a key/value store). If you’re dealing with a lot of data, you might want to split this up into multiple properties.

Getting the property bag (using the getCustomPropertiesAsync function) is asynchronous and based on network calls – it’s wise to be checking the status of the result before trying to process it. Things may will go wrong, so code for it!

Remember – once you make changes to the property bag, you’ll need to push them back to the Exchange server using the saveAsync function.

Getting properties

Getting the custom property is straight forward, it’s all about using the same property name (“settings” in this case) that you stored it with. If there is no property saved with that property name, undefined will be returned.


If you want to, you can test everything like I did. The code below saves and gets and object stored as a custom property using the functions above.

Make sure to run your logic after your Office.initialize function has been called and your add-in is ready.

I was given the following log in the JS console. The JS object which I created was saved and returned back from the Exchange server, pretty neat!


-Simon Jaeger