Managing Outlook delegates via PowerShell

In another example of a small, but impactful change, Microsoft has started rolling out improvements to the PowerShell cmdlets responsible for folder permissions that will allow us to manage some of the delegate-related settings. Two parameters have been added to the *-MailboxFolderPermission cmdlets to facilitate those changes, namely the SendNotificationToUser and SharingPermissionFlags. We will take a look at them in a moment, but first, let’s try to explain what delegates are and why the changes are important.

What is a delegate

In the Exchange world, a delegate is a person you have given some level of access to over your own mailbox. The access can range from being only able to read your messages, to being able to manage all your email as well as compose and send messages on your behalf. While you can set folder level permissions by right-clicking any of your folders in Outlook and selecting the corresponding menu item, the Delegates dialog under File -> Account settings -> Delegate access exposes some additional controls. It’s easy to use this method to grant permissions on commonly used folders, but more importantly it allows you to control access to Private items and to configure the handling of meeting responses. The corresponding settings are shown on the screenshot below:

Outlook Delegates dialog Outlook Delegate permissions dialog

Now, as the folder permissions are configurable via other means as well, what is usually referred to as Delegate is a user for which the “delegate receives a copy of meeting-related messages sent to me” setting is configured. This option only becomes available in the UI when the Calendar folder permissions are set to Editor. Once a Delegate is configured for your mailbox, in the sense of configuring the checkbox mentioned above, the “Deliver meeting requests addressed to me and responses to meeting requests where I am the organizer to” option becomes available, and you can decide whether you, the delegate, or both should receive those. In addition, a Delegate also receives Send on behalf of permissions to your mailbox. More information can be found in the official documentation.

Up until now, some of those settings were only configurable via Outlook, and we as administrators were not able to even see their corresponding values, let alone change them, as they were not exposed in the EAC or any of the underlying PowerShell cmdlets. This in turn created situations in which the admin or support person troubleshooting an issue had to “guess” what the related configuration was, or wait for the user to provide the required details. The only way to obtain this information outside of Outlook, or modify it, was via EWS, which required additional configuration and permissions, so it was far from ideal. Still, in some cases it was easier to use EWS instead of having to get to the user in order to check the settings from Outlook, thus administrators often used solutions such as the EWS delegate module.

Configuring a Delegate via PowerShell

With the recently introduced changes, all of this is now possible via PowerShell. To make things easier and to ensure compatibility with any custom scripts you might already be using, the team opted to not introduce any new cmdlets for delegate management. Instead, the familiar Add-/Get-/Remove-/Set-MailboxFolderPermission cmdlets have been updated to handle delegate scenarios.

You might have noticed that the output of the Get-MailboxFolderPermission changed few weeks back, and it now features one additional column, SharingPermissionFlags. So for example, you would see something like this:

Get-MailboxFolderPermission HuKu:\Calendar

FolderName           User                 AccessRights          SharingPermissionFlags
----------           ----                 ------------          ----------------------
Calendar             Default              {LimitedDetails}
Calendar             Anonymous            {None}

Unfortunately, the SharingPermissionFlags property will not always reflect the correct status, but more on this later. Let’s now see how one can configure delegate settings via PowerShell, as in how we can use the Add-MailboxFolderPermission cmdlet with the new parameters. If I want to add myself as delegate for another user, in addition to the customary Identity, User and AccessRights parameters, I will need to also specify the “level” of delegate access via the SharingPermissionFlags parameter. The parameter is a bit quirky, as it requires you to specify multiple values separated with comma for some configurations. More importantly, the SharingPermissionFlags parameter will only work if you have set the AccessRights parameter value to Editor, so make sure to remember that. To specify the fact that the user need to be added as delegate, set the value of SharingPermissionFlags to Delegate. Here’s an example:

Add-MailboxFolderPermission huku:\calendar -User vasil -AccessRights Editor -SharingPermissionFlags Delegate

FolderName           User                 AccessRights         SharingPermissionFlags
----------           ----                 ------------         ----------------------
Calendar             Vasil Michev         {Editor}             Delegate

