Process contacts in batches by using EWS in Exchange
Learn how to create, get, update, and delete batches of contacts in a single call by using the EWS Managed API or EWS in Exchange.
You can use the EWS Managed API or EWS to work with batches of contacts to reduce the number of calls a client makes to an Exchange server. When you use the EWS Managed API to create, get, update, and delete contacts in batches, you use ExchangeService object methods, whereas when you work with single contacts, you use Contact object methods. If you are using EWS, you use the same operations to work with both a single contact and batches of contacts.
Table 1. EWS Managed API methods and EWS operations for working with batches of contacts
| In order to… | Use this EWS Managed API method | Use this EWS operation |
|---|---|---|
| Create contacts in batches |
ExchangeService.CreateItems |
CreateItem |
| Get contacts in batches |
ExchangeService.BindToItems or ExchangeService.LoadPropertiesForItems |
GetItem |
| Update contacts in batches |
ExchangeService.UpdateItems |
UpdateItem |
| Delete contacts in batches |
ExchangeService.DeleteItems |
DeleteItem |
In this article, you'll learn how to complete basic tasks for batches of contacts by using the EWS Managed API or EWS.
Create contacts in batches by using the EWS Managed API
You can create contacts in batches by using the EWS Managed API CreateItems method, as shown in the following example. This example creates three Contact objects locally, adds each contact to a collection, then calls the CreateItems method on the collection of contacts.
public static Collection<ItemId> CreateContactsInBatch(ExchangeService service)
{
// These are unsaved local instances of a Contact object.
// Despite the required parameter of an ExchangeService object (service), no call
// to an Exchange server is made when the objects are instantiated.
// A call to the Exchange server is made when the service.CreateItems() method is called.
Contact contact1 = new Contact(service);
Contact contact2 = new Contact(service);
Contact contact3 = new Contact(service);
// Set the properties on the first contact.
contact1.DisplayName = "Sadie Daniels";
contact1.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("sadie@contoso.com");
// Set the properties on the second contact.
contact2.DisplayName = "Alfred Welker";
contact2.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("alfred@contoso.com");
// Set the properties on the third contact.
contact3.DisplayName = "Hope Gross";
contact3.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("hope@contoso.com");
// Add the Contact objects to a collection.
Collection<Contact> contactItems = new Collection<Contact>() { contact1, contact2, contact3 };
// Create the batch of contacts on the server.
// This method call results in an CreateItem call to EWS.
ServiceResponseCollection<ServiceResponse> response = service.CreateItems(contactItems, WellKnownFolderName.Contacts, null, null);
// Instantiate a collection of item IDs to populate from the values that are returned by the Exchange server.
Collection<ItemId> itemIds = new Collection<ItemId>();
// Collect the item IDs from the created contacts.
foreach (Contact contact in contactItems)
{
try
{
itemIds.Add(contact.Id);
Console.WriteLine("Contact '{0}' created successfully.", contact.DisplayName);
}
catch (Exception ex)
{
// Print out the exception and the last eight characters of the item ID.
Console.WriteLine("Exception while creating contact {0}: {1}", contact.Id.ToString().Substring(144), ex.Message);
}
}
// Determine whether the CreateItems method call completed successfully.
if (response.OverallResult == ServiceResult.Success)
{
Console.WriteLine("All locally created contacts were successfully created in the Contacts folder.");
Console.WriteLine("\r\n");
}
// If the method did not return success, print the result message for each contact.
else
{
int counter = 1;
foreach (ServiceResponse resp in response)
{
// Print out the result and the last eight characters of the item ID.
Console.WriteLine("Result (contact {0}), id {1}: {2}", counter, itemIds[counter - 1].ToString().Substring(144), resp.Result);
Console.WriteLine("Error Code: {0}", resp.ErrorCode);
Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
Console.WriteLine("\r\n");
counter++;
}
}
return itemIds;
}
Create contacts in batches by using EWS
You can create contacts in batches by using the CreateItem EWS operation, as shown in the following code example. This is also the XML request that the EWS Managed API sends when you use the EWS Managed API to create contacts in batches.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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:CreateItem>
<m:SavedItemFolderId>
<t:DistinguishedFolderId Id="contacts" />
</m:SavedItemFolderId>
<m:Items>
<t:Contact>
<t:DisplayName>Sadie Daniels</t:DisplayName>
<t:EmailAddresses>
<t:Entry Key="EmailAddress1">sadie@contoso.com</t:Entry>
</t:EmailAddresses>
</t:Contact>
<t:Contact>
<t:DisplayName>Alfred Welker</t:DisplayName>
<t:EmailAddresses>
<t:Entry Key="EmailAddress1">alfred@contoso.com</t:Entry>
</t:EmailAddresses>
</t:Contact>
<t:Contact>
<t:DisplayName>Hope Gross</t:DisplayName>
<t:EmailAddresses>
<t:Entry Key="EmailAddress1">hope@contoso.com</t:Entry>
</t:EmailAddresses>
</t:Contact>
</m:Items>
</m:CreateItem>
</soap:Body>
</soap:Envelope>
The server responds to the CreateItem request with a CreateItemResponse message that includes a ResponseCode value of NoError for each of the new contacts, which indicates that each contact was created and saved successfully.
Get contacts in batches by using the EWS Managed API
You can get contacts in batches by using the EWS Managed API BindToItems method, as shown in the following example. This example assumes that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server.
public static Collection<Contact> BatchGetContactItems(ExchangeService service, Collection<ItemId> itemIds)
{
// Create a property set that limits the properties returned by the Bind method to only those that are required.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly, ContactSchema.DisplayName);
// Get the items from the server.
// This method call results in a GetItem call to EWS.
ServiceResponseCollection<GetItemResponse> response = service.BindToItems(itemIds, propSet);
// Instantiate a collection of Contact objects to populate from the values that are returned by the Exchange server.
Collection<Contact> contactItems = new Collection<Contact>();
foreach (GetItemResponse getItemResponse in response)
{
try
{
Item item = getItemResponse.Item;
Contact contact = (Contact)item;
contactItems.Add(contact);
// Print out confirmation and the last eight characters of the item ID.
Console.WriteLine("Found item {0}.", contact.Id.ToString().Substring(144));
}
catch (Exception ex)
{
Console.WriteLine("Exception while getting a contact: {0}", ex.Message);
}
}
// Check for success of the BindToItems method call.
if (response.OverallResult == ServiceResult.Success)
{
Console.WriteLine("All contacts retrieved successfully.");
Console.WriteLine("\r\n");
}
return contactItems;
}
Get contacts in batches by using EWS
You can get contacts in batches by using the GetItem EWS operation and the code in the following example. This is also the XML request that the EWS Managed API sends when you use the EWS Managed API to get contacts in batches. The ItemId attribute has been shortened for readability.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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:GetItem>
<m:ItemShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="contacts:DisplayName" />
</t:AdditionalProperties>
</m:ItemShape>
<m:ItemIds>
<t:ItemId Id="ceJwVAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yS" />
<t:ItemId Id="ceJwWAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yT" />
<t:ItemId Id="ceJwXAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yU" />
</m:ItemIds>
</m:GetItem>
</soap:Body>
</soap:Envelope>
The server responds to the GetItem request with a GetItemResponse message that includes the ID and the display name for each of the requested contacts.
Update contacts in batches by using the EWS Managed API
You can update contacts in batches by using the EWS Managed API UpdateItems method, as shown in the following example. The previous example creates the contact but does not specify who they work for. You can use the code in this example to update all your contacts at once to include their company name.
This example assumes that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server.
public static Collection<Contact> BatchUpdateContactItems(ExchangeService service, Collection<Contact> contactItems)
{
// Update the company name of each contact locally.
foreach (Contact contact in contactItems)
{
// Update the company name of the contact.
contact.CompanyName = "Contoso";
// Print out confirmation with the last eight characters of the item ID and the contact company name.
Console.WriteLine("Updated local contact {0} with the company name '{1}'.", contact.Id.ToString().Substring(144), contact.CompanyName);
}
// Send the item updates to the server.
// This method call results in an UpdateItem call to EWS.
ServiceResponseCollection<UpdateItemResponse> response = service.UpdateItems(contactItems, WellKnownFolderName.Contacts, ConflictResolutionMode.AutoResolve, null, null);
// Verify the success of the UpdateItems method call.
if (response.OverallResult == ServiceResult.Success)
{
Console.WriteLine("All contacts updated successfully.\r\n");
}
// If the method did not return success, print the result message for each contact.
else
{
Console.WriteLine("All contacts were not successfully saved on the server.\r\n");
int counter = 1;
foreach (ServiceResponse resp in response)
{
Console.WriteLine("Result for (contact {0}): {1}", counter, resp.Result);
Console.WriteLine("Error Code: {0}", resp.ErrorCode);
Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
counter++;
}
}
return contactItems;
}
Update contacts in batches by using EWS
You can update contacts in batches by using the GetItem EWS operation, as shown in following code example. This is also the XML request that the EWS Managed API sends when you use the EWS Managed API to update contacts in batches. The ItemId attribute has been shortened for readability.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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:UpdateItem ConflictResolution="AutoResolve">
<m:SavedItemFolderId>
<t:DistinguishedFolderId Id="contacts" />
</m:SavedItemFolderId>
<m:ItemChanges>
<t:ItemChange>
<t:ItemId Id="ceJwVAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yS" />
<t:Updates>
<t:SetItemField>
<t:FieldURI FieldURI="contacts:CompanyName" />
<t:Contact>
<t:CompanyName>Contoso</t:CompanyName>
</t:Contact>
</t:SetItemField>
</t:Updates>
</t:ItemChange>
<t:ItemChange>
<t:ItemId Id="ceJwWAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yT" />
<t:Updates>
<t:SetItemField>
<t:FieldURI FieldURI="contacts:CompanyName" />
<t:Contact>
<t:CompanyName>Contoso</t:CompanyName>
</t:Contact>
</t:SetItemField>
</t:Updates>
</t:ItemChange>
<t:ItemChange>
<t:ItemId Id="ceJwXAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yU" />
<t:Updates>
<t:SetItemField>
<t:FieldURI FieldURI="contacts:CompanyName" />
<t:Contact>
<t:CompanyName>Contoso</t:CompanyName>
</t:Contact>
</t:SetItemField>
</t:Updates>
</t:ItemChange>
</m:ItemChanges>
</m:UpdateItem>
</soap:Body>
</soap:Envelope>
The server responds to the UpdateItem request with an UpdateItemResponse message that includes a ResponseCode value of NoError, which indicates that each of the updates was saved successfully on the server. Any conflicts are reported in the ConflictResult element.
Delete contacts in batches by using the EWS Managed API
You can delete contacts in batches by using the DeleteItems EWS Managed API method, as shown in the following example. This example assumes that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server.
public static void BatchDeleteContactItems(ExchangeService service, Collection<ItemId> itemIds)
{
// Delete the batch of contact objects.
// This method call results in an DeleteItem call to EWS.
ServiceResponseCollection<ServiceResponse> response = service.DeleteItems(itemIds, DeleteMode.SoftDelete, null, AffectedTaskOccurrence.AllOccurrences);
// Check for success of the DeleteItems method call.
// DeleteItems returns success even if it does not find all the item IDs.
if (response.OverallResult == ServiceResult.Success)
{
Console.WriteLine("Contacts deleted successfully.\r\n");
}
// If the method did not return success, print a message.
else
{
Console.WriteLine("Not all contacts deleted successfully.\r\n");
}
}
Delete contacts in batches by using EWS
You can delete contacts in batches by using the DeleteItem EWS operation, as shown in the following code example. This is also the XML request that the EWS Managed API sends when you use the EWS Managed API to delete contacts in batches. The ItemId attribute has been shortened for readability.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://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:DeleteItem DeleteType="SoftDelete" AffectedTaskOccurrences="AllOccurrences">
<m:ItemIds>
<t:ItemId Id="ceJwYAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yY" />
<t:ItemId Id="ceJwZAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yZ" />
<t:ItemId Id="ceJwaAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51ya" />
</m:ItemIds>
</m:DeleteItem>
</soap:Body>
</soap:Envelope>
The server responds to the DeleteItem request with a DeleteItemResponse message that includes a ResponseCode value of NoError for each item that was removed. Note that the operation also returns success if the item ID could not be found.
Verifying that a batch process completed successfully
When one or more contacts in a batched request can't be processed as requested, an error is returned for each contact that failed, and the rest of the contacts in the batch are processed as expected. Failures in batch processing can occur if the item was deleted, and therefore can't be retrieved, or updated, or if the item moved to a different folder, and therefore has a new item ID, and cannot be modified with the item ID sent. The information in this section shows how to get error details about failures in batch processing of contacts.
To verify the success of a batch process by using the EWS Managed API, you can check that the OverallResult property of the ServiceResponseCollection is equal to ServiceResult.Success. If so, all the contacts were processed successfully. If the OverallResult is not equal to ServiceResult.Success, one or more of the contacts were not processed successfully. Each of the objects returned in the ServiceResponseCollection contains the following properties:
These properties contain information about why the contacts could not be processed as requested. The examples in this article print out the Result, ErrorCode, and ErrorMessage for each failed contact. You can use these results to investigate the issue.
For EWS, to verify the success of a batched process, check the ResponseClass attribute for each item being processed. The following is the basic structure of the ResponseMessageType, the base type from which all response messages are derived.
<ResponseMessage ResponseClass="Success | Warning | Error">
<MessageText/>
<ResponseCode/>
<DescriptiveLinkKey/>
<MessageXml/>
</ResponseMessage>
The ResponseClass attribute is set to Success if the contact was processed successfully, or Error if the contact was not processed successfully. For contacts, you will not encounter a Warning during batch processing. If the ResponseClass is Success, the ResponseCode element that follows is also always set to NoError. If the ResponseClass is Error, you need to check the values of the MessageText, ResponseCode, and MessageXml elements to determine what caused the problem. DescriptiveLinkKey is currently unused.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for