SearchMailbox Method  
 

Search the current mailbox for messages that match the specified criteria.

Syntax

object.SearchMailbox( Criteria, Messages, [CharacterSet] )

Parameters

Criteria
A string which consists of one or more keywords which are used to define the search criteria. The following keywords are recognized:
Keyword Description
ANSWERED Match those messages which have the imapFlagAnswered flag set.
BCC address Match those messages which contain the specified address in the BCC header field.
BEFORE date Match those messages which were added to the mailbox prior to the specified date.
BODY string Match those messages where the body contains the specified string.
CC address Match those messages which contain the specified address in the CC header field.
DELETED Match those messages which have the imapFlagDeleted flag set.
DRAFT Match those messages which have the imapFlagDraft flag set.
FLAGGED Match those messages which have the imapFlagUrgent flag set.
FROM address Match those messages which contain the specified address in the FROM header field.
HEADER field string Match those messages which contain the string in the specified header field. If no string is specified, then all messages which contain the header will be matched.
LARGER size Match those messages which are larger than the specified size in bytes.
NEW Match those messages which have the imapFlagRecent flag set, but not the imapFlagSeen flag.
OLD Match those messages which do not have the imapFlagRecent flag set.
ON date Match those messages which were added on the specified date.
RECENT Match those messages which have the imapFlagRecent flag set.
SEEN Match those messages which have the imapFlagSeen flag set.
SENTBEFORE date Match those messages whose Date header value is earlier than the specified date.
SENTON date Match those messages whose Date header value is the same as the specified date.
SENTSINCE date Match those messages whose Date header value is later than the specified date.
SINCE date Match those messages added to the mailbox after the specified date.
SMALLER size Match those messages which are smaller than the specified size in bytes.
SUBJECT string Match those messages whose Subject header contains the specified string.
TEXT string Match those messages whose headers or body contains the specified string.
TO address Match those messages which contain the specified address in the TO header field.
UID sequence Match those messages with unique identifiers in the sequence set.
UNANSWERED Match those messages which do not have the imapFlagAnswered flag set.
UNDELETED Match those messages which do not have the imapFlagDeleted flag set.
UNDRAFT Match those messages which do not have the imapFlagDraft flag set.
UNFLAGGED Match those messages which do not have the imapFlagUrgent flag set.
UNSEEN Match those messages which do not have the imapFlagSeen flag set.
Messages
This argument must be passed as an array of integers which will contain the message numbers of those messages which match the search criteria. The size of the array determines the maximum number of matches that will be returned by the method. Note that the array must specify 32-bit integers. In Visual Basic, this means that the array would be typed as Long. In Visual Basic.NET, the array would be typed as Integer.
CharacterSet
An optional string which specifies the character set to use when searching the mailbox. If this argument is omitted, the default UTF-8 character set will be used. Note that not all servers support searches using anything but the default character set.

Return Value

This method will return the number of messages which were found to match the search criteria. If no messages match the criteria, then the return value will be zero. A return value of -1 indicates an error, and the specific error code can be determined by checking the LastError property.

Remarks

The SearchMailbox method is used to search a mailbox for messages which match a given criteria and return a list of the matching message numbers. The search criteria is composed of one or more search keywords and and optional value to match against. String searches are not case sensitive and partial matches in the message are returned. The message numbers returned by this method are only valid until the mailbox is expunged or another mailbox is selected.

In addition to the listed keywords, the keyword NOT may prefix a keyword to return those messages which do not match the search criteria. For example, "NOT TO user@domain.com" would return those messages which were not addressed to user@domain.com.

If multiple search keywords are specified, the result is the intersection of all those messages which meet the search criteria. For example, a search criteria of "DELETED SINCE 1-Jan-2010" would return all those messages which are marked for deletion and were added to the mailbox after 1 January 2010.

Those search keywords which expect dates must be specified in format dd-mmm-yyyy where the month is the three letter abbreviation for the month name. Note that the internal date the message was added to the mailbox is not the same as the value of the Date header field in the message.

If the search keyword expects a string value and the string contains one or more spaces, you need to enclose the search string in quotes as part of the criteria string. For example, in Visual Basic you could use code like this:

strCriteria = "SUBJECT " + Chr(34) + "search string" + Chr(34)

The quotes around the search string prevents the server from interpreting it as a multiple search criteria to be evaluated. If you are using a search string provided by a user, it is recommended that you always enclose it in quotes to prevent any potential ambiguity in the search. Even if the search string does not contain any spaces, it is always safe to enclose it in quotes.

The UID keyword expects a one or more unique message identifiers. These values may provided as comma separated list, or a range delimited by a colon. For example, "UID 23000:24000" would return all those messages who have UIDs ranging from 23000 through to 24000.

See Also

MailboxName Property, ExamineMailbox Method, SelectMailbox Method