Shared Outlook folders

As of January 2023, Microsoft has renamed “Office 365” to “Microsoft 365”. For more information, see Microsoft’s official FAQs.

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.

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.
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.

View shared folders in Outlook (optional)

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.
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.

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

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 with the shared_from parameter:

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders?shared_from=<OWNER_EMAIL_ADDRESS>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

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 requires shared_from
• Get Folder request requires shared_from
• Create Folder request requires shared_from
• Update Folder request requires shared_from
• Delete Folder request requires shared_from

All operations are performed on the folder owner’s account, not on your own account.

Access messages in shared folders

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:

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?in=<FOLDER_ID>&shared_from=<OWNER_EMAIL_ADDRESS>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

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 requires both in (folder ID) and shared_from parameters
• Get Thread request requires shared_folder_id along with shared_from
• Update Thread request requires shared_folder_id along with shared_from
• Delete Thread request requires shared_folder_id along with shared_from

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.
• 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).