More .NET components

IMAP - searching

Searching basics #

IMAP features a powerful SEARCH command. To search for messages matching specified criteria, use Imap object's Search method. It accepts a variable number of search parameters and supports basic logical operators, which makes complex queries possible.

Tip: You can choose which message fields to retrieve to improve the performance of your application.

Note: Please note that searching only operates on the selected folder.

CSharp

// create IMAP client instance, connect, log in, select folder
var imap = new Rebex.Net.Imap();
imap.Connect(hostname, SslMode.Implicit);
imap.Login(username, password);
imap.SelectFolder("Inbox");

// find messages from Joe
ImapMessageCollection list = imap.Search(ImapSearchParameter.From("joe@example.org"));

// print some info about mails from Joe
foreach (ImapMessageInfo info in list)
{
    Console.WriteLine("[{0}] {1}", info.ReceivedDate, info.Subject);
}

VisualBasic

' create IMAP client instance, connect, log in, select folder
Dim imap As New Rebex.Net.Imap()
imap.Connect(hostname, SslMode.Implicit)
imap.Login(username, password)
imap.SelectFolder("Inbox")

' find messages from Joe
Dim list As ImapMessageCollection =
    imap.Search(ImapSearchParameter.From("joe@example.org"))

' print some info about mails from Joe
For Each info As ImapMessageInfo In list
    Console.WriteLine("[{0}] {1}", info.ReceivedDate, info.Subject)
Next

Tip: See the table bellow for common search criteria or the complete list of more.

From, subject, full-text and other criteria #

IMAP offers a lot of search parameters. The table below lists some of them. See the API documentation for the complete list of search criteria.

Search parameter Description
From(address) Messages that contain the specified string in their From field.
To(address) Messages that contain the specified string in their To field.
CC(address) Messages that contain the specified string in their CC field.
Bcc(address) Messages that contain the specified string in their BCC field.
Subject(queryTerm) Messages that contain the specified string in their Subject field.
Body(queryTerm) Messages that contain the specified string in their body.
FullText(queryTerm) Messages that contain the specified string in their headers or body.
Arrived(on) Messages that arrived on the specified date (disregarding time).
Arrived(since, before) Messages that arrived in the specified date interval (disregarding time).
Sent(on) Messages that were sent on the specified date (disregarding time).
Sent(since, before) Messages that were sent in the specified date interval (disregarding time).
HasFlagsAllOf(flags) Messages with all the specified flags set.
HasFlagsNoneOf(flags) Messages with none of the specified flags set.
Header(headerName, query) Messages that contain the specified string in the specified header.
Size(min, max) Messages whose size is within the specified interval.
Unread Messages that don't have the Seen flag set.
All Search for all messages. Same as GetMessageList method.
More... Click for a complete list...


The following code uses several search criteria together:

CSharp

// create IMAP client instance, connect, log in, select folder
// ...

// find messages from Joe which arrived today (IMAP ignores the time part)
// and have "Holiday" in subject
ImapMessageCollection list = imap.Search(
    ImapSearchParameter.From("joe@example.org"),
    ImapSearchParameter.Arrived(DateTime.Now),
    ImapSearchParameter.Subject("Holiday"));

VisualBasic

' create IMAP client instance, connect, log in, select folder
' ...

' find messages from Joe which arrived today (IMAP ignores the time part)
' and have "Holiday" in subject
Dim list As ImapMessageCollection = imap.Search(
    ImapSearchParameter.From("joe@example.org"),
    ImapSearchParameter.Arrived(DateTime.Now),
    ImapSearchParameter.Subject("Holiday"))

Retrieving specific fields #

By default, the Search method returns the Envelope information (headers such as Date, From, To, Subject). To retrieve more (or less) information, use ImapListFields argument.

The following code finds emails from Joe and retrieves the Envelope and message bodies:

CSharp

// create IMAP client instance, connect, log in, select folder
// ...

