| title | description | ms.date | localization_priority |
|---|---|---|---|
Enable shared folders and shared mailbox scenarios in an Outlook add-in |
Discusses how to configure add-in support for shared folders (a.k.a. delegate access) and shared mailboxes. |
07/02/2021 |
Normal |
This article describes how to enable shared folders (also known as delegate access) and shared mailbox (now in preview) scenarios in your Outlook add-in, including which permissions the Office JavaScript API supports.
Important
Support for this feature was introduced in requirement set 1.8. See clients and platforms that support this requirement set.
The following sections describe supported configurations for shared mailboxes (now in preview) 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.
The mailbox owner must first provide access to a delegate. The delegate must then follow the instructions outlined in the "Add another person's mailbox to your profile" section of the article Manage another person's mail and calendar items.
Exchange server admins can create and manage shared mailboxes for sets of users to access. At present, Exchange Online is the only supported server version for this feature.
An Exchange Server feature known as "automapping" is on by default which means that subsequently the shared mailbox should automatically appear in a user's Outlook app after Outlook has been closed and reopened. However, if an admin turned off automapping, the user must follow the manual steps outlined in the "Add a shared mailbox to Outlook" section of the article Open and use a shared mailbox in Outlook.
Warning
Do NOT sign into the shared mailbox with a password. The feature APIs won't work in that case.
The mailbox owner must first provide access to a delegate by updating the mailbox folder permissions. The delegate must then follow the instructions outlined in the "Add another person’s mailbox to your folder list in Outlook Web App" section of the article Access another person's mailbox.
Exchange server admins can create and manage shared mailboxes for sets of users to access. At present, Exchange Online is the only supported server version for this feature.
After receiving access, a shared mailbox user must follow the steps outlined in the "Add the shared mailbox so it displays under your primary mailbox" section of the article Open and use a shared mailbox in Outlook on the web.
Warning
Do NOT use other options like "Open another mailbox". The feature APIs may not work properly then.
To learn more about where add-ins do and do not activate in general, refer to the Mailbox items available to add-ins section of the Outlook add-ins overview page.
The following table describes the permissions that the Office JavaScript API supports for delegates and shared mailbox users.
| Permission | Value | Description |
|---|---|---|
| Read | 1 (000001) | Can read items. |
| Write | 2 (000010) | Can create items. |
| DeleteOwn | 4 (000100) | Can delete only the items they created. |
| DeleteAll | 8 (001000) | Can delete any items. |
| EditOwn | 16 (010000) | Can edit only the items they created. |
| EditAll | 32 (100000) | Can edit any items. |
Note
Currently the API supports getting existing permissions, but not setting permissions.
The DelegatePermissions object 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. You can see an example of how to check for a specific permission in the Perform an operation as delegate or shared mailbox user section later in this article.
A delegate's updates to the owner's mailbox are usually synced across mailboxes immediately.
However, if REST or Exchange Web Services (EWS) operations were used to set an extended property on an item, such changes could take a few hours to sync. We recommend you instead use the CustomProperties object and related APIs to avoid such a delay. To learn more, see the custom properties section of the "Get and set metadata in an Outlook add-in" article.
Important
In a delegate scenario, you can't use EWS with the tokens currently provided by office.js API.
To enable shared folders and shared mailbox scenarios in your add-in, you must set the SupportsSharedFolders element to true in the manifest under the parent element DesktopFormFactor. At present, other form factors are not supported.
To support REST calls from a delegate, set the Permissions node in the manifest to ReadWriteMailbox.
The following example shows the SupportsSharedFolders element set to true in a section of the manifest.
...
<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 selected extension point -->
</ExtensionPoint>
<!-- You can define more than one ExtensionPoint element as needed -->
</DesktopFormFactor>
</Host>
</Hosts>
...
</VersionOverrides>
</VersionOverrides>
...You can get an item's shared properties in Compose or Read mode by calling the item.getSharedPropertiesAsync method. This returns a SharedProperties object that currently provides the user's permissions, the owner's email address, the REST API's base URL, and the target mailbox.
The following example shows how to get the shared properties of a message or appointment, check if the delegate or shared mailbox user has Write permission, and make a REST call.
function performOperation() {
Office.context.mailbox.getCallbackTokenAsync({
isRest: true
},
function (asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value !== "") {
Office.context.mailbox.item.getSharedPropertiesAsync({
// Pass auth token along.
asyncContext: asyncResult.value
},
function (asyncResult1) {
let sharedProperties = asyncResult1.value;
let delegatePermissions = sharedProperties.delegatePermissions;
// Determine if user can do the expected operation.
// E.g., do they have Write permission?
if ((delegatePermissions & Office.MailboxEnums.DelegatePermissions.Write) != 0) {
// Construct REST URL for your operation.
// Update <version> placeholder with actual Outlook REST API version e.g. "v2.0".
// Update <operation> placeholder with actual operation.
let rest_url = sharedProperties.targetRestUrl + "/<version>/users/" + sharedProperties.targetMailbox + "/<operation>";
$.ajax({
url: rest_url,
dataType: 'json',
headers:
{
"Authorization": "Bearer " + asyncResult1.asyncContext
}
}
).done(
function (response) {
console.log("success");
}
).fail(
function (error) {
console.log("error message");
}
);
}
}
);
}
}
);
}Tip
As a delegate, you can use REST to get the content of an Outlook message attached to an Outlook item or group post.
If you want to call a REST operation on an item, whether or not the item is shared, you can use the getSharedPropertiesAsync API to determine if the item is shared. After that, you can construct the REST URL for the operation using the appropriate object.
if (item.getSharedPropertiesAsync) {
// In Windows, Mac, and the web client, this indicates a shared item so use SharedProperties properties to construct the REST URL.
// Add-ins don't activate on shared items in mobile so no need to handle.
// Perform operation for shared item.
} else {
// In general, this is not a shared item, so construct the REST URL using info from the Call REST APIs article:
// https://docs.microsoft.com/office/dev/add-ins/outlook/use-rest-api
// Perform operation for non-shared item.
}Depending on your add-in's scenarios, there are a few limitations for you to consider when handling shared folder or shared mailbox situations.
In Message Compose mode, getSharedPropertiesAsync is not supported in Outlook on the web or on Windows unless the following conditions are met.
a. Delegate access/Shared folders
- The mailbox owner starts a message. This can be a new message, a reply, or a forward.
- They save the message then move it from their own Drafts folder to a folder shared with the delegate.
- The delegate opens the draft from the shared folder then continues composing.
b. Shared mailbox
- A shared mailbox user starts a message. This can be a new message, a reply, or a forward.
- They save the message then move it from their own Drafts folder to a folder in the shared mailbox.
- Another shared mailbox user opens the draft from the shared mailbox then continues composing.
The message is now in a shared context and add-ins that support these shared scenarios can get the item's shared properties. After the message has been sent, it's usually found in the sender's Sent Items folder.
Your add-in can use REST and the add-in's permission must be set to ReadWriteMailbox to enable REST access to the owner's mailbox or to the shared mailbox as applicable. EWS is not supported.
User or shared mailbox hidden from an address list
If an admin hid a user or shared mailbox address from an address list like 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.