Access a calendar as a delegate by using EWS in Exchange

Learn how to access a calendar as a delegate by using the EWS Managed API or EWS in Exchange.

You can use the EWS Managed API or EWS to give a user delegate access to a mailbox owner's Calendar folder. The delegate can then create meeting requests on behalf of the mailbox owner, create appointments, respond to meeting requests, and retrieve, update, and delete meetings from the mailbox owner's Calendar folder, depending on their permissions.

As a delegate, you use the same methods and operations to access a mailbox owner's Calendar folder that you use to access your own Calendar folder. The main difference is that you have to use explicit access to find or create a calendar item or calendar subfolder, and then after you identify the item ID or folder ID, you can use implicit access to get, update, or delete the item.

Table 1. EWS Managed API methods and EWS operations for accessing a calendar as a delegate

Prerequisite tasks

Before a user can access a mailbox owner's Calendar folder as a delegate, the user must be added as a delegate with permissions to the mailbox owner's Calendar folder.

A delegate must have a mailbox attached to their account to update the calendar of a mailbox owner.

If a delegate needs to work with meeting requests and responses only, you can add the delegate to the Calendar folder, and use the default MeetingRequestsDeliveryScope.DelegatesAndSendInformationToMe EWS Managed API enumeration value or the DeliverMeetingRequests EWS element value of DelegatesAndSendInformationToMe to send the requests to the delegate and informational messages to the mailbox owner. The delegate then does not need to be given access to the mailbox owner's Inbox folder.

Create a meeting or appointment as a delegate by using the EWS Managed API

The EWS Managed API enables you to use the service object for the delegate user to create calendar items for the mailbox owner. This example shows how to use the Save method to create a meeting and send meeting requests to the attendees.

This example assumes that service is a valid ExchangeService object for the delegate and that the delegate has been granted the appropriate permissions for the mailbox owner's Calendar folder.

private static void DelegateAccessCreateMeeting(ExchangeService service)
{
    Appointment meeting = new Appointment(service);
    // Set the properties on the meeting object to create the meeting.
    meeting.Subject = "Team building exercise";
    meeting.Body = "Let's learn to really work as a team and then have lunch!";
    meeting.Start = DateTime.Now.AddDays(2);
    meeting.End = meeting.Start.AddHours(4);
    meeting.Location = "Conference Room 12";
    meeting.RequiredAttendees.Add("sadie@contoso.com");
    meeting.ReminderMinutesBeforeStart = 60;
    // Save the meeting to the Calendar folder for 
    // the mailbox owner and send the meeting request.
    // This method call results in a CreateItem call to EWS.
    meeting.Save(new FolderId(WellKnownFolderName.Calendar, 
        "primary@contoso.com"), 
        SendInvitationsMode.SendToAllAndSaveCopy);
    // Verify that the meeting was created.
    Item item = Item.Bind(service, meeting.Id, new PropertySet(ItemSchema.Subject));
    Console.WriteLine("\nMeeting created: " + item.Subject + "\n");
}

Note that when you save the item, the Save method call must identify the mailbox owner's Calendar folder. If the mailbox owner's Calendar folder is not specified, the meeting request gets saved to the delegate's calendar and not the mailbox owner's Calendar folder. You can include the mailbox owner's Calendar folder in the Save method call in two ways. We recommend that you instantiate a new instance of the FolderId object by using the WellKnownFolderName and the SMTP address of the mailbox owner.

meeting.Save(new FolderId(WellKnownFolderName.Calendar,
    "primary@contoso.com"), SendInvitationsMode.SendToAllAndSaveCopy);

However, you can also Bind to the Calendar folder first, and then use the ID of the folder in the Save method call. Be aware, however, that this creates an extra EWS call.

    // Identify the mailbox owner's SMTP address
    // and bind to their Calendar folder.
    Mailbox primary = new Mailbox("primary@contoso.com"); 
    Folder primaryCalendar = Folder.Bind(service, 
        new FolderId(WellKnownFolderName.Calendar, primary)); 
…
    // Save the meeting to the Calendar folder for the mailbox owner and send the meeting request.
    meeting.Save(primaryCalendar.Id, 
        SendInvitationsMode.SendToAllAndSaveCopy);

Create a meeting or appointment as a delegate by using EWS

EWS enables you to use the service object for the delegate user to create calendar items for the mailbox owner. This example shows how to use the CreateItem operation to create a meeting and send meeting requests to the attendees.

This is also the XML request that the EWS Managed API sends when you use the Save method to create a meeting or appointment as a delegate.

The SOAP header has been removed from the following example for brevity.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
         xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
         xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
…
  <soap:Body>
    <m:CreateItem SendMeetingInvitations="SendToAllAndSaveCopy">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="calendar">
          <t:Mailbox>
            <t:EmailAddress>primary@contoso.com</t:EmailAddress>
          </t:Mailbox>
        </t:DistinguishedFolderId>
      </m:SavedItemFolderId>
      <m:Items>
        <t:CalendarItem>
          <t:Subject>Team building exercise</t:Subject>
          <t:Body BodyType="HTML">Let's learn to really work as a 
              team and then have lunch!</t:Body>
          <t:ReminderMinutesBeforeStart>60</t:ReminderMinutesBeforeStart>
          <t:Start>2014-03-09T23:26:33.756-05:00</t:Start>
          <t:End>2014-03-10T03:26:33.756-05:00</t:End>
          <t:Location>Conference Room 12</t:Location>
          <t:RequiredAttendees>
            <t:Attendee>
              <t:Mailbox>
                <t:EmailAddress>sadie@contoso.com</t:EmailAddress>
              </t:Mailbox>
            </t:Attendee>
          </t:RequiredAttendees>
        </t:CalendarItem>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

