How to: Persist metadata for the same mailbox by using roaming settings

apps for Office

Learn how to store and access data that is specific to a mailbox and a mail app, and accessible on the supported form factors.

Last modified: May 01, 2015

Applies to: apps for Office | Office Add-ins | Outlook

Learn more about supported hosts and other requirements.

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office".

In this article
Roaming settings format
Loading roaming settings
Creating or assigning a setting
Removing a setting
Additional resources

A mail app can use the RoamingSettings object to save data that is specific to the user’s mailbox. This data is accessible by only that mail app. The data is stored on the Exchange Server for that mailbox, and is accessible in subsequent Outlook sessions on all the form factors that the mail app supports.

The data in a RoamingSettings object is stored as a serialized JavaScript Object Notation (JSON) string. The following is an example of the structure, assuming there are three defined roaming settings named app_setting_name_0, app_setting_name_1, and app_setting_name_2.


A mail app typically loads roaming settings in the Office.initialize event handler. The following JavaScript code example shows how to load existing roaming settings and get the values of 2 settings, "customerName" and "customerBalance":

var _mailbox;
var _settings;
var _customerName;
var _customerBalance;

// The initialize function is required for all apps.
Office.initialize = function () {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    _customerName = _settings.get("customerName");
    _customerBalance = _settings.get("customerBalance");

    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run
        // and use the roaming settings.

Continuing with the preceding example, the following JavaScript function, setAppSetting, shows how to use the RoamingSettings.set method to set a setting named cookie with today’s date, and persist the data by using the RoamingSettings.saveAsync method to save all the roaming settings back to the Exchange Server. The set method creates the setting if the setting does not already exist, and assigns the setting to the specified value. The saveAsync method saves roaming settings asynchronously. This code sample passes a callback method, saveMyAppSettingsCallback, to saveAsync. When the asynchronous call finishes, saveMyAppSettingsCallback is called by using one parameter, asyncResult. This parameter is an AsyncResult object that contains the result of and any details about the asynchronous call. You can use the optional userContext parameter to pass any state information from the asynchronous call to the callback function.

// Set an application setting.
function setAppSetting() {
    _settings.set("cookie", Date());

// Callback method after saving custom application roaming settings.
function saveMyAppSettingsCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.

Also extending the preceding examples, the following JavaScript function, removeAppSetting, shows how to use the RoamingSettings.remove method to remove the cookie setting and save all the roaming settings back to the Exchange Server.

// Remove an application setting.
function removeAppSetting()
© 2015 Microsoft