Partager via

  • Article

FindItem Operation

Last modified: September 06, 2011

Applies to: Exchange Server 2007 | Exchange Server 2010

In this article
FindItem Request Example
Successful FindItem Response
FindItem Error Response

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. Specifying this is required. Note that a soft-deleted traversal combined with a search restriction will result in zero items returned, even if there are items that match the search criteria.

  • The response shape of items. This identifies the properties that are returned in the response. Specifying this is required.

  • The root folders from which to perform the search. Specifying this is required.

  • The paging mechanism for returning view data in pages. Specifying this is optional.

  • Options for grouping and sorting the items that are returned.

  • Search restrictions for filtering the items that are returned.

Remarks

The FindItem operation 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 returns only the Name (EmailAddressType) element and does not return the EmailAddress element in the Mailbox element for the following fields:

  • The From field for messages

  • The Sender field for messages

  • The Organizer field for calendar items

Note

The FindItem operation can return results in a CalendarView element. The CalendarView element returns single calendar items and all occurrences. If a CalendarView element 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 element is not used.

SOAP Headers

The FindItem operation can use the SOAP headers that are listed and described in the following table.

Header

Element

Description

DateTimePrecision

DateTimePrecision

Specifies the resolution of data/time values in responses from the server, either in seconds or in milliseconds.

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.

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 Exchange Web Services (EWS) virtual directory of the computer that is running Microsoft Exchange Server 2010 and 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.

Message elements represent email messages and all other items that are not strongly typed by the EWS schema. Items such as IPM.Sharing and IPM.InfoPath are returned as Message elements. Exchange 2010 does not return the base Item element in responses.

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.