Work with folders by using EWS in Exchange
Learn how to create, get, update, and delete folders by using the EWS Managed API or EWS in Exchange.
EWS in Exchange uses folders to structure and organize mailboxes. You can create new, get, update, and delete folders by using the EWS Managed API or EWS. Each of the methods or operations listed in the following table is performed on a Folder object, a Folder type, or one of the derived folder classes or types.
Table 1. Methods and operations for creating, getting, updating and deleting folders
| In order to… | EWS Managed API method | EWS operation |
|---|---|---|
| Create a folder | Folder.Save | CreateFolder |
| Create a folder hierarchy | Not available | CreateFolderPath |
| Get a folder | Folder.Bind | GetFolder |
| Get a folder hierarchy | Folder.FindFolders | FindFolder |
| Update a folder | Folder.Update | UpdateFolder |
| Delete a folder | Folder.Delete | DeleteFolder |
Create a folder by using the EWS Managed API
The following code example shows how to use the Folder class to create a new generic folder with a DisplayName of "Custom Folder" and a FolderClass property value of IPF.Note. The Folder.Save method saves the folder as a child folder of the Inbox folder.
These examples assume that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server.
// Create a custom folder.
Folder folder = new Folder(service);
folder.DisplayName = "Custom Folder";
folder.FolderClass = "IPF.Note";
// Save the folder as a child folder of the Inbox.
folder.Save(WellKnownFolderName.Inbox);
To create a different type of folder, such as a CalendarFolder, ContactsFolder, SearchFolder, or TasksFolder, create a new instance of the specific class (instead of the generic Folder class) and do not set the FolderClass property. For example, the following code example shows how to create a new TasksFolder.
// Create a custom Tasks folder.
TasksFolder folder = new TasksFolder(service);
folder.DisplayName = "Custom Tasks";
// Save the folder as a child folder in the Inbox folder.
// This method call results in a CreateFolder call to EWS.
folder.Save(WellKnownFolderName.Inbox);
If you try to create an instance of a specific class and also set the FolderClass property, the ErrorNoFolderClassOverride error is thrown.
Note that you cannot batch the creation of multiple folders in a single method call by using the EWS Managed API.
Create a folder by using EWS
You can create a single folder or multiple of folders by using EWS.
To create a single folder, send a CreateFolder operation request message. The CreateFolder operation request indicates that the parent folder is the Inbox, the DisplayName is "Custom Folder", and the FolderClass element value is IPF.Note.
This is also the XML request that the EWS Managed API sends when you create a new folder and call the Folder.Save method.
<?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:CreateFolder>
<m:ParentFolderId>
<t:DistinguishedFolderId Id="inbox" />
</m:ParentFolderId>
<m:Folders>
<t:Folder>
<t:FolderClass>IPF.Note</t:FolderClass>
<t:DisplayName>Custom Folder</t:DisplayName>
</t:Folder>
</m:Folders>
</m:CreateFolder>
</soap:Body>
</soap:Envelope>
The server responds to the CreateFolder request with a CreateFolderResponse message that includes a ResponseCode value of NoError, which indicates that the folder was created successfully, and the FolderId of the newly created message.
To create multiple folders, include multiple Folder elements in the CreateFolder operation request message. All the new folders must be in the same parent folder.
Create a folder hierarchy by using EWS
You can create a folder hierarchy in a single call by using the EWS CreateFolderPath operation. The same functionality is not available in the EWS Managed API. Instead, if you are using the EWS Managed API, you can create folders one by one, as shown in Create a folder by using EWS.
Note
The EWS Managed API does not implement this functionality.
Get a folder by using the EWS Managed API
The following code example shows how to use the Folder.Bind method to get the Inbox folder. As a best practice, limit the properties returned to only those required for your application. This example limits the return properties to only include the Id property by creating a PropertySet object and applying the IdOnly value to the BasePropertySet property.
This example assumes that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server.
// As a best practice, limit the properties returned to only those that are required.
// In this scenario, you only need the FolderId.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly);
// Bind to an existing folder and get only the properties specified in the PropertySet.
// This method call results in a GetFolder call to EWS.
Folder rootfolder = Folder.Bind(service, WellKnownFolderName.Inbox, propSet);
If you need to return additional properties, add properties from the FolderSchema class to the PropertySet, or use one of the overloaded Bind methods that returns all first class properties.
Note that you cannot get multiple folders at one time by using the EWS Managed API. You have to call the Bind method on each folder separately.
Get a folder by using EWS
You can get a single folder or multiple folders by using EWS.
To get a single folder, send a GetFolder operation request message to the server. In the following example, the BaseShape is set to IdOnly, so only the FolderId of the specified folder is returned. The FolderIds element indicates that the folder to retrieve is the Inbox folder.
This is also the XML request that the EWS Managed API sends when you bind to a folder by using the Folder.Bind method.
To get multiple folders, include multiple FolderIds elements in the GetFolder operation request message.
<?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:GetFolder>
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
</m:FolderShape>
<m:FolderIds>
<t:DistinguishedFolderId Id="inbox" />
</m:FolderIds>
</m:GetFolder>
</soap:Body>
</soap:Envelope>
The following XML example shows the GetFolderResponse message that is sent from the server to the client in response to the GetFolder operation request. It only contains the FolderId value of the Inbox folder. The values of some attributes and elements have 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="800"
MinorBuildNumber="16"
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:GetFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:GetFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Folders>
<t:Folder>
<t:FolderId Id="AAAENAAA=" ChangeKey="AQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAEkbCr"/>
</t:Folder>
</m:Folders>
</m:GetFolderResponseMessage>
</m:ResponseMessages>
</m:GetFolderResponse>
</s:Body>
</s:Envelope>
Get a folder hierarchy by using the EWS Managed API
The following code example shows how to retrieve the subfolders for a specified root folder. This example retrieves the subfolders of the MsgFolderRoot folder, which is the root of the IPM Subtree (where your mailbox folders and items are stored).
In this example, a FolderView class object is created to limit the results of the Folder.FindFolders method response. This scenario limits the properties to return to the following: Id, DisplayName, and the extended property that indicates whether the folder is a hidden folder. Set the FolderView.Traversal value to Deep to perform a recursive search so that the server retrieves the subfolders, and set the root folder to MsgFolderRoot, so that the server returns all the user's folders (and the server does not return system folders in the Non-IPM Subtree).
This example assumes that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server.
// Create a new folder view, and pass in the maximum number of folders to return.
FolderView view = new FolderView(folderViewSize);
// Create an extended property definition for the PR_ATTR_HIDDEN property,
// so that your results will indicate whether the folder is a hidden folder.
ExtendedPropertyDefinition isHiddenProp = new ExtendedPropertyDefinition(0x10f4, MapiPropertyType.Boolean);
// As a best practice, limit the properties returned to only those required.
// In this case, return the folder ID, DisplayName, and the value of the isHiddenProp
// extended property.
view.PropertySet = new PropertySet(BasePropertySet.IdOnly, FolderSchema.DisplayName, isHiddenProp);
// Indicate a Traversal value of Deep, so that all subfolders are retrieved.
view.Traversal = FolderTraversal.Deep;
// Call FindFolders to retrieve the folder hierarchy, starting with the MsgFolderRoot folder.
// This method call results in a FindFolder call to EWS.
FindFoldersResults findFolderResults = service.FindFolders(WellKnownFolderName.MsgFolderRoot, view);
Get a folder hierarchy by using EWS
The following XML examples show how to use the FindFolder operation to retrieve a folder hierarchy by using EWS. This example retrieves the msgfolderroot folder, which is the root of the IPM Subtree, and all its subfolders. The Traversal attribute is set to Deep so that the server performs a recursive search of the folder hierarchy and only returns folders and subfolders under the specified root in the response. In this example, the BaseShape element is set to IdOnly so that the server only returns the FolderId element. To make the output easier to understand, include the DisplayName element in your results by including it in the AdditionalProperties element in the request, along with the ExtendedFieldURI value for the PR_ATTR_HIDDEN property, so that you know whether the folders are hidden folders.
This is also the XML request that the EWS Managed API sends when you call the FindFolders method.
<?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:FindFolder Traversal="Deep">
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="folder:DisplayName" />
<t:ExtendedFieldURI PropertyTag="4340"
PropertyType="Boolean" />
</t:AdditionalProperties>
</m:FolderShape>
<m:IndexedPageFolderView MaxEntriesReturned="100"
Offset="0"
BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="msgfolderroot" />
</m:ParentFolderIds>
</m:FindFolder>
</soap:Body>
</soap:Envelope>
The following XML example shows the FindFolderResponse message that is sent from the server to the client in response to the FindFolder operation request. It contains only the FolderId, the DisplayName, and the value of the PR_ATTR_HIDDEN extended property for all the subfolders under the msgrootfolder folder. If the Value element is set to true, the folder should be hidden in the client view.
This is also the XML response that the EWS Managed API sends when you get multiple folders by using the FindFolder method. The values of some attributes and elements have been shortened for readability, and some folders have not been included 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="815"
MinorBuildNumber="6"
Version="V2_7"
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:FindFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:FindFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:RootFolder IndexedPagingOffset="16"
TotalItemsInView="16"
IncludesLastItemInRange="true">
<t:Folders>
<t:CalendarFolder>
<t:FolderId Id="AAAEOAAA="
ChangeKey="AgAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAA3"/>
<t:DisplayName>Calendar</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>false</t:Value>
</t:ExtendedProperty>
</t:CalendarFolder>
<t:ContactsFolder>
<t:FolderId Id="AAAEPAAA="
ChangeKey="AwAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAA4"/>
<t:DisplayName>Contacts</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>false</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:ContactsFolder>
<t:FolderId Id="AAAUKAAA="
ChangeKey="AwAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAS5"/>
<t:DisplayName>Recipient Cache</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:Folder>
<t:FolderId Id="AAAUJAAA="
ChangeKey="AQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAASx"/>
<t:DisplayName>Conversation Action Settings</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:Folder>
…
</t:Folders>
</m:RootFolder>
</m:FindFolderResponseMessage>
</m:ResponseMessages>
</m:FindFolderResponse>
</s:Body>
</s:Envelope>
Update a folder by using the EWS Managed API
The following code example shows how to update the display name of a folder by using the EWS Managed API.
First, create a PropertySet to limit the number of properties that the server returns in the Folder.Bind response. We recommend that you use the IdOnly BasePropertySet to reduce calls to the Exchange database. Next, use the Bind method to bind to the folder to update. Then, update the DisplayName property, and use the Folder.Update method to save the changes.
In this example, we assume that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server. The local variable folderId is the Id of the folder to update.
// As a best practice, only include the ID value in the PropertySet.
PropertySet propertySet = new PropertySet(BasePropertySet.IdOnly);
// Bind to an existing folder and get the FolderId.
// This method call results in a GetFolder call to EWS.
Folder folder = Folder.Bind(service, folderId, propertySet);
// Update the display name of the folder.
folder.DisplayName = "Updated folder name";
// Save the updates.
// This method call results in an UpdateFolder call to EWS.
folder.Update();
Update a folder by using EWS
The following XML examples show how to update the display name of a folder by using EWS.
First, send a GetFolder operation request message to get the folder to update, as shown in Get a folder hierarchy by using EWS.
Next, send an UpdateFolder operation request message to the server to update a folder. The UpdateFolder operation request updates the DisplayName to "Updated Custom Folder".
This is also the XML request that the EWS Managed API sends when you update a folder by using the Folder.Update method. The values of some attributes and elements have 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:UpdateFolder>
<m:FolderChanges>
<t:FolderChange>
<t:FolderId Id="OrV9ZAAA=" ChangeKey="AQAAABYAAABVzRdyy/cHS4XTC9itCRdUAAAOrXWb" />
<t:Updates>
<t:SetFolderField>
<t:FieldURI FieldURI="folder:DisplayName" />
<t:Folder>
<t:DisplayName>Updated Custom Folder</t:DisplayName>
</t:Folder>
</t:SetFolderField>
</t:Updates>
</t:FolderChange>
</m:FolderChanges>
</m:UpdateFolder>
</soap:Body>
</soap:Envelope>
The server responds to the UpdateFolder request with a UpdateFolderResponse message that includes the a ResponseCode value of NoError, and the FolderId of the folder that was updated with an updated ChangeKey attribute value.
Delete a folder by using the EWS Managed API
This article provides a basic example that shows you how to delete a folder by using the EWS Managed API. For more details about deleting folders, see Deleting items by using EWS in Exchange.
To delete a folder by using the EWS Managed API, first, use the Folder.Bind method to bind to the service object to the folder to delete. Next, use the Folder.Delete method to delete the folder by using the HardDelete deletion mode.
This example assumes that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server. The local variable folderId is the Id of the folder to delete.
// Bind to an existing folder and get all its properties.
// This method call results in a GetFolder call to EWS.
Folder folder = Folder.Bind(service, folderId);
// HardDelete the folder.
// This method call results in a DeleteFolder call to EWS.
folder.Delete(DeleteMode.HardDelete);
Delete a folder by using EWS
This article provides a basic XML example that shows you how to delete a folder by using EWS. For more details about deleting folders, see Deleting items by using EWS in Exchange.
To delete a folder by using EWS, first, send a GetFolder operation request message to get the folder to update as shown in Get a folder by using EWS.
Next, send a DeleteFolder operation request message to the server to delete the folder. The DeleteFolder operation request indicates that the DeleteType is HardDelete and it includes the FolderId of the folder to delete.
This is also the XML request that the EWS Managed API sends when you delete a folder by using the Folder.Delete method. The values of some attributes and elements have 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:DeleteFolder DeleteType="HardDelete">
<m:FolderIds>
<t:FolderId Id="OrV9ZAAA=" ChangeKey="AQAAABYAAABVzRdyy/cHS4XTC9itCRdUAAAOrXWf" />
</m:FolderIds>
</m:DeleteFolder>
</soap:Body>
</soap:Envelope>
The server responds to the DeleteFolder request with a DeleteFolderResponse message that includes the a ResponseCode value of NoError, which indicates that the folder deletion was successful.
Next steps
After you have retrieved the folders on the server, or made changes to folders, you might want to synchronize your folder hierarchy or subscribe to notifications about folder changes on the server.
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