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 mailFlagAnswered 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 mailFlagDeleted flag set.
DRAFT	Match those messages which have the mailFlagDraft flag set.
FLAGGED	Match those messages which have the mailFlagUrgent 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 mailFlagRecent flag set, but not the mailFlagSeen flag.
OLD	Match those messages which do not have the mailFlagRecent flag set.
ON date	Match those messages which were added on the specified date.
RECENT	Match those messages which have the mailFlagRecent flag set.
SEEN	Match those messages which have the mailFlagSeen 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 mailFlagAnswered flag set.
UNDELETED	Match those messages which do not have the mailFlagDeleted flag set.
UNDRAFT	Match those messages which do not have the mailFlagDraft flag set.
UNFLAGGED	Match those messages which do not have the mailFlagUrgent flag set.
UNSEEN	Match those messages which do not have the mailFlagSeen 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, SelectMailbox Method

Copyright © 2025 Catalyst Development Corporation. All rights reserved.