// find messages from Joe
// retrieve Envelope and Body
ImapMessageCollection list = imap.Search(
    ImapListFields.Envelope | ImapListFields.Body,
    ImapSearchParameter.From("joe@example.org"));

// print some info about mails from Joe
foreach (ImapMessageInfo info in list)
{
    Console.WriteLine("[{0}] {1}", info.ReceivedDate, info.Subject);
    Console.WriteLine("-----");
    if (info.HasBodyText)
        Console.WriteLine(info.BodyText);
    else
        Console.WriteLine("... no text body to show ...");
    Console.WriteLine("-----");
}

VisualBasic

' create IMAP client instance, connect, log in, select folder
' ...

' find messages from Joe
' retrieve Envelope and Body
Dim list As ImapMessageCollection = imap.Search(
    ImapListFields.Envelope Or ImapListFields.Body,
    ImapSearchParameter.From("joe@example.org"))

' print some info about mails from Joe
For Each info As ImapMessageInfo In list
    Console.WriteLine("[{0}] {1}", info.ReceivedDate, info.Subject)
    Console.WriteLine("-----")
    If info.HasBodyText Then
        Console.WriteLine(info.BodyText)
    Else
        Console.WriteLine("... no text body to show ...")
    End If
    Console.WriteLine("-----")
Next

Searching within a message subset #

In some cases, you already have a subset of messages and you would like only search in this specific subset. This can be done with ImapSearchParameter.MessageSet method:

CSharp

// create IMAP client instance, connect, log in, select folder
// ...

// find messages from Joe
ImapMessageCollection list = imap.Search(
    ImapListFields.UniqueId,
    ImapSearchParameter.From("joe@example.org"));

// create message set based on found mails
ImapMessageSet uidset = list.ToUniqueIdMessageSet();

// perform some searches within message set (mails from Joe)
ImapMessageCollection list1 = imap.Search(
    ImapSearchParameter.MessageSet(uidset),
    ImapSearchParameter.Unread);

ImapMessageCollection list2 = imap.Search(
    ImapSearchParameter.MessageSet(uidset),
    ImapSearchParameter.FullText("Holiday"));

VisualBasic

' create IMAP client instance, connect, log in, select folder
' ...

' find messages from Joe
Dim list As ImapMessageCollection = imap.Search(
    ImapListFields.UniqueId,
    ImapSearchParameter.From("joe@example.org"))

' create message set based on found mails
Dim uidset As ImapMessageSet = list.ToUniqueIdMessageSet()

' perform some searches within message set (mails from Joe)
Dim list1 As ImapMessageCollection = imap.Search(
    ImapSearchParameter.MessageSet(uidset),
    ImapSearchParameter.Unread)

Dim list2 As ImapMessageCollection = imap.Search(
    ImapSearchParameter.MessageSet(uidset),
    ImapSearchParameter.FullText("Holiday"))

Logical operators - AND, OR, NOT #

You can combine search criteria using And, Or and Not logical operators. Please note that Search method combines given arguments using And operator by default when multiple criteria are specified.

CSharp

// create IMAP client instance, connect, log in, select folder
// ...

// find messages from Joe OR John,
// AND whose subject contains "Holiday",
// AND are NOT marked as deleted
ImapMessageCollection list = imap.Search(
    ImapSearchParameter.Or(
        ImapSearchParameter.From("joe@example.org"),
        ImapSearchParameter.From("john@example.org")),
    ImapSearchParameter.Subject("Holiday"),
    ImapSearchParameter.Not(ImapSearchParameter.Deleted));

VisualBasic

' create IMAP client instance, connect, log in, select folder
' ...

' find messages from Joe OR John,
' AND whose subject contains "Holiday",
' AND are NOT marked as deleted
Dim list As ImapMessageCollection = imap.Search(
    ImapSearchParameter.Or(
        ImapSearchParameter.From("joe@example.org"),
        ImapSearchParameter.From("john@example.org")),
    ImapSearchParameter.Subject("Holiday"),
    ImapSearchParameter.Not(ImapSearchParameter.Deleted))