RoamingSettings object (JavaScript API for Office v1.1)

JavaScript API for Office v1.1

Represents custom settings for a mail app that are stored in the user's mailbox as name/value pairs.

Last modified: November 24, 2014






Retrieves the specified setting.


Removes the specified setting.


Saves the settings.


Sets or creates the specified setting.

The settings created by using the methods of the RoamingSettings object are saved per app and per user. That is, they are available only to the app that created them, and only from the user's mail box in which they are saved.

The name of a setting is a string, while the value can be a string, number, boolean, null, object, or array.

The RoamingSettings object is automatically loaded as part of the Context object, and is available by calling the roamingSettings property of that object when the app is activated. The developer is responsible for calling the saveAsync method after adding or deleting settings to save the settings in the user's mailbox.

The settings saved by using methods of the RoamingSettings object from a user's instance of a mail app are saved in the user's mailbox and are available only to that user's instance of the app. Mail apps also support the CustomProperties object, which lets you create a property bag stored with the current item. For more information, see Creating custom properties for a mail app.

App types

Mail apps

Supported clients

Outlook 2013, Outlook Web App, Outlook 2013 SP1, Outlook 2013 RT, OWA for Devices, Outlook for Mac





© 2014 Microsoft