Implement shared folders and shared mailbox scenarios in an Outlook add-in

This article describes how to implement shared folders (also known as delegate access) and shared mailbox scenarios in your Outlook add-in, including which permissions the Office JavaScript API supports.

Supported clients and platforms

The following table shows supported client-server combinations for this feature, including the minimum required Cumulative Update where applicable. Excluded combinations aren't supported.

Supported setups

The following sections describe supported configurations for shared mailboxes and shared folders. The feature APIs may not work as expected in other configurations. Select the platform you'd like to learn how to configure.

To learn more about where add-ins do and don't activate in general, refer to the Mailbox items available to add-ins section of the Outlook add-ins overview page.

Configure the manifest

To implement shared folders and shared mailbox scenarios in your add-in, you must first configure support for the feature in your manifest. The markup varies depending on the type of manifest your add-in uses.

"authorization": {
  "permissions": {
    "resourceSpecific": [
      ...
      {
        "name": "Mailbox.SharedFolder",
        "type": "Delegated"
      },
    ]
  }
},

...
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    ...
    <Hosts>
      <Host xsi:type="MailHost">
        <DesktopFormFactor>
          <SupportsSharedFolders>true</SupportsSharedFolders>
          <FunctionFile resid="residDesktopFuncUrl" />
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <!-- Configure the extension point. -->
          </ExtensionPoint>
          ...
        </DesktopFormFactor>
      </Host>
    </Hosts>
    ...
  </VersionOverrides>
</VersionOverrides>
...

Identify if a folder or mailbox is shared

Before you can run operations in a shared folder or shared mailbox, you must first identify whether the current folder or mailbox is shared. To determine this, call Office.context.mailbox.item.getSharedPropertiesAsync on a message or appointment in compose or read mode. If the item is in a shared folder or shared mailbox, the method returns a SharedProperties object that provides the user's permissions, the owner's email address, the REST API's base URL, and the location of the target mailbox.

The following example calls the getSharedPropertiesAsync method to identify the owner of the mailbox and the permissions of the delegate or shared mailbox user.

Office.context.mailbox.item.getSharedPropertiesAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error("The current folder or mailbox isn't shared.");
    return;
  }
  const sharedProperties = result.value;
  console.log(`Owner: ${sharedProperties.owner}`);
  console.log(`Permissions: ${sharedProperties.delegatePermissions} `);
});

Supported permissions

The following table describes the permissions that getSharedPropertiesAsync supports for delegates and shared mailbox users.

The DelegatePermissions enum returned by the delegatePermissions property is implemented using a bitmask to indicate the permissions. Each position in the bitmask represents a particular permission and if it's set to 1, then the user has the respective permission. For example, if the second bit from the right is 1, then the user has Write permission.

Perform an operation as a delegate or shared mailbox user

Once you've identified that the current mail item is in a shared folder or shared mailbox, your add-in can then perform the necessary operations on the item within the shared environment. To run operations on an item in a shared context, you must first configure your add-in's permission in the manifest. Then, use Microsoft Graph to complete the operations.

Configure the add-in's permissions

To use Microsoft Graph services, an add-in must configure the read/write mailbox permission in its manifest. The markup varies depending on the type of manifest your add-in uses.

• Unified manifest for Microsoft 365: Set the "name" property of an object in the "authorization.permissions.resourceSpecific" array to "Mailbox.ReadWrite.User".
• Add-in only manifest: Set the Permissions element to ReadWriteMailbox.

Use Microsoft Graph

To implement your shared folder and shared mailbox scenarios, use Microsoft Graph to access additional mailbox information and resources. For example, you can use Microsoft Graph to get the contents of an Outlook message that's attached to a message in a mailbox where a user has delegate access. For guidance on how to use Microsoft Graph, see Overview of Microsoft Graph and Outlook mail API in Microsoft Graph.

Limitations

Depending on your add-in's scenarios, there are a few limitations for you to consider when handling shared folder or shared mailbox situations.

Message Compose mode

In Message Compose mode, getSharedPropertiesAsync isn't supported in Outlook on the web or on Windows (new and classic) unless the following conditions are met.

• Delegate access/Shared folders

  1. The mailbox owner starts a message. This can be a new message, a reply, or a forward.
  2. They save the message then move it from their own Drafts folder to a folder shared with the delegate.
  3. The delegate opens the draft from the shared folder then continues composing.

• Shared mailbox (applies to classic Outlook on Windows only)

  1. A shared mailbox user starts a message. This can be a new message, a reply, or a forward.
  2. They save the message then move it from their own Drafts folder to a folder in the shared mailbox.
  3. Another shared mailbox user opens the draft from the shared mailbox then continues composing.

Once these conditions are met, the message becomes available in a shared context and add-ins that support these shared scenarios can get the item's shared properties. After the message is sent, it's usually found in the Sent Items folder of the sender's personal mailbox.

User or shared mailbox hidden from an address list

If an admin hid a user or shared mailbox address from an address list, such as the global address list (GAL), affected mail items opened in the mailbox report Office.context.mailbox.item as null. For example, if the user opens a mail item in a shared mailbox that's hidden from the GAL, Office.context.mailbox.item representing that mail item is null.

Sync across shared folder clients

A delegate's updates to the owner's mailbox are usually synced across mailboxes immediately. However, if Microsoft Graph operations were used to set an extended property on an item, such changes could take some time to sync. To avoid a delay, we recommend you instead use the CustomProperties object and related APIs. To learn more, see the "Custom data per item in a mailbox: custom properties" section of Get and set metadata in an Outlook add-in.

See also

• Allow someone else to manage your mail and calendar
• Calendar sharing in Microsoft 365
• Add a shared mailbox to Outlook
• Overview of Microsoft Graph