# Shared Outlook folders Source: https://developer.nylas.com/docs/provider-guides/microsoft/shared-folders/ > **Info:** > **As of January 2023, Microsoft has renamed "Office 365" to "Microsoft 365"**. For more information, see [Microsoft's official FAQs](https://www.microsoft.com/en-us/microsoft-365/business/microsoft-365-frequently-asked-questions). Microsoft Outlook allows users to share folders with other people in their organization. This page explains how to share Outlook folders and how to access folders that have been shared with you using the Nylas API. ## Before you begin To work with shared folders in Nylas, you need: - A Microsoft 365 account with folder sharing permissions - A Nylas grant with the appropriate scopes for accessing shared folders - The email address or grant ID of the person who shared the folder ## Required scopes To access shared folders, you must request one of the following Microsoft scopes when authenticating: - **`Mail.Read.Shared`**: Read-only access to shared folders - **`Mail.ReadWrite.Shared`**: Read and write access to shared folders These scopes allow your application to access folders that have been shared with the authenticated user. For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/). > **Info:** > **The `Mail.Read.Shared` and `Mail.ReadWrite.Shared` scopes are Microsoft-specific**. They work alongside the standard `Mail.Read` and `Mail.ReadWrite` scopes to provide access to shared resources. ## Share folders in Microsoft Outlook Before you can access a shared folder through Nylas, the folder owner must share it with you in Microsoft Outlook. The process varies depending on whether you're using Outlook on the web or the desktop application. ### Share a folder in Outlook on the web 1. Sign in to [Outlook on the web](https://outlook.office.com). 2. Right-click the folder you want to share in the folder list. 3. Select **Permissions** or **Share folder**. 4. Enter the email address of the person you want to share the folder with. 5. Select the permission level (for example, **Reviewer**, **Editor**, or **Owner**). 6. Click **Share**. ### Share a folder in Outlook desktop 1. Open Outlook desktop application. 2. Right-click the folder you want to share in the folder list. 3. Select **Properties**. 4. Go to the **Permissions** tab. 5. Click **Add** and enter the email address of the person you want to share the folder with. 6. Select the permission level and click **OK**. For more information about sharing folders in Microsoft Outlook, see [Microsoft's documentation](https://support.microsoft.com/en-us/office/share-an-outlook-calendar-or-folder-with-other-people-353ed2c1-3d5c-4b9e-a5f8-7d78287af2e7). ## View shared folders in Outlook (optional) > **Info:** > **Viewing shared folders in the Outlook UI is optional**. You don't need to import or add shared folders in Outlook to access them through the Nylas API. As long as the folder has been shared with you and your grant has the appropriate scopes (`Mail.Read.Shared` or `Mail.ReadWrite.Shared`), you can access shared folders directly through the API. If you want to view shared folders in your Outlook client, you can add them to your folder list. The process varies depending on which version of Outlook you're using. ### View shared folders in Outlook on the web 1. Sign in to [Outlook on the web](https://outlook.office.com). 2. In the left navigation pane, right-click the area labeled **Shared with me** (or right-click your mailbox name). 3. Select **Add shared folder or mailbox**. 4. Enter the email address of the person who shared the folder with you. 5. Click **Add**. The shared folders appear in your folder list under the owner's name. ### View shared folders in Outlook desktop (New Outlook) 1. Open Outlook desktop application. 2. Go to **File → Account Info** or **Settings → Accounts → Shared with me**. 3. In the **Shared with me** pane, you'll see a list of mailboxes or folders shared with you. 4. To display a shared folder in the folder pane, select **+ Add** or **Add shared folder or mailbox**. 5. Enter the email address or name of the folder owner. 6. The shared folder appears in your folder list under **Shared with me**. ### View shared folders in Outlook desktop (Classic Outlook) 1. Open Outlook desktop application. 2. Go to **File → Account Settings → Account Settings**. 3. Select your account and click **Change**. 4. Click **More Settings**. 5. Go to the **Advanced** tab. 6. Click **Add** under **Open these additional mailboxes**. 7. Enter the email address of the person who shared the folder with you. 8. Click **OK** to close all dialog boxes. ### Important notes about viewing shared folders - **Subfolders**: To view shared subfolders, the parent folder (and sometimes the top-level mailbox) must have at least "Folder Visible" permission. Without this permission on parent levels, subfolders may not appear in your folder list. - **Permission propagation**: It can take some time (sometimes hours) for new shared permissions to fully propagate. If you don't see folders immediately, try restarting Outlook or waiting for the server to sync. - **Not required for API access**: Remember that adding shared folders in the Outlook UI is optional. You can access shared folders through the Nylas API without adding them to your Outlook client. For more information about viewing shared folders in Outlook, see [Microsoft's documentation](https://support.microsoft.com/en-us/office/share-and-access-another-person-s-mailbox-or-folder-in-outlook-a909ad30-e413-40b5-a487-0ea70b763081). ## Access shared folders with Nylas After a folder has been shared with you, you can access it through the Nylas API using your grant. Microsoft has specific limitations for accessing shared folders that you must follow. ### List folders shared by a specific owner > **Warning:** > **Microsoft does not support listing all shared folders from all accounts**. You must specify the folder owner's email address or grant ID using the `shared_from` query parameter. To list folders shared by a specific owner, make a [Get all Folders request](/docs/reference/api/folders/get-folder/) with the `shared_from` parameter: ```bash curl --request GET \ --url 'https://api.us.nylas.com/v3/grants//folders?shared_from=' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` The `shared_from` parameter accepts: - An email address of the person who shared the folder - A grant ID associated with the folder owner When you use `shared_from`, Nylas returns only the folders shared by that specific owner. Your own folders are not included in the response. For example, if you have folder A and B, and someone shares a folder C with you, you'll only see the folder C when you pass `shared_from` with the owner's email address. ### Work with shared folders When using `shared_from`, you can perform all operations on folders shared by the specified owner: - [Get all Folders request](/docs/reference/api/folders/get-folder/) requires `shared_from` - [Get Folder request](/docs/reference/api/folders/get-folders-id/) requires `shared_from` - [Create Folder request](/docs/reference/api/folders/post-folder/) requires `shared_from` - [Update Folder request](/docs/reference/api/folders/put-folders-id/) requires `shared_from` - [Delete Folder request](/docs/reference/api/folders/delete-folders-id/) requires `shared_from` All operations are performed on the folder owner's account, not on your own account. ### Access messages in shared folders > **Warning:** > **Microsoft does not support listing messages across all shared folders, even if they are from the same owner**. You must specify both the `in` parameter (folder ID) and the `shared_from` parameter. To list messages in a shared folder, you must provide both the folder ID and the owner's email address or grant ID: ```bash curl --request GET \ --url 'https://api.us.nylas.com/v3/grants//messages?in=&shared_from=' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` All other message endpoints support shared folders as long as you pass the `shared_from` parameter. ### Work with threads in shared folders Thread operations in shared folders have specific requirements: - [Get all Threads request](/docs/reference/api/threads/get-threads/) requires both `in` (folder ID) and `shared_from` parameters - [Get Thread request](/docs/reference/api/threads/get-threads-id/) requires `shared_folder_id` along with `shared_from` - [Update Thread request](/docs/reference/api/threads/put-threads-id/) requires `shared_folder_id` along with `shared_from` - [Delete Thread request](/docs/reference/api/threads/delete-threads-id/) requires `shared_folder_id` along with `shared_from` > **Warning:** > **Nylas does not support listing, retrieving, updating, or deleting threads across shared folders**. You must specify a specific folder and owner for each operation. ## Limitations Keep the following limitations in mind when working with shared folders: - **Scope requirements**: You must request `Mail.Read.Shared` or `Mail.ReadWrite.Shared` scopes during authentication to access shared folders. - **Owner specification required**: Microsoft does not support listing all shared folders from all accounts. You must always specify the folder owner's email address or grant ID using the `shared_from` parameter. - **Folder isolation**: When using `shared_from`, you only see folders from that specific owner. Your own folders are not included in the response. - **Message listing**: To list messages in shared folders, you must provide both the `in` parameter (folder ID) and the `shared_from` parameter. Microsoft does not support listing messages across all shared folders. - **Attachment downloads**: Downloading attachments from messages in shared folders is not supported. You can list messages and read their attachment metadata, but the Download Attachment endpoint doesn't accept the `shared_from` parameter. - **Thread operations**: Listing threads requires both `in` and `shared_from`. Retrieving, updating, or deleting threads requires `shared_folder_id` along with `shared_from`. Nylas does not support listing, retrieving, updating, or deleting threads across shared folders. - **Subfolders**: If a folder is shared, its subfolders are not automatically shared. Each subfolder must be shared separately. - **Deleting messages and threads**: To delete messages or threads from a shared folder, the folder owner must also share the "Deleted Items" folder with you. Without access to the Deleted Items folder, deletion operations will fail. - **Microsoft-only feature**: Shared folder access through the `shared_from` parameter is only available for Microsoft grants. - **Permission levels**: The actions you can perform on shared folders depend on the permission level granted by the folder owner (for example, read-only vs. read-write access).