Exchange Server calendar and folder permissions: Add-MailboxFolderPermission and delegates

"Can you give my assistant access to my calendar?" is a daily request, and on Exchange Server the cleanest answer is a folder permission set in the Exchange Management Shell. The cmdlets are simple, but they're picky about folder names, about adding versus changing an entry, and about the difference between calendar access and a real delegate. In this post I'll cover the syntax, the roles, delegates and the two errors everyone hits.

How folder permissions work#

• Every mailbox folder has its own permission list. Besides named users and groups it has two built-in entries: Default (everyone in the organization without their own entry) and Anonymous (unauthenticated users). On calendars, Default is typically AvailabilityOnly.
• Folders are addressed as Mailbox:\Folder or Mailbox:\Parent\Subfolder, for example ayla@contoso.com:\Calendar or Ayla:\Inbox\Reports.
• The folder name is the one in the mailbox's language. A German mailbox has Kalender, not Calendar.
• You can grant permissions to mailboxes, mail users and mail-enabled security groups (nested groups included). Plain distribution groups don't work because they aren't security principals.
• Four cmdlets do the work: Get-, Add-, Set- and Remove-MailboxFolderPermission. Add creates a new entry; Set replaces the rights of an existing entry.
• The -SharingPermissionFlags and -SendNotificationToUser parameters you'll see in examples online work only in Exchange Online. They don't exist for Exchange Server mailboxes.

The roles#

Step-by-step#

1. Check what's already there#

Get-MailboxFolderPermission -Identity "ayla@contoso.com:\Calendar" |
    Format-Table FolderName, User, AccessRights -AutoSize

2. Find the real folder name#

If the identity fails for a mailbox in another language, ask Exchange for the calendar folder's actual name:

Get-MailboxFolderStatistics -Identity ayla@contoso.com -FolderScope Calendar |
    Format-Table Name, FolderPath, FolderType -AutoSize

The default calendar is the entry whose FolderType is Calendar. Use its name in the identity, for example ayla@contoso.com:\Kalender.

3. Add, change or remove an entry#

# New entry
Add-MailboxFolderPermission -Identity "ayla@contoso.com:\Calendar" -User julia@contoso.com -AccessRights Editor

# Change an existing entry (the new rights replace the old ones)
Set-MailboxFolderPermission -Identity "ayla@contoso.com:\Calendar" -User julia@contoso.com -AccessRights Reviewer

# Show subject and location to everyone in the organization
Set-MailboxFolderPermission -Identity "ayla@contoso.com:\Calendar" -User Default -AccessRights LimitedDetails

# Remove an entry
Remove-MailboxFolderPermission -Identity "ayla@contoso.com:\Calendar" -User julia@contoso.com -Confirm:$false

4. Script it safely: add or set#

Scripts that run against many mailboxes hit both errors below sooner or later. Check for an entry first:

$folder = "ayla@contoso.com:\Calendar"
$user   = "julia@contoso.com"
$entry  = Get-MailboxFolderPermission -Identity $folder -User $user -ErrorAction SilentlyContinue
if ($entry) { Set-MailboxFolderPermission -Identity $folder -User $user -AccessRights Editor }
else        { Add-MailboxFolderPermission -Identity $folder -User $user -AccessRights Editor }

5. Make someone a real delegate#

On Exchange Server, Editor rights on a calendar let the assistant manage items and accept or decline a meeting request by opening it in the manager's mailbox. They don't make the assistant a delegate who receives meeting requests. For that, the mailbox owner uses classic Outlook: File › Account Settings › Delegate Access › Add. The delegate settings there also control whether the delegate receives copies of meeting-related messages and can see private items; note that the private-items option applies to all folders.

Outlook's delegate setup also grants Send on Behalf. To grant or check that from the shell:

Set-Mailbox ayla@contoso.com -GrantSendOnBehalfTo @{Add="julia@contoso.com"}
Get-Mailbox ayla@contoso.com | Format-List GrantSendOnBehalfTo

For room and equipment mailboxes, use Set-CalendarProcessing -ResourceDelegates instead.

The two errors and what they mean#

Adding an entry for someone who already has one fails with the following message, and the error details name the exception UserAlreadyExistsInPermissionEntryException:

An existing permission entry was found for user: Julia Rossi.

Use Set-MailboxFolderPermission to change the existing entry instead. The opposite case, changing an entry that doesn't exist, fails with this message and the exception UserNotFoundInPermissionEntryException:

There is no existing permission entry found for user: Julia Rossi.

Use Add-MailboxFolderPermission instead. If you get this for Default, check whether someone deleted the Default entry; add it back with Add-MailboxFolderPermission. Remember that an entry granted to a group doesn't count as an entry for its members.

Verify#

• Run Get-MailboxFolderPermission again. Good looks like exactly one line for the user with the role you intended, and Default and Anonymous still present.
• Have the user open the shared calendar in Outlook or Outlook on the web. Reviewers should see details, while a user covered only by Default with LimitedDetails sees subject and location only.
• For delegates, send a meeting request to the manager and confirm the delegate receives it and can respond on their behalf.

Tips & gotchas#

• Grant to mail-enabled security groups for teams, so access follows group membership.
• Don't confuse folder permissions with Full Access: Full Access opens the whole mailbox; folder permissions are per folder. See Send As and Send on Behalf errors on Exchange Server for the sending side.
• Private items stay hidden from folder-permission users; only the Outlook delegate option exposes them.
• Outlook in cached mode may need a restart before new rights show up.
• In hybrid, folder permissions between on-premises and cloud mailboxes have their own rules; see Cross-premises permissions in Exchange hybrid.

References#

• Add-MailboxFolderPermission (Microsoft Learn)
• Set-MailboxFolderPermission (Microsoft Learn)