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:
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 |
Specifies the resolution of data/time values in responses from the server, either in seconds or in milliseconds. |
|
Impersonation |
Identifies the user whom the client application is impersonating. |
|
MailboxCulture |
Identifies the RFC3066 culture to be used to access the mailbox. |
|
RequestVersion |
Identifies the schema version for the operation request. |
|
ServerVersion |
Identifies the version of the server that responded to the request. |
|
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.
See Also