Back to blog

Office 365 Permissions Inventory: Mailbox Folder Permissions

Aug 3, 2017 by Vasil Michev

For the final article in our ‘Permissions Inventory’ series, we will cover mailbox folder permissions. The PowerShell script included in this article will help you generate a detailed report on all (or some) folders across all (or some) mailboxes in the company, along with their permissions. While this script is similar to the previous scenario we covered (Calendar permissions), the number of entries we will have to deal with in this case is much larger, which means that some additional edits must be made to the script. Let’s dive right in.
To get the folder level permissions, we will use the Get-MailboxFolderPermission cmdlet, as we did before. We will also utilise the Get-MailboxFolderStatistics cmdlet to get the list of folders. This time around the number of folders is much greater, so we will wrap the execution via Invoke-Command which will only return a minimal set of data back, in order to optimise the script execution time.
To further reduce the output, we only cover the “user accessible” folders. Their corresponding folder types are added to the $includedfolders array you can find on line 53. The list is still big enough, so feel free to remove some of the entries you don’t care about, such as the Outbox folder. A ‘trimmed down’ version is provided on line 54, but you can also input your own list.
Similarly, an $excludedfolders array can be used to filter out unwanted, non-default, or ‘user created’ folders. The array is on line 58 and lists the folder names, not the folder type. Examples include folders such as the “News feeds” or “Suggested Contacts”, but as before, feel free to add to the list. The more folders you exclude here, the faster the script will run!
The following script block illustrates the logic described above – get the list of all the folders with a minimal set of properties, then filter it out to display only the return folders we are interested in:

Any user-created (sub)folder will still be present in the output after the filtering operation unless you have explicitly included its name in the $excludedfolders array, as detailed above.
The script includes several parameters to control the recipient types included in the output. By default, only user mailboxes are included (the –IncludeUserMailboxes switch), but you can also opt to include shared (-IncludeSharedMailboxes), room and equipment (-IncludeRoomMailboxes) or all of the above (-IncludeAll). Team, Discovery and Group mailboxes are not included, but the script can easily be amended to account for them if needed.
For the actual output, you can choose between the default one-line per permission entry, or the ‘condensed’ output, which reduces the output to one line per folder. This is controlled via the –CondensedOutput switch. Examples of the two types of output are depicted below:

As seen from the screenshots, the number of entries in the “condensed” output will be smaller, however filtering the permissions entries will require additional steps. Do let us know which method you prefer by commenting on this post!
The script will automatically generate a CSV file, and will also store the output in the global $varPermissions variable if you want to transform it before saving. You can specify another variable name using the –OutVariable parameter.
Next, a parameter is provided in order to control the inclusion of the default permission entries for folders, namely the –IncludeDefaultPermissions switch. This can be important in situations where you are troubleshooting folder access, for example a common scenario is for people to forget to grant permissions on the Root folder when sharing an Inbox or another folder. For this reason, some companies choose to pre-configure the default level of permissions on the Root folder. Of course, the default level applies to all users in the company, so if there are any permissions set on it, you might want to know about them. That said, these permissions are not included unless you run the script with the aforementioned switch, as they substantially increase the number of entries in the output.
Lastly, the –ExcludeUsers parameter is provided in order to allow you to exclude permission entries for certain accounts from the output. An example of this would be an administrative account that has been granted permissions to all or a group of mailboxes, or a service account that needs to access particular folder(s). The parameter requires you to provide the SMTP address of the user you want to exclude, and accepts multiple entries separated by comma. Here’s an example use case:
.\Mailbox_Folder_Permissions_inventory.ps1 -ExcludeUsers,
Additional examples on the script usage can be found in the built-in help. It’s worth mentioning that the script does not include any code to handle Exchange Online connectivity, you will have to take care of this part yourself. If no valid Exchange Online session is detected, then the script will fail.
The script file can be downloaded from the TechNet Gallery here:
Now, some additional warnings should be mentioned here. Running the script against a large number of mailboxes can take hours to complete. This is because not only is the script cycling over each mailbox, but for each mailbox, around 15 folders are covered, and that’s by default, not accounting for any user-created folders. In order to avoid this, make sure to adjust the $includedfolders and $excludedfolders arrays to only cover folders you are interested in!
Even with a reduced set of folders to check, it’s likely that you’ll run into some throttling issues or broken PowerShell sessions. The script offers a very basic way to overcome such issues, by adding some delay between cmdlet execution (line 101), which you can adjust as necessary. In addition, you can uncomment line 145/170 to make sure the script writes output to the CSV file after each iteration. For a proper solution, refer to this article for tips on how to run PowerShell scripts against large number of objects in Exchange Online.
Cogmotive is the leading global provider of enterprise level reporting and analytics applications for Office 365. Find out more now.