How to: Get conversation items by using the EWS Managed API 2.0

Set up to get conversation items by using the EWS Managed API

Before you use the EWS Managed API to get items in a conversation, complete the following tasks:

• Download the EWS Managed API.

• Add a reference to the EWS Managed API.

• Ensure that you have an Exchange 2013 or Exchange Online service account with a major version of 15 or higher.

• Set up a ExchangeService object with the correct credentials and EWS URL. For more information, see Connecting to EWS by using the EWS Managed API 2.0.

Get items in a single conversation by using the conversation identifier

You can get items in a conversation by using the conversation identifier for one conversation item in the Inbox. The following code example shows you how do this. This example provides a set of conversation nodes for the first conversation in the Inbox. The item identifier, subject, and received time for each item will be returned in the response, along with the conversation index and parent conversation index properties. You can use the conversation index properties to reconstruct the node hierarchy.

In this example, all conversation items in the default Deleted Items and Drafts folders are ignored.

static void GetConversationItemsSingleConversation(ExchangeService service)
{
   try
   {
      // Find an item in a conversation. Find the first item.
      FindItemsResults<Item> results = service.FindItems(WellKnownFolderName.Inbox,
                                                         new ItemView(1));

      // Get the conversation identifier of an item. 
      ConversationId convId = results.Items[0].ConversationId;

      // Specify the properties that will be 
      // returned for the items in the conversation.
      PropertySet properties = new PropertySet(BasePropertySet.IdOnly,
                                                ItemSchema.Subject,
                                                ItemSchema.DateTimeReceived);

      // Identify the folders to ignore.
      Collection<FolderId> foldersToIgnore = new Collection<FolderId>() { WellKnownFolderName.DeletedItems, WellKnownFolderName.Drafts };

      // Request conversation items. This results in a call to the service.         
      ConversationResponse response = service.GetConversationItems(convId,
                                                                     properties,
                                                                     null,
                                                                     foldersToIgnore,
                                                                     ConversationSortOrder.TreeOrderDescending);

      // Get the synchronization state of the conversation.
      Console.WriteLine("SyncState: " + response.SyncState);

      Collection<Item> items = new Collection<Item>();

      // Process each node of conversation items.
      foreach (ConversationNode node in response.ConversationNodes)
      {
         Console.WriteLine("Parent conversation index: " + node.ParentConversationIndex);
         Console.WriteLine("Conversation index: " + node.ConversationIndex);
         Console.WriteLine("Conversation node items:");

         // Process each item in the conversation node.
         foreach (Item item in node.Items)
         {
            Console.WriteLine("   Item ID: " + item.Id.UniqueId);
            Console.WriteLine("   Subject: " + item.Subject);
            Console.WriteLine("   Received: " + item.DateTimeReceived);
            items.Add(item);
         }
      }
   }
   // This exception may occur if there is an error with the service.
   catch (ServiceResponseException srException)
   {
      Console.WriteLine(srException);
   }
}

We recommend that you cache the SyncState property for subsequent requests to get items in the conversation.

Get items in many conversations by using the ConversationRequest object

You can use the ConversationRequest object to get items from two or more conversations. The following code example shows you how to do this. This example provides a set of conversation nodes for the first two conversations in the Inbox. The item identifier, subject, and the received time for each item will be returned in the response, along with the conversation index and parent conversation index properties. You can use the conversation index properties to reconstruct the node hierarchy. This example assumes that the first two items in the Inbox are from different conversations.

In this example, all conversation items in the default Deleted Items and Drafts folders are ignored.

static void GetConversationItemsManyConversations(ExchangeService service)
{
   try
   {
      // Find the first two items in the Inbox.  Find the first item. This item will be used to call the GetConversationItems operation.
      FindItemsResults<Item> results = service.FindItems(WellKnownFolderName.Inbox, new ItemView(2));

      // Get the conversation identifier of the first two items in the Inbox. 
      ConversationId convId1 = results.Items[0].ConversationId;
      ConversationId convId2 = results.Items[1].ConversationId;
      
      // Identify two conversation requests. 
      ConversationRequest convR1 = new ConversationRequest();
      convR1.ConversationId = convId1;
      ConversationRequest convR2 = new ConversationRequest();
      convR2.ConversationId = convId2;

      // Create a collection of conversations to fetch. 
      Collection<ConversationRequest> conversations = new Collection<ConversationRequest>();
      conversations.Add(convR1);
      conversations.Add(convR2);

      // Specify the properties that will be returned for the items in the conversation.
      PropertySet properties = new PropertySet(BasePropertySet.IdOnly,
                                                ItemSchema.Subject,
                                                ItemSchema.DateTimeReceived);

      // Identify the folders to ignore.
      Collection<FolderId> foldersToIgnore = new Collection<FolderId>() { WellKnownFolderName.DeletedItems, WellKnownFolderName.Drafts };


      // Request conversation items. This results in a call to the service.
      ServiceResponseCollection<GetConversationItemsResponse> responses = service.GetConversationItems(conversations, properties, foldersToIgnore, ConversationSortOrder.TreeOrderDescending);

      // Process each conversation.
      foreach (GetConversationItemsResponse resp in responses)
      {
         // Identify the synchronization state of the conversation.
         Console.WriteLine("Sync State: " + resp.Conversation.SyncState);

         // Process each node in the conversation.
         foreach (ConversationNode node in resp.Conversation.ConversationNodes)
         {
            Console.WriteLine("Parent conversation index: " + node.ParentConversationIndex);
            Console.WriteLine("Conversation index: " + node.ConversationIndex);
            Console.WriteLine("Conversation node items:");

            // Process each item in the conversation node.
            foreach (Item item in node.Items)
            {
               Console.WriteLine("   Item ID: " + item.Id.UniqueId);
               Console.WriteLine("   Subject: " + item.Subject);
               Console.WriteLine("   Received: " + item.DateTimeReceived);
            }
         }
      }
   }
   // This exception may occur if there is an error with the service.
   catch (ServiceResponseException srException)
   { 
      Console.WriteLine(srException);
   }
}

As a best practice, we recommend that you return only the properties that the client application requires, rather than using the FirstClassProperties option for the BasePropertySet class. We recommend that you cache the SyncState property for subsequent requests to get items in the conversation.

Next steps

This article describes how to get conversation items. For more information about working with items in a conversation, see the following articles:

• How to: Apply conversation actions by using the EWS Managed API 2.0

• Working with items by using the EWS Managed API 2.0

Additional resources

• How to: Find conversations by using the EWS Managed API 2.0

• Working with search by using the EWS Managed API 2.0

• Working with conversations by using the EWS Managed API 2.0

• Core EWS Managed API 2.0 tasks

• Getting started with the EWS Managed API 2.0