FindFolder operation
The FindFolder operation uses Exchange Web Services to find subfolders of an identified folder and returns a set of properties that describe the set of subfolders.
FindFolder returns only the first 512 bytes of any streamable property. For Unicode, it returns the first 255 characters by using a null-terminated Unicode string.
Deep traversal queries cannot be performed on public folders.
Restrictions are permitted and should use only the folder properties, not the item properties. Sorting functionality is not available for FindFolder responses. Grouped queries are not available for FindFolder queries.
[!NOTE} The FindFolder operation is also used to find managed folders.
SOAP Headers
The FindFolder operation can use the SOAP headers that are listed and described in the following table.
| Header | Element | Description |
|---|---|---|
| Impersonation | ExchangeImpersonation | Identifies the user whom the client application is impersonating. |
| MailboxCulture | MailboxCulture | Identifies the RFC3066 culture to be used to access the mailbox. |
| RequestVersion | RequestServerVersion | Identifies the schema version for the operation request. |
| ServerVersion | ServerVersionInfo | Identifies the version of the server that responded to the request. |
| TimeZoneContext | TimeZoneContext | Identifies the time zone to be used for all responses from the server. |
FindFolder request example
The following example of a FindFolder request shows how to form a request to find all the folders located in an Inbox.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<FindFolder Traversal="Shallow" xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<FolderShape>
<t:BaseShape>Default</t:BaseShape>
</FolderShape>
<ParentFolderIds>
<t:DistinguishedFolderId Id="inbox"/>
</ParentFolderIds>
</FindFolder>
</soap:Body>
</soap:Envelope>
Using the Default value for the BaseShape, the response returns the folder name, the folder ID, the number of subfolders, the number of child folders found in the folder, and the count of unread items.
FindFolder request elements
This FindFolder request includes the following elements:
For additional FindFolder request elements, see the schema.
FindFolder response example
The following Simple Object Access Protocol (SOAP) body example shows a successful response to the FindFolder request. The response contains the elements that are returned when the Default value for the BaseShape is used.
Note
The folder ID and the change key have been shortened to preserve readability.
<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="652" MinorBuildNumber="0"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<FindFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<m:ResponseMessages>
<m:FindFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:RootFolder TotalItemsInView="1" IncludesLastItemInRange="true">
<t:Folders>
<t:Folder>
<t:FolderId Id="AQAnAH" ChangeKey="AQAAABY" />
<t:DisplayName>TestFolder</t:DisplayName>
<t:TotalCount>0</t:TotalCount>
<t:ChildFolderCount>0</t:ChildFolderCount>
<t:UnreadCount>0</t:UnreadCount>
</t:Folder>
</t:Folders>
</m:RootFolder>
</m:FindFolderResponseMessage>
</m:ResponseMessages>
</FindFolderResponse>
</soap:Body>
</soap:Envelope>
FindFolder response elements
The properties that are returned in the response are determined by the BaseShape and the AdditionalProperties if they are used. A successful FindFolder response includes the following elements:
- ServerVersionInfo
- FindFolderResponse
- ResponseMessages
- FindFolderResponseMessage
- ResponseCode
- RootFolder (FindItemResponseMessage)
- Folders
- Folder
- FolderId
- DisplayName (string)
- TotalCount
- ChildFolderCount
- UnreadCount
FindFolder responses to a request with the AllProperties response shape will not return the TotalCount and UnreadCount elements for public folder searches.
FindFolder Error response example
The following SOAP body example shows an error response that occurs when you search for a folder that is identified by a malformed folder identifier.
<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="652" MinorBuildNumber="0"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<FindFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<m:ResponseMessages>
<m:FindFolderResponseMessage ResponseClass="Error">
<m:MessageText>Id is malformed.</m:MessageText>
<m:ResponseCode>ErrorInvalidIdMalformed</m:ResponseCode>
<m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
</m:FindFolderResponseMessage>
</m:ResponseMessages>
</FindFolderResponse>
</soap:Body>
</soap:Envelope>
FindFolder error response elements
The FindFolder error response includes the following elements:
Additional Information
- The folder DisplayName (string) element is always included in the default shape.
- The UnreadCount element is included in Tasks and Notes folders.
- Use the PropertyTag value of 0x672D with a property type of Integer to identify a managed folder by using the ExtendedFieldURI element.