Once this option is set, the user (me) will receive the Editor level of access to the Calendar folder, and the mailbox will have the “delegate receives a copy of meeting-related messages sent to me” option enabled, just as described in the previous section. Note that the cmdlet does not expose any way to change the scope of meeting requests delivery controlled by the “Deliver meeting requests addressed to me and responses to meeting requests where I am the organizer to” option. The reasons being, this is a global option and not configurable per delegate, but you can still use Outlook or EWS to control it.

Other uses of the SharingPermissionFlags parameter

If we also want to make sure that the delegate will be able to see Private items, the SharingPermissionFlags parameter needs to include the corresponding CanViewPrivateItems value. This value can only be supplied if Delegate value is also present, and as already mentioned above, if the AccessRights parameter is set to Editor. As we already used the Add-MailboxFolderPermission cmdlet to create a permission entry for that user though, this time we will use the Set-MailboxFolderPermission cmdlet to update it:

Set-MailboxFolderPermission huku:\calendar -User vasil -AccessRights Editor -SharingPermissionFlags Delegate,CanViewPrivateItems

To verify the permissions are applied, we can rerun the Get-MailboxFolderPermission cmdlet:

Get-MailboxFolderPermission HuKu:\Calendar

FolderName           User                 AccessRights           SharingPermissionFlags
----------           ----                 ------------           ----------------------
Calendar             Default              {LimitedDetails}
Calendar             Anonymous            {None}
Calendar             Vasil Michev         {Editor}               Delegate, CanViewPrivateItems

Note that the “Delegate can see my private items” option, corresponding to the CanViewPrivateItems value can technically be configured without requiring the user to be Delegate. This requirement is enforced by the parameter sets for the cmdlet, in order to reflect the “supported” configuration.

You can make additional changes at any point via the Set-MailboxFolderPermission cmdlet, for example, if you want to revoke the delegate-level permissions but still keep the user as Editor on the Calendar, specify the None value for the SharingPermissionFlags parameter:

Set-MailboxFolderPermission huku:\calendar -User vasil -AccessRights Editor -SharingPermissionFlags None

Or you can remove the entry altogether via the Remove-MailboxFolderPermission cmdlet:

Remove-MailboxFolderPermission huku:\calendar -User vasil

As with other folder level permissions, make sure that no existing entry exists before using the Add-MailboxFolderPermission cmdlet. Otherwise an error will be thrown, and you have to use the Set-MailboxFolderPermission cmdlet or simply remove the entry via the Remove-MailboxFolderPermission cmdlet first.

Using the SendNotificationToUser parameter

The other newly introduced parameter, SendNotificationToUser, serves to generate an email message summarizing the changes made into a “sharing invitation”. It’s the analog of the “Automatically send a message to delegate summarizing these permissions” checkbox in the Outlook Delegate dialog, shown above. The parameter can only be used when configuring permissions for Calendar folders, and only when one of the following AccessRights parameter values is specified: AvailabilityOnly, LimitedDetails, Reviewer or Editor.

Another important thing to note is that the SendNotificationToUser parameter is a Boolean, not a Switch. Thus, whenever you specify it, don’t forget to include the corresponding $true or $false value. I would personally prefer a switch, as it’s a cleaner and easier solution. I would also extend the same argument to the SharingPermissionFlags parameter, and have already left this feedback with Microsoft.

To complete our covering of the SendNotificationToUser parameter, here’s an example of what a “sharing invitation” will look like:

Outlook delegate invitation

 

Summary

In this article, we took a quick look at the new parameters introduced to handle delegates in Exchange Online. While the changes to the *-MailboxFolderPermission can be classified as “minor”, they bring a welcome improvement to the way we can report on or set delegate permissions. With the changes discussed above, using EWS will no longer be necessary to accomplish this task, instead we can rely on the familiar PowerShell cmdlets, making the life of the admins easier.

It is important to understand that the new capabilities cannot account for every possible delegate scenario. In some cases, such as configuring the delivery scope of meeting requests, one might still need to resort to using Outlook or EWS. Another example is the requirement that the CanViewPrivateItems flag can only be used when the Delegate flag is set. Similarly, it’s also important to understand that the Get-MailboxFolderPermission might not correctly reflect on changes made via EWS or Outlook, as it only reflects the “supported” configuration.

Lastly, for folks still using on-premises Exchange – the changes detailed here are only available in Exchange Online. At least for the time being.

