Synchronize folders by using EWS in Exchange
Find out how to use the EWS Managed API or EWS to get a list of folders, or a list of folders that have changed, in order to synchronize your client.
EWS in Exchange uses item synchronization and folder synchronization to sync mailbox content between the client and server. Folder synchronization gets the initial list of folders from a root folder and then, over time, gets changes that were made to those folders and gets new folders as well.
If you're performing folder synchronization by using the EWS Managed API, you first get the initial list of folders in the root folder by using the ExchangeService.SyncFolderHierarchy method. You then update the value of the cSyncState parameter during subsequent calls to get the list of new and changed folders.
To perform folder synchronization by using EWS, you request the initial list of folders in the root folder by using the SyncFolderHierarchy operation, parse the response, and then at some point in the future get the changes to the folders in the root, and parse the response. After the client receives the list of initial or changed folders, it makes updates locally. How and when you retrieve changes in the future depends on the synchronization design pattern your application is using.
Get the list of all folders or changed folders by using the EWS Managed API
The following code example shows how to get an initial list of folders in a root folder and then get a list of changes to folders in the root folder that have occurred since the previous synchronization. During the initial call to the ExchangeService.SyncFolderHierarchy method, set the cSyncState value to null. When the method completes, save the cSyncState value locally to use in the next SyncFolderHierarchy method call. In both the initial call and the subsequent calls, the folders are retrieved in batches of ten, by using successive calls to the SyncFolderHierarchy method, until no more changes remain. This example sets the propertySet parameter to IdOnly to reduce calls to the Exchange database, which is a synchronization best practice. In this example, we assume that service is a valid ExchangeService object binding and that cSyncState represents the sync state that was returned by a prior call to SyncFolderHierarchy.
// Get a list of all folders in the mailbox by calling SyncFolderHierarchy.
// The folderId parameter must be set to the root folder to synchronize.
// The propertySet parameter is set to IdOnly to reduce calls to the Exchange database
// because any additional properties result in additional calls to the Exchange database.
// The syncState parameter is set to cSyncState, which should be null in the initial call,
// and should be set to the sync state returned by the previous SyncFolderHierarchy call
// in subsequent calls.
ChangeCollection<FolderChange> fcc = service.SyncFolderHierarchy(new FolderId(WellKnownFolderName.Root), PropertySet.IdOnly, cSyncState);
// If the count of changes is zero, there are no changes to synchronize.
if (fcc.Count == 0)
{
Console.WriteLine("There are no folders to synchronize.");
}
// Otherwise, write all the changes included in the response
// to the console.
// For the initial synchronization, all the changes will be of type
// ChangeType.Create.
else
{
foreach (FolderChange fc in fcc)
{
Console.WriteLine("ChangeType: " + fc.ChangeType.ToString());
Console.WriteLine("FolderId: " + fc.FolderId);
Console.WriteLine("===========");
}
}
// Save the sync state for use in future SyncFolderItems requests.
// The sync state is used by the server to determine what changes to report
// to the client.
string fSyncState = fcc.SyncState;
After you retrieve the list of new or changed folders on the server, create or update the folders on the client.
Get the initial list of folders by using EWS
The following example shows an XML request to get the initial folder hierarchy by using the SyncFolderHierarchy operation. This is also the XML request that the EWS Managed API sends when retrieving the list of initial folders by using the SyncFolderHierarchy method. The SyncState element of the SyncFolderHierarchy operation is not included because this is the initial synchronization. This example sets the BaseShape element to IdOnly to reduce calls to the Exchange database, which is a synchronization best practice.
<?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="Exchange2013" />
</soap:Header>
<soap:Body>
<m:SyncFolderHierarchy>
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
</m:FolderShape>
<m:SyncFolderId>
<t:DistinguishedFolderId Id="root" />
</m:SyncFolderId>
</m:SyncFolderHierarchy>
</soap:Body>
</soap:Envelope>
The following example shows the XML response that is returned by the server after it processes the SyncFolderHierarchy operation request. The initial response includes Create elements for all folders because all folders are considered new during an initial synchronization. The values of some attributes and elements have been shortened for readability, and some Create element blocks were removed for brevity.
<?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="785"
MinorBuildNumber="6"
Version="V2_6"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:SyncFolderHierarchyResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:SyncFolderHierarchyResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:SyncState>H4sIAA==</m:SyncState>
<m:IncludesLastFolderInRange>true</m:IncludesLastFolderInRange>
<m:Changes>
<t:Create>
<t:Folder>
<t:FolderId Id="AAMkADM="
ChangeKey="AQAAABYA"/>
</t:Folder>
</t:Create>
<t:Create>
<t:Folder>
<t:FolderId Id="AAMkADMzM="
ChangeKey="AQAAABY"/>
</t:Folder>
</t:Create>
<t:Create>
<t:Folder>
<t:FolderId Id="AAMkAD/AAA="
ChangeKey="AQAAABYA"/>
</t:Folder>
</t:Create>
<t:Create>
<t:Folder>
<t:FolderId Id="AAMkADBh="
ChangeKey="AQAAABYA"/>
</t:Folder>
</t:Create>
...
</m:Changes>
</m:SyncFolderHierarchyResponseMessage>
</m:ResponseMessages>
</m:SyncFolderHierarchyResponse>
</s:Body>
</s:Envelope>
After you retrieve the list of new folders on the server, create the folders on the client.
Get the changes since the last sync by using EWS
The following example shows the XML request to get the list of changes to folders in the root folder by using the SyncFolderHierarchy operation. This is also the XML request that the EWS Managed API sends when retrieving the list of changes to the root folder. This example sets the SyncState element value to the value returned in the previous response. And for demonstration purposes, this example sets the BaseShape element to AllProperties instead of IdOnly to show the additional properties returned. Setting the BaseShape element to IdOnly is a synchronization best practice. The value of SyncState 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="Exchange2013" />
</soap:Header>
<soap:Body>
<m:SyncFolderHierarchy>
<m:FolderShape>
<t:BaseShape>AllProperties</t:BaseShape>
</m:FolderShape>
<m:SyncFolderId>
<t:DistinguishedFolderId Id="root" />
</m:SyncFolderId>
<m:SyncState>H4sIAA==</m:SyncState>
</m:SyncFolderHierarchy>
</soap:Body>
</soap:Envelope>
The following example shows the XML response that is returned by the server after it processes the SyncFolderHierarchy operation request from the client. This response indicates that one folder was updated, one folder was created, and one folder was deleted since the prior synchronization. The value of the SyncState element, Id attributes, and ChangeKey attributes have been shortened for readability.
Remember that the request included the AllPropertiesBaseShape. This is just for demonstration purposes. We recommend that you set the BaseShape element to IdOnly in production.
<?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="745" MinorBuildNumber="21" Version="V2_3"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:SyncFolderHierarchyResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:SyncFolderHierarchyResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:SyncState>H4sIAAA</m:SyncState>
<m:IncludesLastFolderInRange>true</m:IncludesLastFolderInRange>
<m:Changes>
<t:Update>
<t:Folder>
<t:FolderId Id="AAMkADM=" ChangeKey="AQAAABY" />
<t:ParentFolderId Id="AQMkADMzADI1==" ChangeKey="AQAAAA==" />
<t:FolderClass>IPF.Note</t:FolderClass>
<t:DisplayName>Meeting Notes</t:DisplayName>
<t:TotalCount>3</t:TotalCount>
<t:ChildFolderCount>0</t:ChildFolderCount>
<t:EffectiveRights>
<t:CreateAssociated>true</t:CreateAssociated>
<t:CreateContents>true</t:CreateContents>
<t:CreateHierarchy>true</t:CreateHierarchy>
<t:Delete>true</t:Delete>
<t:Modify>true</t:Modify>
<t:Read>true</t:Read>
<t:ViewPrivateItems>true</t:ViewPrivateItems>
</t:EffectiveRights>
<t:UnreadCount>0</t:UnreadCount>
</t:Folder>
</t:Update>
<t:Create>
<t:Folder>
<t:FolderId Id="AAMkADMzM=" ChangeKey="AQAAABYAA" />
<t:ParentFolderId Id="AQMkO67A==" ChangeKey="AQAAAA==" />
<t:FolderClass>IPF.Note</t:FolderClass>
<t:DisplayName>Schedules</t:DisplayName>
<t:TotalCount>0</t:TotalCount>
<t:ChildFolderCount>0</t:ChildFolderCount>
<t:EffectiveRights>
<t:CreateAssociated>true</t:CreateAssociated>
<t:CreateContents>true</t:CreateContents>
<t:CreateHierarchy>true</t:CreateHierarchy>
<t:Delete>true</t:Delete>
<t:Modify>true</t:Modify>
<t:Read>true</t:Read>
<t:ViewPrivateItems>true</t:ViewPrivateItems>
</t:EffectiveRights>
<t:UnreadCount>0</t:UnreadCount>
</t:Folder>
</t:Create>
<t:Delete>
<t:FolderId Id="AAMkAD/AAA=" ChangeKey="AQAAAA==" />
</t:Delete>
</m:Changes>
</m:SyncFolderHierarchyResponseMessage>
</m:ResponseMessages>
</m:SyncFolderHierarchyResponse>
</s:Body>
</s:Envelope>
Update the client
If you're using the EWS Managed API, after you get the list of new or changed folders, use the Folder.Load method to get properties on the new or changed items, compare the properties to the local values, and update or create the folders on the client.
If you're using EWS, use the GetFolder operation to get properties on the new or changed folders and update or create the folders on the client.
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