• Article

Adding delegates by using the EWS Managed API 2.0

Last modified: October 13, 2012

Applies to: EWS Managed API | Exchange Server 2007 Service Pack 1 (SP1) | Exchange Server 2010

Note: This content applies to the EWS Managed API 2.0 and earlier versions. For the latest information about the EWS Managed API, see Web services in Exchange.

You can use the Microsoft Exchange Web Services (EWS) Managed API to give delegates access to the resources of another account. These delegates can then act on behalf of the account holder to perform tasks for which they are granted permissions.

You can grant delegates to act on behalf of the primary account holder in these areas:

  • Calendars

  • Contacts

  • Inbox

  • Journal

  • Notes

  • Tasks

To add a delegate for an account

  1. Create a delegate object that represents the user who is to be added as a delegate.

    DelegateUser newDelegate = new DelegateUser("delegate@email.address);

  2. Set the permissions that you want to grant to the delegate on the DelegateUser object.

    newDelegate.Permissions.CalendarFolderPermissionLevel = DelegateFolderPermissionLevel.Editor;

  3. Create a list of delegates to add and add the new delegate to the list. This example uses a generic List object to hold the delegate list.

    List<DelegateUser>delegatesToAdd = new List<DelegateUser>();
delegatesToAdd.Add(newDelegate);

  4. Create a Mailbox object to represent the account that the delegates are being added to.

    Mailbox mailbox = new Mailbox("primaryAccount@email.address");

  5. Call the AddDelegates method to add the new delegate.

    Collection<DelegateUserResponse> result = service.AddDelegates(mailbox, MeetingRequestsDeliveryScope.DelegatesAndMe, delegatesToAdd);

The AddDelegates method adds the specified account holders as delegates of the primary account. The list of account holders can be either an array of DelegateUser objects, or any object that implements the IEnumberable interface and returns DelegateUser objects.

This procedure assumes that a valid ExchangeService object is bound to the primary user's account, or that the primary user's account is being impersonated.

Example

The following code example shows how to add delegates to a primary user by using the AddDelegates method.

    public Collection<DelegateUserResponse> AddDelegates()
    {
      // Bind to the service by using the primary e-mail address credentials.
      ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
      service.Credentials = new NetworkCredential(user1Name, user1Password, emailDomain);
      service.AutodiscoverUrl(user1Email);

      // Create a list to hold the new delegates to add.
      List<DelegateUser> newDelegates = new System.Collections.Generic.List<DelegateUser>();

      // Create a new delegate that has read access to the primary user's calendar.
      DelegateUser calendarDelegate = new DelegateUser(user2Email);
      calendarDelegate.Permissions.CalendarFolderPermissionLevel = DelegateFolderPermissionLevel.Editor;

      // Add the delegate to the list of new delegates.
      newDelegates.Add(calendarDelegate);

      // Create a new delegate that can add tasks to the primary user's task list.
      DelegateUser taskDelegate = new DelegateUser(user3Email);

      // Turn off appointments since this delegate is not for calendar items.
      taskDelegate.ReceiveCopiesOfMeetingMessages = false;

      taskDelegate.Permissions.TasksFolderPermissionLevel = DelegateFolderPermissionLevel.Author;
      taskDelegate.Permissions.InboxFolderPermissionLevel = DelegateFolderPermissionLevel.Editor;
      
      // Add the delegate to the list of new delegates.
      newDelegates.Add(taskDelegate);

      // Create a mailbox object that represents the primary user.
      Mailbox mailbox = new Mailbox(user1Email);

      // Call the AddDelegates method to add the delegates to the primary user's mailbox.
      Collection<DelegateUserResponse> response = service.AddDelegates(mailbox, MeetingRequestsDeliveryScope.DelegatesAndSendInformationToMe, newDelegates);

      return response;
    }

The AddDelegates method in the code example returns a list of DelegateUserResponse objects, one for each delegate that is added to the primary account.

Examine the DelegateUserResponse objects to determine the success or failure for each delegate. If the response contains the ErrorDelegateAlreadyExists enumeration value in the ServiceResult property, use the UpdateDelegate operation to modify the delegate's access to the primary account.

Compiling the code

For information about compiling this code, see Getting started with the EWS Managed API 2.0.

Robust programming

  • Write appropriate error handling code for common search errors.

  • Review the client request XML that is sent to the Exchange server.

  • Review the server response XML that is sent from the Exchange server.

  • Set the service binding as shown in Setting the Exchange service URL by using the EWS Managed API 2.0. Do not hard code URLs because if mailboxes move, they might be serviced by a different Client Access server. If the client cannot connect to the service, retry setting the binding by using the AutodiscoverUrl(String) method.

  • Set the target Exchange Web Services schema version by setting the requestedServerVersion parameter of the ExchangeService constructor. For more information, see Versioning EWS requests by using the EWS Managed API 2.0.

Security

  • Use HTTP with SSL for all communication between client and server.

  • Always validate the server certificate that is used for establishing the SSL connections. For more information, see Validating X509 certificates by using the EWS Managed API 2.0.

  • Do not include user names and passwords in trace files.

  • Verify that Autodiscover lookups that use HTTP GET to find an endpoint always prompt for user confirmation; otherwise, they should be blocked.