63 thoughts on “Managing Outlook delegates via PowerShell

  1. Joe says:

    Does anybody know how to remove delegate access from an exchangeonline mailboX using Powershell so that when you open the FilE>Accounts>Delegates view in Outlook the user is not in the list? I have removeD every trace of delegate access using remove-mailboXfolderpermission , Set-Mailbox $Email -GrantSendOnBehalfTo @{remove=”$Delegate”}, removing user from publicDelegates attribute in AD. Even if the user might not have access they still show in the Outlook GUI if you bring up the Delegate list.

    Reply
    1. Vasil Michev says:

      It’s a separate flag, not exposed via PowerShell. EWS would be my preferred method to handle this. If you need to stick to PowerShell, best you can do is use the -ResetDelegateUserCollection flag, which will purge all delegates.

      Remove-MailboxFolderPermission user:\Calendar -ResetDelegateUserCollection
      Reply
      1. Joe says:

        Thank you. Its unfortunate we cant FULLY remove delegate access using ExchangeOnline PS for a single user and I don’t believe I have seen this stated clearly anywhere in documentation. I am aware of the reset command but as stated this removes all delegates. I wonder if this can be done using Graph API.

        Reply
  2. ALan Burchill says:

    So… there is no way to turn off ““Automatically send a message to delegate summarizing these permissions” or to remove the delegate permission entry ? i can set them all to “none” but the permission still remains.

    Reply
    1. Sara says:

      Hi. Have you found any way to turn off these notifications please?
      turn off ““Automatically send a message to delegate summarizing these permissions” or to remove the delegate permission entry ?

      Reply
  3. John says:

    Hi,

    Is it possible to enable a delegate to view items flagged “To do” via powershell ?

    Reply
    1. Vasil Michev says:

      Delegation works on the folder level, or optionally the entire mailbox. You cannot delegate access to specific items only.

      Reply
  4. Jeremy Bradshaw says:

    Hi Vasil,

    Hoping you might know the answer to this. I thought that when we grant somebody the “Delegate” flag, that somebody should then show up on the mailbox’s GrantSendOnBehalfTo (or AD’s publicDelegates) property. I’m seeing a user who is able to do Send on Behalf successfully, but on the mailbox being sent on behalf of, I see no sign of Send on Behalf permission. I’ve checked with Get-Mailbox | select GrantSendOnBehalfTo, also looked in AD at publicDelegates (knowing the two are one and the same), and I look in Get-CalendarProcessing | select ResourceDelegates.

    Wondering if the “Delegate” sharing flag can grant Send on Behalf without having that permission be documented anywhere else that admins can see.

    Also wondering if you’re aware of a way to review existing sharing flags. Maybe MFCMAPI?

    Thanks in advance.

    Reply
    1. Vasil Michev says:

      Afaik it shouldn’t be possible without Send on behalf (or Send As). In fact both the PowerShell flag and Outlook will add Send on behalf permissions when adding a delegate. I suppose something went wrong on the backend, try re-adding the permissions.
      As for reviewing the flags, EWS is my preferred solution: http://www.flobee.net/delegate-management-module-updated-2/

      Reply
  5. Eddy Veldboer says:

    Great article and still helpfull in troubleshooting delegates and SharingPermissionFlags. Thanks for sharing your knowledge!

    Reply
  6. rajesh says:

    i want to forward email to specific recipient with start date and end date using PowerShell script.
    Email forwarding is achieved but I am not sure how to put restriction of start date and end date.
    Is this possible ?? If yes, can you please help me with the powershell script for the same

    Reply
    1. Vasil Michev says:

      Simply schedule a script to disable forwarding at a specific date.

      Reply
  7. Tosh says:

    This article is still useful after 2 years – just wanted to say thank you!

    Reply
  8. Peter says:

    Hi Vasil,

    Very great post to understand SharingPermissionFlags !

    Is it a way to grant Editor access with SharingPermissionFlags set to Delegate to a Security group ?

    Reply
    1. Vasil Michev says:

      Afaik only user objects are supported as delegates.

      Reply
      1. wayne ash says:

        at least from dec 2022, i can confirm that a 365 universal email enabled group can be added for permissions. same command, just use the email address of the group

        Reply
  9. Tony says:

    Hi Vasil,

    Great post!

    How would you pull a report on all delegates with access to private items? Is it possible with powershell?
    Thanks,
    Tony

    Reply
  10. Yury A. says:

    Any recommendation for an equivalent PS-based solution for enabling delegates’ view of private items in non-calendar folders of a share mailbox?

    Add-MailboxFolderPermission :\inbox -User user@domain.com -AccessRights Editor SharingPermissionFlags Delegate,CanViewPrivateItems

    Your request can’t be completed. The parameter “SharingPermissionFlags” cannot be specified for the following:
    Outlook.com mailbox, non-calendar folders, default permission or anonymous permission.

    Reply
    1. Vasil Michev says:

      That flag is a global one for the mailbox, not folder specific. Although I cannot be sure whether using the cmdlet is the correct way to set it “globally”, you might have to use EWS for that.

      Reply
  11. jith says:

    THIS IS Exchange 2013
    address is correct and fYI i can able to provide a permission for user mailbox and security GP But i cannot perform shared mailbox and distribution Gp

    Reply
  12. jith says:

    i am getting below error.
    i am trying room mail box calender permission to shared mail box…could you please help me

    [PS] C:\Windows\system32>Set-MailboxFolderPermission mlot@sxx.com:\calendar -User development@sxx.com -AccessRights Editor
    The user “development@sxx.com” is either not valid SMTP address, or there is no matching
    information.
    + CategoryInfo : NotSpecified: (:) [Set-MailboxFolderPermission], InvalidExternalUserIdException
    + FullyQualifiedErrorId : [Server=EXMBX01,RequestId=8f88fc17-0b03-432d-b70a-3086de10ae62,TimeStamp=19/02/2019 14:2
    2:08] [FailureCategory=Cmdlet-InvalidExternalUserIdException] DF0CC02E,Microsoft.Exchange.Management.StoreTasks.Se
    tMailboxFolderPermission
    + PSComputerName : exmbx01.sxx.com

    Reply
    1. Vasil Michev says:

      Well double-check the address or use a different identifier. In addition, it seems like you are running this on-premises. The “delegate” parameters of the cmdlet only work in Office 365.

      Reply
  13. Jeff says:

    OK, this may be a somewhat dumb question, but is it safe to presume that this cmdlet only works on the Calendar folder?

    I’ve tried using the same for the Inbox folder and it generates an error. And I’m assuming it wasn’t a fat-finger by me. (“Add-MailboxFolderPermission bigboss:\inbox -User execasst -AccessRights Editor -SharingPermissionFlags Delegate”)

    “Your request can’t be completed. The parameter “SharingPermissionFlags” cannot be specified for the following:
    Outlook.com mailbox, non-calendar folders, default permission or anonymous permission.”

    That pretty much says “No Inbox delegate for you!”, right?

    Reply
    1. Vasil Michev says:

      Yes, it’s only for the Calendar folder. For Inbox or any other folder simply skip the -SharingPermissionFlag, you don’t need it anyway.

      Reply
  14. alvin says:

    Hi , i have a delegate reported that calendar owner still receiving the calendar items, delegate access rights is editor and sharingpermissionflag is delegate,canview private items. On outlook client, there’s an option to choose “delegate only” which is already set. i dont know why the calendar owner is still receiving the calendar invites

    Reply
    1. Vasil Michev says:

      Try removing/re-adding the permissions? Also check for any rules that might be affecting this. Message trace can show you why a given message gets delivered to the owner as well as the delegate.

      Reply
  15. Volodymyr says:

    Hi,

    Do you have any information whether the SharingPermissionFlags parameter is going to be supported by Exchange 2016 or 2019

    Thans

    Reply
    1. Vasil Michev says:

      Afaik it’s still only supported for ExO. I’ll ask if they have any plans on porting it to On-Prem versions.

      Reply
      1. Vasil Michev says:

        So the reply I got is there are no plans to port it to on-premises currently. Things might change in the future though.

        Reply
  16. Clif says:

    In our environment we’ve granted specific users access to a mailbox owner’s calendar via the powershell script and set LimitedDetails like seen in your screenshot. So, for a particular mailbox owner there may be 3-4 other people that have this LimitedDetail permission assigned.

    When the mailbox owner sends a meeting request to someone in the organization (not necessarily these 3-4 people that have access) these 3-4 users with limited details are getting a copy of the meeting request and can then click to respond (yes / no) to the invite. I’d like to turn off these meeting requests for “delegates” so they don’t receive these requests.

    If I go to File > Account Settings > Delegate Access the screen is completely blank. So, I can’t make the simple toggle here. I haven’t been able to figure out a powershell command to disable this.

    If I am reading and understanding your post correctly will it work if I remove the LimitedDetails setting change their permission to Editor with the Delegate SharingPermissionFlag? Then simply disabling the “delegate receives a copy of meeting-related messages sent to me” through the Outlook File > Account Settings > Delegate Access?

    Thanks!

    Reply
  17. Richard says:

    Hi Vasil,

    This blog is great and has helped me understand more about what’s possible with configuring delegate permissions.

    If you had time, can you please help me understand why the “-SharingPermissionFlags CanViewPrivateItems” can only be configured against a calendar folder and not say the inbox?

    I tested this and after providing the SharingPermissions Flag to view private items within the calendar, the user could see Private email items within the Inbox folder? Does providing this to the calendar allow all private items to be viewable by the delegate? I’m just unclear how the Calendar/Inbox relate.

    Thanks in advance,
    Richard

    Reply
    1. Vasil Michev says:

      It’s a mailbox-wide setting, corresponding to the “delegate can see my private items” option you can configure via Outlook. The delegate still needs to have access to the corresponding folder though.

      Reply
      1. Richard says:

        Hi Vasil,

        That makes more sense.

        So it sounds like a two-step process if I’m correct?

        1) Provide delegate access to the Inbox
        2) Provide delegate access to the calendar with the -SharingPermissionFlags CanViewPrivateItems

        Kind regards,
        Richard Ing

        Reply
  18. Emil Sabkov says:

    Hi,

    how can we list the users that have permission to a given folder and see the value of -SendNotificationToUser

    Reply
    1. Vasil Michev says:

      You can list them using the examples given above:

      Get-MailboxFolderPermission HuKu:\Calendar

      There is no way to see what the value of the SendNotificationToUser flag was set to when adding the permissions, this is a one-time notification and I guess the folks at Microsoft decided there is no point to report on it later on.

      Reply
  19. Joy Knox says:

    This is working great however when I add a delegate, the existing delegate permission is revoked. We always want the primary assistant as the delegate, but during vacation or backup support, we want to ADD another delegate. How do I maintain delegate permissions but still ADD a 2nd delegate. Here is my syntax:

    **I set the below command when adding the 2nd delegate**
    Set-MailboxFolderPermission USERNAME:\calendar -User DELEGATEUSERNAME -AccessRights Editor -SharingPermissionFlags Delegate,CanViewPrivateItems

    It successfully adds the new delegate, but removes the previous delegate setting.

    Reply
  20. tonakis says:

    Hi,
    related to “delegate receives a copy of meeting-related messages sent to me” option – could that be changed via PS using Set-CalendarProcessing cmdlet ? Thanks!

    Reply
    1. Vasil Michev says:

      The -Delegate flag for Add/Set-MailboxFolderPermissions corresponds to the “delegate receives a copy of meeting-related messages sent to me” (“receivecopiesofmeetingmessages”) option. It’s not the same as the -ForwardRequestsToDelegates parameter we can see/set via Set-CalendarProcessing – this one is global, not configurable per delegate.

      The “Deliver meeting requests addressed to me and responses to meeting requests where I am the organizer to” option (“MeetingRequestsDeliveryScope”) is also a different flag/setting, this one is only controllable via EWS or the Outlook client.

      Reply
      1. tonakis says:

        Thanks for the reply
        I was referring more to the switch – [-RemoveForwardedMeetingNotifications ] set via Set-CalendarProcessing cmdlet which corresponds to “delegate receives a copy of meeting-related messages sent to me”.

        Reply
  21. Filipe Araujo says:

    How do I get this update? I need to achieve “CanViewPrivateItems” but my PS does not currently recognize the expressions. Thanks!

    Reply
  22. Ricardo says:

    Thank you for writing this. I was waiting for this for a while. I used the PowerShell command you provided to setup a delegate, but the option of who should be receiving the meeting requests is set to “My delegates only”. Is there a way to change this with PowerShell to any of the other two options? thanks

    Reply
    1. Vasil Michev says:

      Nope, you can only modify this one from Outlook, or by using EWS.

      Reply
  23. Lars says:

    The following painful method allows sharing a calendar giving the same access as would be achieved in Office 365 by using the -SharingPermissionFlags Delegate,CanViewPrivateItems:
    Logon as the calendar user. Start Outlook in Online Mode. Manually share the calendar with editor permissions + allow Viewing Private items.

    Reply
  24. Asger says:

    Thanks so very much!
    Much appreciated.

    Funny that “allows” (delegation) overrules “Denies” (reviewer limitations)
    On Windows server, deny will always overrule allow..

    Reply
  25. Asger says:

    Thanks for a lot of great tips.
    I have one question related to this post.

    We have a user who needs full access to a shared mailbox (not a user’s mailbox) including all subfolders, sent, drafts etc. but only reviewer rights to the calendar including private items.
    I’ve tried to use the above mentioned commands, but he still can edit the calendar.
    Delegate access has been granted from EAC.
    Any suggestions?

    Reply
    1. Vasil Michev says:

      If you have granted Full Access permissions, those “overwrite” any folder-level ones. Instead you should be granting permissions on the folder level, which is incidentally the subject of an article I’m releasing very soon on the Cogmotive blog. I’ll update the link 🙂

      Reply
  26. Jose Byron Gonzalez says:

    Thank you for writing this! It answers my question and it would resolve my problem except that my PS doesn’t want to play ball:

    A parameter cannot be found that matches parameter name ‘SharingPermissionsFlags’.
    + CategoryInfo : InvalidArgument: (:) [Add-MailboxFolderPermission], ParameterBindingException
    + FullyQualifiedErrorId : NamedParameterNotFound,Add-MailboxFolderPermission

    Do I need to update something, since it doesn’t show the new column in the output for Get-MalboxFolder Permission?

    Reply
    1. Vasil Michev says:

      This only works against Office 365, more specifically the Multi-tenant version of O365. If you are using on-premises Exchange or any of the other variations of O365, you will have to wait until the feature is released there.

      Reply
      1. Jose Byron Gonzalez says:

        Aha! I knew there had to be a catch. Thank you very much.

        Reply
  27. Robert says:

    One last question how does the (Get-CalendaProcessing Delegate Column) relate to the options you discussed in this blog post?

    I seem to have some confusion between the Delegate Column and the Options described by you.

    Reply
    1. Vasil Michev says:

      Simply ignore the Get-CalendaProcessing output, the ResourceDelegates attribute shown there can be set independently of the options detailed here (and the Outlook delegate settings). Or let me rephrase that, if you use the cmdlets above or the Outlook delegate setting, it should set the ResourceDelegates attribute as well, but there are other scenarios where this is not true.

      They have made some changes recently that limit the ways to modify ResourceDelegates (https://www.michev.info/Blog/Post/1744/controlling-resource-delegates-for-user-mailboxes), but there are still some “workarounds” left. The SharingPermissionFlags value is what you should be looking at, or the actual ReceiveCopiesOfMeetingMessages property that’s exposed via EWS.

      For example, I can add a “delegate” in Outlook that doesn’t have access to my Calendar folder at all, and it can still show up in ResourceDelegates. However, the SharingPermissionFlags will be empty.

      Reply
      1. Robert says:

        OK I see Thanks. I have always been confused to some degree by the way resource delegates are set and how the setting in outlook corresponds to the setting on the users mailbox.

        Thanks for the clarification.

        Reply
  28. Robert says:

    Doesn’t the resource delegate option in Get-CalenderProcessing show the delegates for the mailbox?

    Reply
    1. Vasil Michev says:

      No, not in all cases. But in general you can use it as indicator whether there are *some* delegates configured.

      Reply
      1. Robert says:

        OK I see. So while it can be used its not always accurate. We recenly had a case where a user had previously configured a delegate on his mailbox and then that delegation was removed.

        However the user who was previously configured as a delegate, kept receiving meeting requests from the mailbox he was formerly a delegate for.

        Turned out to be an issue with a delegate rule only visible in MFCMAPI. https://practical365.com/exchange-server/deleted-delegates-still-receive-meeting-invites-for-other-mailbox-users/

        Absolutely the more frustrating thing.

        Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.