The server responds to the CreateItem request with a CreateItemResponse message that includes a ResponseCode element value of NoError, which indicates that the meeting was created successfully. The response also contains the item ID of the newly created meeting.

Search for a meeting or appointment as a delegate by using the EWS Managed API

To search for a meeting, you must use one of the ExchangeService.FindItems methods that includes a FolderId parameter, so that you can specify the mailbox owner's Calendar folder.

static void DelegateAccessSearchWithFilter
    (ExchangeService service, SearchFilter filter)
{
    // Limit the result set to 10 items.
    ItemView view = new ItemView(10);
    view.PropertySet = new PropertySet(ItemSchema.Subject,
                                       ItemSchema.DateTimeReceived,
                                       EmailMessageSchema.IsRead);
    // Item searches do not support deep traversal.
    view.Traversal = ItemTraversal.Shallow;
    // Define the sort order.
    view.OrderBy.Add(ItemSchema.DateTimeReceived, SortDirection.Descending);
    try
    {
        // Call FindItems to find matching calendar items. 
        // The FindItems parameters must denote the mailbox owner,
        // mailbox, and Calendar folder.
        // This method call results in a FindItem call to EWS.
        FindItemsResults<Item> results = service.FindItems(
        new FolderId(WellKnownFolderName.Calendar, 
            "primary@contoso.com"), 
            filter, 
            view);
        foreach (Item item in results.Items)
        {
            Console.WriteLine("Subject: {0}", item.Subject);
            Console.WriteLine("Id: {0}", item.Id.ToString());
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Exception while 
            enumerating results: {0}", ex.Message);
    }
}

After the FindItems call returns a response with an ID, you can get, update or delete that meeting by using the ID and implicit access — and you do not need to specify the mailbox owner's SMTP address.

Search for a meeting or appointment as a delegate by using EWS

EWS enables you to use the service object for the delegate user to search for appointments and meetings that meet a set of search criteria. This example shows how to use the FindItem operation to find meetings in the mailbox owner's Calendar folder that contain the word "building" in the subject.

This is also the XML request that the EWS Managed API sends when you use the FindItem method to search for a meeting or appointment as a delegate.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:FindItem Traversal="Shallow">
      <m:ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="item:Subject" />
          <t:FieldURI FieldURI="item:DateTimeReceived" />
          <t:FieldURI FieldURI="message:IsRead" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:IndexedPageItemView MaxEntriesReturned="10"
                             Offset="0"
                             BasePoint="Beginning" />
      <m:Restriction>
        <t:Contains ContainmentMode="Substring"
                    ContainmentComparison="IgnoreCase">
          <t:FieldURI FieldURI="item:Subject" />
          <t:Constant Value="building" />
        </t:Contains>
      </m:Restriction>
      <m:SortOrder>
        <t:FieldOrder Order="Descending">
          <t:FieldURI FieldURI="item:DateTimeReceived" />
        </t:FieldOrder>
      </m:SortOrder>
      <m:ParentFolderIds>
        <t:DistinguishedFolderId Id="calendar">
          <t:Mailbox>
            <t:EmailAddress>primary@contoso.com</t:EmailAddress>
          </t:Mailbox>
        </t:DistinguishedFolderId>
      </m:ParentFolderIds>
    </m:FindItem>
  </soap:Body>
</soap:Envelope>

The server responds to the FindItem request with a FindItemResponse message that includes a ResponseCode element value of NoError, which indicates that the search completed successfully. The response contains a CalendarItem for any appointments or meetings that met the search criteria. In this case, only one meeting is found.

The value of the ItemId element has been shortened for readability.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ServerVersionInfo MajorVersion="15"
                         MinorVersion="0"
                         MajorBuildNumber="893"
                         MinorBuildNumber="10"
                         Version="V2_10"
                         xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns="http://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
  </s:Header>
  <s:Body>
    <m:FindItemResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
                        xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:FindItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder IndexedPagingOffset="1"
                        TotalItemsInView="1"
                        IncludesLastItemInRange="true">
            <t:Items>
              <t:CalendarItem>
                <t:ItemId Id="IJpUAAA="
                          ChangeKey="DwAAABYAAADOilbYa8KaT7ZgMoTz2P+hAAAAIKhS" />
                <t:Subject>Team building exercise</t:Subject>
                <t:DateTimeReceived>2014-03-04T21:27:22Z</t:DateTimeReceived>
              </t:CalendarItem>
            </t:Items>
          </m:RootFolder>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </m:FindItemResponse>
  </s:Body>
</s:Envelope>

Now that you have the ItemId for the meeting that meets your criteria, you can get, update, or delete that meeting by using the ItemId and implicit access — and you do not need to specify the mailbox owner's SMTP address.

Get, update, or delete calendar items as a delegate by using the EWS Managed API

You can use the EWS Managed API to get, update, or delete a meeting or appointment in the same way that you perform these actions when you're not using delegate access. The only difference is that the service object is for the delegate user. The item ID included in the Bind method call uniquely identifies the item in the mailbox store, in the mailbox owner's Calendar folder.

Table 2. EWS Managed API methods for working with appointments and meetings as a delegate

Get, update, or delete calendar items as a delegate by using EWS

You can use EWS to get, update, or delete a meeting or appointment in the same way that you perform these actions when you're not using delegate access. The only difference is that the service object is for the delegate user. The item ID included in the GetItem method call uniquely identifies the item in the mailbox store, in the mailbox owner's Calendar folder.

Table 3. EWS operations for working with appointments and meetings as a delegate

See also

• Delegate access and EWS in Exchange
• Add and remove delegates by using EWS in Exchange
• Set folder permissions for another user by using EWS in Exchange
• Calendars and EWS in Exchange