Share via


FindFolder Operation

Last modified: September 14, 2011

Applies to: Exchange Server 2007 | Exchange Server 2010

In this article
FindFolder Request Example
FindFolder Response Example
FindFolder Error Response Example
Additional Information

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.

Remarks

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

Description

The following example of a FindFolder request shows how to form a request to find all the folders located in an Inbox.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
  xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <FindFolder Traversal="Shallow" xmlns="https://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>

Comments

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.

Request Elements

This FindFolder request includes the following elements:

For additional FindFolder request elements, see the schema.

FindFolder Response Example

Description

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.

Code

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://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="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                        xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                        xmlns="https://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>

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:

Comments

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

Description

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.

Code

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://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="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                          xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                          xmlns="https://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>

Error Response Elements

The FindFolder error response includes the following elements:

Additional Information

  • The folder DisplayName 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.

See Also

Other Resources