office.roamingsettings.yml

### YamlMime:TSType
name: Office.RoamingSettings
uid: 'outlook!Office.RoamingSettings:interface'
package: outlook!
fullName: Office.RoamingSettings
summary: >-
  The settings created by using the methods of the `RoamingSettings` object are saved per add-in and per user. That is,
  they are available only to the add-in that created them, and only from the user's mailbox in which they are saved.


  While the Outlook add-in API limits access to these settings to only the add-in that created them, these settings
  shouldn't be considered secure storage. They can be accessed by Exchange Web Services or Extended MAPI. They shouldn't
  be used to store sensitive information, such as user credentials or security tokens.


  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 accessible via the `roamingSettings` property in the `Office.context` namespace.


  To learn more about `RoamingSettings`<!-- -->, see [Get and set add-in metadata for an Outlook
  add-in](https://learn.microsoft.com/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in)<!-- -->.
remarks: >-
  \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


  **Important**:


  - The `RoamingSettings` object is initialized from the persisted storage only when the add-in is first loaded. For
  task panes, this means that it's only initialized when the task pane first opens. If the task pane navigates to
  another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has
  persisted changes. The persisted changes will not be available until the task pane (or item in the case of UI-less
  add-ins) is closed and reopened.


  - When set and saved through Outlook on Windows
  ([new](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) or classic) or on Mac, these
  settings are reflected in Outlook on the web only after a browser refresh.


  **[Minimum permission
  level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!-- -->**:
  **restricted**


  **[Applicable Outlook
  mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!-- -->**:
  Compose or Read
isPreview: false
isDeprecated: false
type: interface
methods:
  - name: get(name)
    uid: 'outlook!Office.RoamingSettings#get:member(1)'
    package: outlook!
    fullName: get(name)
    summary: Retrieves the specified setting.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **restricted**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: Compose or Read


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml


      const settingName = $("#settingName").val();

      const settingValue = Office.context.roamingSettings.get(settingName);

      $("#settingValue").val(settingValue);

      console.log(`The value of setting "${settingName}" is "${settingValue}".`);

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'get(name: string): any;'
      parameters:
        - id: name
          description: The case-sensitive name of the setting to retrieve.
          type: string
      return:
        type: any
        description: 'Type: String \| Number \| Boolean \| Object \| Array'
  - name: remove(name)
    uid: 'outlook!Office.RoamingSettings#remove:member(1)'
    package: outlook!
    fullName: remove(name)
    summary: Removes the specified setting.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **restricted**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: Compose or Read
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'remove(name: string): void;'
      parameters:
        - id: name
          description: The case-sensitive name of the setting to remove.
          type: string
      return:
        type: void
        description: ''
  - name: saveAsync(callback)
    uid: 'outlook!Office.RoamingSettings#saveAsync:member(1)'
    package: outlook!
    fullName: saveAsync(callback)
    summary: >-
      Saves the settings.


      Any settings previously saved by an add-in are loaded when it's initialized, so during the lifetime of the session
      you can just use the set and get methods to work with the in-memory copy of the settings property bag. When you
      want to persist the settings so that they're available the next time the add-in is used, use the `saveAsync`
      method.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **restricted**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: Compose or Read


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml


      // Save settings in the mailbox to make it available in future sessions.

      Office.context.roamingSettings.saveAsync(function(result) {
        if (result.status !== Office.AsyncResultStatus.Succeeded) {
          console.error(`Action failed with message ${result.error.message}`);
        } else {
          console.log(`Settings saved with status: ${result.status}`);
        }
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'saveAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;'
      parameters:
        - id: callback
          description: >-
            Optional. When the method completes, the function passed in the `callback` parameter is called with a single
            parameter of type `Office.AsyncResult`<!-- -->.
          type: '(asyncResult: <xref uid="office!Office.AsyncResult:interface" />&lt;void&gt;) =&gt; void'
      return:
        type: void
        description: ''
  - name: 'set(name, value)'
    uid: 'outlook!Office.RoamingSettings#set:member(1)'
    package: outlook!
    fullName: 'set(name, value)'
    summary: >-
      Sets or creates the specified setting.


      The `set` method creates a new setting of the specified name if it doesn't already exist, or sets an existing
      setting of the specified name. The value is stored in the document as the serialized JSON representation of its
      data type.


      A maximum of 32KB is available for the settings of each add-in. An error with code 9057 is thrown when that size
      limit is exceeded.


      Any changes made to settings using the `set` method will not be saved to the server until the `saveAsync` method
      is called.
    remarks: >-
      \[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]


      **[Minimum permission
      level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
      -->**: **restricted**


      **[Applicable Outlook
      mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
      -->**: Compose or Read


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml


      const settingName = $("#settingName").val();

      const settingValue = $("#settingValue").val();

      Office.context.roamingSettings.set(settingName, settingValue);

      console.log(`Setting "${settingName}" set to value "${settingValue}".`);

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'set(name: string, value: any): void;'
      parameters:
        - id: name
          description: The case-sensitive name of the setting to set or create.
          type: string
        - id: value
          description: Specifies the value to be stored.
          type: any
      return:
        type: void
        description: ''