Search-MapiItems

Description

This cmdlet searches for items in a folder, and optionally its subfolders using a rich text-based search pattern.

Syntax
Note: Parameters in orange are optional.
Search-MapiItems
-FolderMapiObject<Mapi.NET.Folder>
-SearchForString
-RecurseSwitchParameter
-ReturnPropsMapi.NET.Tags[]
Parameters
FolderA Mapi.NET.Folder in which items are searched.
SearchForA text string search pattern used to find items. See remarks for search pattern details.
RecurseA SwitchParameter which, if present, causes the search to walk down thru the subfolders of Folder.
ReturnPropsAn optional list of one or more specific properties to return for each item found. See remarks for default properties returned.
Remarks

This cmdlet provides a powerful search function for finding items in folders.

This cmdlet does not use MAPI's restriction based filtering, but analyzes each item in a folder.  As such, searching for items may take some time to complete since item metadata must be requested for each item.  Additionally, this may incur many network operations if the folder to be search is not cached locally or is not in a PST file.

The ReturnProps parameter allows for specifying properties to be returned for items found.  When this parameter is omitted, the following properties are returned: Subject, Message Delivery Time, and Sender Name.  The EntryID of each matching item is always returned regardless of the values in the ReturnProps parameter.


The SearchFor text is a rich search pattern feature that allows for many advanced search operations. The general format of the search string is as follows:

property_id -operator criteria

This second format is for operators that require 2 criteria elements, such as the -btw (between) operator

property_id -operator criteria1::criteria2

Property_ID should equate to either one of the named values in the Mapi.NET.Tags enumeration or should be a hex value preceded by '0x'.
-operator should be one of the supported operators found below in the Operators table (at bottom of this page).
Criteria should be the value that is compared to Property_ID.


Grouping
Grouping can be done by using the -AND and -OR operators:

prop_1 -operator crit1 -and prop_2 -operator crit2


Nested Groups
Multiple levels of grouping is allowed and operates outward, with the deepest nesting being tested first, working its way out to the outer most grouping:

((prop_1 -operator crit1 -and prop_2 -operator crit2) -or prop_3 -operator crit3)


Quoted Criteria
Criteria that contains any of the special characters used in the search pattern (like parentheses, dashes, etc.) can be wrapped in double-quote marks to prevent confusion:

prop_1 -operator "criteria "with quotes" and (parentheses)"


Negation
The NOT prefix can be placed before a group to negate the results of that comparison:

NOT(prop_1 -operator criteria)


Case Sensitivity
Text based properties are compared without case-sensitivity by default.  A search group can be made case-sensitive by prefixing a group with CASE:

CASE(prop_1 -operator criteria)


Default Null
The default behavior of search is such that properties that exist, but have no value (i.e. null), always fail on search.  This means that a search for a numeric property will fail if the property doesn't exist or is null; e.g. zero is not equal to null.  However, prefixing a group with DEFNULL will cause the property(ies) in the group to be set to their property type's default value if null.  This will change a non-existing integer value to zero and a non-existing string to "" (empty quotes) before the value comparison is performed.

DEFNULL(prop_1 -operator criteria)


Recipient Searching
Properties of recipients of an item can also be searched.  Prefixing a group with RECIP, RECIP:All, or RECIP:Any causes the search processor to perform the operations in the group against the recipients of the item.  RECIP is a shorter version of RECIP:Any.  RECIP:Any means that any recipient that matches the enclosed search pattern causes the item to be included in the search results.  RECIP:All means that all recipients of the item must match the enclosed search pattern.

RECIP(prop_1 -operator criteria)
RECIP:Any(prop_1 -operator criteria)
RECIP:All(prop_1 -operator criteria)


Attachment Searching
Similar to how recipient properties can be searched, attachments can also be searched by prefixing a group with ATTACH, ATTACH:Any, or ATTACH:All.  ATTACH is a shorter version of ATTACH:Any.

ATTACH(prop_1 -operator criteria)
ATTACH:Any(prop_1 -operator criteria)
ATTACH:All(prop_1 -operator criteria)


Wildcard Properties
Wildcards can be used for the Property_ID element of a search in order to search across all properties, or properties of certain types.  Search is successful on the first matching property.  Supported wildcard property identifiers are:

*All properties are searched.
*StringAll string properties are searched.
*NumericAll numeric properties are searched.
*BooleanAll boolean properties are searched.
*BinaryAll binary properties are searched.
*DatesAll date properties are searched.
*GuidAll guid properties are searched.  Note that most GUID properties are actually stored as binary, not guid.

*string -operator criteria


Operators

OperatorValue Types Description
-eqAll TypesThe property and criteria must be equal.  String comparisons not inside a CASE group are compared without case sensitivity.  The entire value must be equal.
-hasString TypesThe property must only contain criteria. If used on non-string values, the operation is treated as -eq
-ne All TypesThe property and criteria must NOT be equal.  String comparisons not inside a CASE group are compared without case sensitivity.
-nhasString TypesThe property must NOT contain criteria.  If used on non-string values, the operation is treated as -neq
-swString TypesThe property must start with criteria.  Comparisons not inside a CASE group are compared without case-sensitivity.
-ewString TypesThe property must end with criteria.  Comparisons not inside a CASE group are compared without case-sensitivity.
-gtNumeric and Date typesThe property must be greater than, but not equal to, criteria.
-gteNumeric and Date typesThe property must be greater than or equal to criteria.
-ltNumeric and Date typesThe property must be less than, but not equal to, criteria.
-lteNumeric and Date typesThe property must be less than or equal to criteria.
-btwNumeric and Date typesThe property must be between, criteria1 and criteria2.  Uses criteria1::criteria2 format.
-matchString TypesThe property must match the Regular Expression pattern found in criteria.
-bandInteger typesIf only a single criteria value is provided, property and criteria are compared with a bitwise AND where a non-zero result is a success.If two criteria are given (criteria1::criteria2 format), then the results are compared as: (property AND criteria1) = criteria2.  This allows for specific searching for individual bit masks in integer types.
-borInteger typesIf only a single criteria value is provided, property and criteria are compared with a bitwise OR where a non-zero result is a success.If two criteria are given (criteria1::criteria2 format), then the results are compared as: (property OR criteria1) = criteria2.  This allows for specific searching for individual bit masks in integer types.
-bxorInteger typesIf only a single criteria value is provided, property and criteria are compared with a bitwise XOR where a non-zero result is a success.If two criteria are given (criteria1::criteria2 format), then the results are compared as: (property XOR criteria1) = criteria2.  This allows for specific searching for individual bit masks in integer types.