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:

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

See Also:

Envelope.UID Property

RetrieveEnvelopes Method
RetrieveEnvelopesEx Method
RetrieveSingleMessage Method


Copyright © 2002-2022, AfterLogic Corporation. All rights reserved.