Search Method

Searches the currently selected mailbox for messages which meet specified condition.

This method can also sort the results but the IMAP server must support SORT extension for that. Gmail and Outlook.com still don't support SORT to the moment (Feb 2015). If sorting is not supported by the server, this method will fail. To learn how check for an extension, see MoveMessages method's example. It checks for MOVE extension, checking for SORT can be done the same way.

Message numbers (or UIDs) are returned as array of numbers. Lower bound of the array is 1.

By default, this method just returns message numbers or UIDs for all messages in the mailbox. To search for specific items, specify non-empty search Condition.

Condition is a set of search criteria in IMAP4 format. Some popular search keys are listed below:

ALL - all messages
ANSWERED - messages with "\Answered" flag set
BEFORE <date> - messages whose Date is earlier then specified date
BODY <string> - messages that contain specified string in the body
DELETED - messages with "\Deleted" flag set
DRAFT - messages with "\Draft" flag set
FLAGGED - messages with "\Flagged" flag set
FROM <string> - messages that contain specified string in "From:"
HEADER <header name> <string> - messages that have specified header and specified string is contained in the header value
LARGER <number> - messages whose size larger than specified number
NEW - messages with "\Recent" flag set and "\Seen" flag not set. Identical to "(RECENT UNSEEN)"
NOT <search key> - messages that do not satisfy given search key
OLD - messages with "\Recent" flag not set
ON <date> - messages whose Date is within specified date
OR <search key 1> <search key 2> - messages that match at least key 1 or key 2
RECENT - messages with "\Recent" flag set
SEEN - messages with "\Sent" flag set
SUBJECT <string> - messages that contain specified string in "Subject:"
UID <message set> - messages whose UIDs are inside specified UID range
UNSEEN - messages with "\Seen" flag not set

Full list of allowed keys is described in RFC 3501 (INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1).

When multiple keys are specified, the result is the intersection (AND function) of all the messages that match those keys. For example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refers to all deleted messages from Smith that were placed in the mailbox since February 1, 1994. A search key can also be a parenthesized list of one or more search keys (e.g., for use with the OR and NOT keys).

In all search keys that use strings, a message matches the key if the string is a substring of the field. The matching is case-insensitive.

Sorting rule can be "ARRIVAL", "CC", "DATE", "FROM", "SIZE", "SUBJECT", "TO". Sorting is in ascending order. To change order, add "REVERSE" before the key, e.g. "REVERSE ARRIVAL".

Multiple keys are allowed, e.g. "SUBJECT DATE" ("REVERSE" modifier affects only the immediate key after it, subsequent keys are not affected so you may need to specify it multiple times, e.g. "REVERSE SUBJECT REVERSE DATE").

arrIndices = ObjectName.Search(AsUID, [Condition], [Charset])


Parameters:
AsUID As Boolean	If True, returned array will be array of UIDs (unique-IDs). Otherwise, message numbers will be returned
Condition As String	(optional) Search condition. Default is "ALL" (all messages in the currently selected mailbox returned)
Charset as String	(optional) Charset of the string that appear in search criteria. If not specified, default (US-ASCII) charset is assumed
OrderBy as String	(optional) Sorting rule. If not specified, SEARCH command instead of SORT is used and the messages get returned in their natural order in the mailbox

Return value As Variant	Array of Variant/Long, each value is UID or message number of the message. If error has occurred, return value is Empty

Usage example:

' This sample searches Inbox and retrieves unread messages only
Dim Mailer, SearchResults, Message, I
'Using visual basic to create object
Set Mailer = CreateObject("MailBee.IMAP4")
'Using ASP to create object
'Set Mailer = Server.CreateObject("MailBee.IMAP4")
'In ASP use Response.Write instead of MsgBox
Mailer.EnableLogging = True
Mailer.LogFilePath = "C:\Temp\imap4_log.txt"
Mailer.ClearLog
Mailer.LicenseKey = "put your license key here"
If Mailer.Connect("mailserver.com", 143, "MyName", "MyPassword") Then
  If Mailer.SelectMailbox("Inbox") Then
    SearchResults = Mailer.Search(False, "UNSEEN") ' Get list of message numbers of unread messages
    If Not IsEmpty(SearchResults) Then
      For I = LBound(SearchResults) To UBound(SearchResults)
        Set Message = Mailer.RetrieveSingleMessage(SearchResults(I), False)
        If Not Message Is Nothing Then
          MsgBox Message.BodyText
        End If
      Next
    End If
  End If
  Mailer.Disconnect
End If