Outlook Add-in Roaming Settings Behaviour and Shared Mailboxes

Roaming Settings are a feature of the Office Add-in Model (Office.js) and provide a persisted storage object that your add-in can use. The Office Add-in model takes care of storing the settings and making them available as users move onto different devices or different hosts (Desktop Outlook vs Web Browser for example). This works as you would expect for the simple scenario of a user accessing their own mailbox. Where things get complicated (and undocumented) is when you introduce users having access to Shared Mailboxes or delegate access to other users mailboxes. This post walks through those scenarios to discover just how roaming settings actually work.

In a Users Mailbox

This is the simple case. I’ve created an add-in called Outlook Roaming Settings that simply allows us to Set, Get, and Save Roaming Setting values so we can test what is happening.

I’m going to use the add-in to set a roaming setting value called “MyOutlookSetting” to the value “Set in Cams mailbox”

As you would expect this is persisted. If I restart the add-in on a different mail message in Cams inbox then the value of the setting is read back out of the roaming settings. Nothing strange here, let’s move on.

In a Shared Mailbox (accessed from within Users Mailbox)

There are several ways to open/access a Shared Mailbox. I think one of the most common ways is that the Shared Mailbox appears as a secondary mailbox underneath the users mailbox. That’s the scenario depicted below. Here I’ve selected an email in the inbox of the Shared Mailbox and started the add-in. Notice that the value from the roaming setting “Set in Cams mailbox” is used here. So it appears that the roaming settings object follows me as a user if I use the add-in in my own mailbox or in the Shared Mailbox.

But hold that thought, things are about to get more complex.

In a Shared Mailbox (opening Shared Mailbox directly)

Instead of accessing the Shared Mailbox from within a users mail we will instead directly access the Shared Mailbox. You can directly open any mailbox (Shared or Delegated) that you can been granted access to. There are several ways to directly open a mailbox you have permission to. In Outlook Web Access click on your profile picture and select Open another mailbox and enter the address of the mailbox.

You can see from the URL we are in the Shared Mailbox as it contain /mail/{mailbox name} rather than just /mail.

Running the add-in we find that the Roaming Setting value that we set earlier isn’t available.

If we do set a new value for this roaming setting to “Set in Shared Mailbox”, we can restart the add-in and this value is persisted.

Returning to the users mail file (Cam) and accessing the Shared Mailbox from the left navigation we can see that it still has the original value persisted.

Ok so we’ve established that it’s a different roaming settings object in use depending on whether the Shared Mailbox is opened as a secondary account (within the users mail file) or if it have been opened directly.

Let’s probe some more. Remember how we opened the Shared Mailbox directly (as Cam) and used the add-in to set the roaming settings value? Well let’s open that Shared Mailbox directly again, but this time as a different user (Black Wiggle)

Whoa – I wasn’t expecting that. When Black Wiggle uses the add-in the roaming setting value is already populated with the value that Cam set it to when he opened the Shared Mailbox directly and used the add-in.

The roaming settings actually belong to the mailbox, NOT the user. Be very careful, these settings are not private to and are not related uniquely to the authenticated user.

The Microsoft Docs are not very clear on this and don’t cover the shared/delegate mailbox scenarios.

Conclusion

Reading the Microsoft documentation and based on the behaviour observed this is how I believe it works.

• Roaming settings are stored at the mailbox level, and it’s 1 roaming setting object per add-in.
• When the Outlook host starts up, it uses the roaming settings object of the primary (or first) mailbox that’s opened (usually this will be the users own mail file unless they have directly opened another mailbox they have access to). The roaming settings of that primary mailbox are then used across any secondary mailboxes that might appear on the left navigation.
• Roaming settings are not unique to an authenticated user, they belong to the mailbox. If multiple users open the same mailbox and it is the primary mailbox in the Outlook host, then they will be using the same roaming settings object.

Try it out yourself

The add-in I created to do this testing is publicly available in GitHub, even better because it’s so simple it is hosted directly from the GitHub repo so you can simply sideload the add-in using this manifest.xml file without having to run anything up yourself.