• Article

FindItem Operation

Topic Last Modified: 2009-07-31

The FindItem operation identifies items that are located in a specified folder. You can specify the following in a FindItem request:

  • Whether the search is a shallow or soft-deleted traversal. This is required.
  • The response shape of items. This identifies the properties that are returned in the response. This is required.
  • The root folders from which to perform the search. This is required.
  • Paging mechanism for returning view data in pages. This is optional.
  • Options for grouping and sorting the items that are returned.
  • Search restrictions for filtering the items that are returned.

Remarks

FindItem 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. It does not return any of the message body formats or the recipient lists. FindItem will return a recipient summary. You can use the GetItem Operation to get the details of an item.

FindItem only returns the Name (EmailAddressType) element and does not return the EmailAddress element in the Mailbox element for the following fields:

Note

The FindItem operation can return results in a CalendarView. The CalendarView returns single calendar items and all occurrences. If a CalendarView is not used, single calendar items and recurring master calendar items are returned. The occurrences must be expanded from the recurring master if a CalendarView is not used.

FindItem Request Example

Description

The following example of a FindItem request shows how to obtain the item identifier that is defined by the IdOnly enumeration of the BaseShape element for items that are found in the Deleted Items folder.

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>
    <FindItem xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
              Traversal="Shallow">
      <ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
      </ItemShape>
      <ParentFolderIds>
        <t:DistinguishedFolderId Id="deleteditems"/>
      </ParentFolderIds>
    </FindItem>
  </soap:Body>
</soap:Envelope>

Request Elements

The following elements are used in the request:

Note

The schema that describes this element is located in the EWS virtual directory of the computer that is running Microsoft Exchange Server 2007 that has the Client Access server role installed.

For more options for a FindItem request message, explore the schema hierarchy. Start at the FindItem element.

Successful FindItem Response

Description

The following example shows a successful response to the FindItem request.

Starting with Exchange 2007 SP1 with Update Rollup 4 (RU4) applied, Message elements represent e-mail messages and all other items that are not strongly typed by the Exchange Web Services (EWS) schema. This behavior is applied when the Exchange2007_SP1 version header is specified. Items such as IPM.Sharing and IPM.InfoPath are returned as Message elements. Exchange Server 2007 SP1 with RU4 applied and later versions will not return the base Item element in responses. This change may break applications that parse the XML and expect the Item element instead of the Message element.

Note

The item identifiers and change keys 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="595" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindItemResponse 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:FindItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder TotalItemsInView="10" IncludesLastItemInRange="true">
            <t:Items>
              <t:Message>
                <t:ItemId Id="AS4AUn=" ChangeKey="fsVU4==" />
              </t:Message>
              <t:Message>
                <t:ItemId Id="AS4AUM=" ChangeKey="fsVUA==" />
              </t:Message>
            </t:Items>
          </m:RootFolder>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </FindItemResponse>
  </soap:Body>
</soap:Envelope>

Response Elements

The following elements are used in the response:

For more options for a FindItem response message, explore the schema hierarchy. Start at the FindItemResponse element.

FindItem Error Response

Description

The following example shows an error response to a FindItem request.

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="595" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindItemResponse 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:FindItemResponseMessage ResponseClass="Error">
          <m:MessageText>Id is malformed.</m:MessageText>
          <m:ResponseCode>ErrorInvalidIdMalformed</m:ResponseCode>
          <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </FindItemResponse>
  </soap:Body>
</soap:Envelope>

Error Response Elements

The following elements are used in the error response:

For more options for a FindItem error response message, explore the schema hierarchy. Start at the FindItemResponse element.