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

Note

Setting folder-level permissions with Exchange Web Services is not supported in the initial release version of Microsoft Exchange Server 2007.

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.

Note

Individual permissions can only be set on non-Calendar folders. If a client uses an individual permission to call CreateFolder or UpdateFolder against a Calendar folder, the ErrorCannotSetNonCalendarPermissionOnCalendarFolder error code will be returned in the response.

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

Permission Level	Mailbox Folder	Calendar Folder
None	Yes	Yes
Owner	Yes	Yes
PublishingEditor	Yes	Yes
Editor	Yes	Yes
PublishingAuthor	Yes	Yes
Author	Yes	Yes
NoneditingAuthor	Yes	Yes
Reviewer	Yes	Yes
Contributor	Yes	Yes
Custom	Yes	Yes
FreeBusyTimeOnly	No	Yes
FreeBusyTimeAndSubjectAndLocation	No	Yes

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

Permissions by permission level

Permission Level	Can Create	Can Read	Can Create Sub Folders	Is Folder Owner	Is Folder Contact	Is Folder Visible	Edit Items	Delete Items
None	Not Set	Not Set	Not Set	Not Set	?	?	None	None
Owner	true	true	true	true	true	true	All	All
PublishingEditor	true	true	true	Not Set	Not Set	true	All	All
Editor	true	true	Not Set	Not Set	Not Set	Not Set	All	All
PublishingAuthor	true	true	true	Not Set	Not Set	true	Own	Own
Author	true	true	Not Set	Not Set	Not Set	true	Own	Own
NoneditingAuthor	true	true	Not Set	Not Set	Not Set	true	None	Own
Reviewer	Not Set	true	Not Set	Not Set	Not Set	true	None	None
Contributor	true	Not Set	Not Set	Not Set	Not Set	true	None	None
Custom	?	?	?	?	?	?	?	?

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.

Important

Attempts to use CreateFolder and UpdateFolder to set permissions will not succeed unless all the permission settings succeed. The request will fail and will not continue to edit other properties if a set permission attempt fails.

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.

Note

A delegate who has been given Author-level permissions to the Calendar folder through EWS will receive an error if the principal forwards a meeting request to the delegate. Outlook does not allow the forwarding flag to be set unless the delegate has Editor permissions.

Example

The following code example shows how to set folder-level permissions when a folder is created. The authenticated user grants user3 the Editor permission level on a new folder named NewFolderWithPermissionsSet that is created in the Inbox default 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.
    }
}

This code example was created by using proxy objects that were created by using Microsoft Visual Studio 2005 and Exchange Web Services in Exchange 2007 SP1.

See Also

Other Resources

Delegate Access Tasks