Get Outlook messages in a shared or delegated folder

Outlook lets customers share mail folders with one another and provide "read", "create", "modify", or "delete" access to individual folders. Outlook also allows a customer to delegate another user to act on the customer's behalf, and access specific mail folders or the customer's entire mailbox; this is also known as "delegation" in Outlook.

Programmatically, Microsoft Graph supports getting messages in mail folders that have been shared by other users, as well as getting the shared folders themselves. The support also applies to folders that have been delegated.

As an example, Garth has shared with John and given read access to Garth's Inbox. If John has signed into your app and provided delegated permissions (Mail.Read.Shared or Mail.ReadWrite.Shared), your app will be able to access Garth's mail and Garth's Inbox as described below.

Note The sharing permissions (Mail.Read.Shared or Mail.ReadWrite.Shared) allow you to read or write messages in a shared or delegated folder. They do not support subscribing to change notifications on items in such folders. To set up change notification subscriptions on messages in a shared, delegated, or any other user's mail folder in the tenant, use the application permission, Mail.Read.

Get a message in the shared folder

You can get a specific message in Garth's Inbox:

GET users/{Garth-userId | Garth-userPrincipalName}/mailfolders('Inbox')/messages/{id}

On successful completion, you'll get HTTP 200 OK and the message instance identified by {id} from Garth's Inbox.

Get all messages in the shared folder

Get all the messages in Garth's Inbox:

GET users/{Garth-userId | Garth-userPrincipalName}/mailfolders('Inbox')/messages

On successful completion, you'll get HTTP 200 OK and a collection of message instances in Garth's Inbox.

Get the shared folder

Get the folder (Inbox) that Garth has shared with John.

GET users/{Garth-userId | Garth-userPrincipalName}/mailfolders('Inbox')

On successful completion, you'll get HTTP 200 OK and a mailFolder instance that represents Garth's Inbox folder.

The same GET capabilities apply if Garth had delegated John further access to Garth's Inbox, or if Garth had delegated John his entire mailbox.

If Garth has not shared his Inbox with John, nor has he delegated his mailbox to John, specifying Garth’s user ID or user principal name in those GET operations will return an error.

Next steps

Find out more about: