FindFolder operation

Article
03/29/2023

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:

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.

Share via