FindItem Operation

FindItem Operation

Switch on low bandwidth view

Collapse All

Language Filter

Exchange Server 2007 SP1

FindItem Operation

Topic Last Modified: 2008-11-25

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:

From field for messages.
Sender field for messages.
Organizer field for calendar items.

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="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <FindItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="http://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.

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="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="595" MinorBuildNumber="0" 
                         xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindItemResponse 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: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="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="595" MinorBuildNumber="0" 
                         xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindItemResponse 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: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.

Reference

FindItemType

Other Resources

Finding Items (Exchange Web Services)
Exchange Web Services XML Elements