Setting Folder-Level Permissions (Exchange Web Services)

Topic Last Modified: 2009-07-16

Starting with Microsoft Exchange Server 2007 Service Pack 1 (SP1), you can use folder-level permissions to enable a delegator to control a delegate's access to specific folders. A delegator, also known as a principal, can assign folder-level permissions to delegates to allow delegates to perform actions on the principal's behalf. For information about delegate access, see Exchange Web Services and Delegate Access.

Folder-level permissions are supported in the following operations:

• CreateFolder
• GetFolder
• UpdateFolder
• SyncFolderHierarchy

A principal can configure folder-level permissions to do the following:

• Grant, deny, and edit the permissions of a user or security group to a specified folder through role-based permission levels and a combination of individual member permissions.
• Remove a user or security group from the permission set of a folder.
• Configure default and anonymous sharing permissions on a specified folder.

You can set individual permissions on a folder, or you can set a permission level on a folder. The following are the individual permissions that you can set:

• Can Create
• Can Read
• Can Create Subfolders
• Is Folder Owner
• Is Folder Contact
• Is Folder Visible
• Edit Items
• Delete Items

The following table lists the permission levels that you can set on mailbox folders and Calendar folders. If you try to set a Calendar-only permission level on a non-Calendar folder, an ErrorCannotSetCalendarPermissionOnNonCalendarFolder error will be returned in the response.

Mailbox folder and Calendar folder permission levels

The following table shows which individual permissions apply to each permission level.

Permissions by permission level

Question marks indicate that the flag can be either true or false for that permission level. In Microsoft Office Outlook, when the permission level is set to None, IsFolderContact and IsFolderVisible can be either true or false and the permission level remains unchanged. If changes are made to other individual permission settings, the permission level property also changes.

If a non-Custom permission level is specified in the folder-level permissions request, the individual permission settings should not be specified. If you specify an individual permission when a permission level has been specified, an ErrorInvalidPermissionSettings error will be returned in the response.

If the client has to specify individual settings, you must use the Custom permission level; otherwise, an ErrorInvalidPermissionSettings error will be returned in the response.

Folder-level permissions work with other Exchange Web Services operations in the following ways:

• The GetFolder operation will return the permissions that are set on the folder when the AllProperties shape is specified.
• The SyncFolderHierarchy operation synchronizes PermissionSets.
• The UpdateFolder operation will fail if multiple Permission entries are provided for the same user. The UpdateFolder response will return the ErrorDuplicateUserIdsSpecified response code.
• The SetFolderField option of the UpdateFolder operation will overwrite all the permission settings on the folder. The client cannot change the permissions for each user.
• The DeleteFolderField option of the UpdateFolder operation will delete all the permission settings on the folder.

static void CreateFolderLevelPermissions()
{
    // Set the version, credentials, and the Client Access server on ExchangeServiceBinding.
    ExchangeServiceBinding esb = new ExchangeServiceBinding();
    esb.RequestServerVersionValue = new RequestServerVersion();
    esb.RequestServerVersionValue.Version = ExchangeVersionType.Exchange2007_SP1;
    esb.Credentials = new NetworkCredential("username", "password", "domain");
    esb.Url = "https://CAS.example.com/ews/exchange.asmx";

    // Create user identifier.
    UserIdType user = new UserIdType();
    user.PrimarySmtpAddress = "user3@example.com.com";

    // Set the folder permission level to Editor.
    PermissionSetType permissionSet = new PermissionSetType();
    permissionSet.Permissions = new PermissionType[] { new PermissionType() };
    permissionSet.Permissions[0].PermissionLevel = PermissionLevelType.Editor;
    permissionSet.Permissions[0].UserId = user;

    FolderType folder = new FolderType();
    folder.DisplayName = "NewFolderWithPermissionsSet";
    folder.PermissionSet = permissionSet;

    // Specify the target folder.
    DistinguishedFolderIdType inbox = new DistinguishedFolderIdType();
    inbox.Id = DistinguishedFolderIdNameType.inbox;
    TargetFolderIdType targetFolder = new TargetFolderIdType();
    targetFolder.Item = inbox;

    CreateFolderType request = new CreateFolderType();
    request.Folders = new FolderType[] { folder };
    request.ParentFolderId = targetFolder;

    try
    {
        // Send the request and get the response.
        CreateFolderResponseType response = esb.CreateFolder(request);

        // Get the response messages.
        ResponseMessageType[] rmta = response.ResponseMessages.Items;

        // Cast to appropriate response message type.
        if (((FolderInfoResponseMessageType)rmta[0]).ResponseClass == ResponseClassType.Success)
        { 
            // Continue.
        }
        
    }

    catch 
    {
        // Handle errors.
    }
}