Rebex EWS

EWS, SMTP, MIME, S/MIME libraries for .NET

Download 30-day free trial Buy from $199
More .NET libraries

Back to feature list...

Searching

On this page:

The sample code on this page assumes you have already connected and authenticated to an Exchange server.

Searching basics 

To search for messages in an Exchange mailbox matching specified criteria, use Ews 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. 

// create EWS client instance, connect, log in
var ews = new Rebex.Net.Ews();
ews.Connect(hostname);
ews.Login(username, password);

// find messages in 'Inbox' which arrived today
EwsMessageCollection list = ews.Search(
    EwsFolderId.Inbox,
    EwsItemFields.Full,
    EwsSearchParameter.Arrived(DateTime.Now));

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

' create EWS client instance, connect, log in
Dim ews = New Rebex.Net.Ews()
ews.Connect(hostname)
ews.Login(username, password)

' find messages in 'Inbox' which arrived today
Dim list As EwsItemCollection = ews.SearchItems(
    EwsFolderId.Inbox,
    EwsItemFields.Full,
    EwsSearchParameter.Arrived(DateTime.Now))

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

Note: To search for items, use SearchItems method instead. It's equivalent to Search method, but returns EwsItemCollection of EwsItemInfo objects instead.

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

From, subject, full-text and other criteria 

Exchange 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.
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.
HasFlag(status) Messages that are marked with the specified flag.
Arrived(on) Messages that arrived on the specified date (disregarding time).
Arrived(since, before) Messages that arrived in the specified date/time interval.
Sent(on) Messages that were sent on the specified date (disregarding time).
Sent(since, before) Messages that were sent in the specified date/time interval.
Size(min, max) Messages whose size is within the specified interval.
IsRead(value) Messages that are read or unread depending on the value specified.
More... Click for a complete list...


The following code uses several search criteria together: 

// create EWS client instance, connect, log in
// ...

// find messages in 'Inbox'
// from Joe
// which arrived today
// and contains 'Holiday' in subject
EwsItemCollection list = ews.SearchItems(
    EwsFolderId.Inbox,
        EwsSearchParameter.From("joe@example.org"),
        EwsSearchParameter.Arrived(DateTime.Now),
        EwsSearchParameter.Subject("Holiday"));

' create EWS client instance, connect, log in
' ...

' find messages in 'Inbox'
' from Joe
' which arrived today
' and contains 'Holiday' in subject
Dim list As EwsItemCollection = ews.SearchItems(
    EwsFolderId.Inbox,
        EwsSearchParameter.From("joe@example.org"),
        EwsSearchParameter.Arrived(DateTime.Now),
        EwsSearchParameter.Subject("Holiday"))

Retrieving specific fields 

By default, the Search method returns the Exchange default view (headers such as From, Subject, Size, dates, etc.) To retrieve more (or less) information, use the EwsItemFields argument.

The following code shows how to finds emails from Joe and displays From and To fields: 

// create EWS client instance, connect, log in
// ...

// find messages in 'Inbox' from Joe
EwsItemCollection list = ews.SearchItems(
    EwsFolderId.Inbox,
    EwsItemFields.Id,
    EwsSearchParameter.From("joe@example.org"));

// print some info
foreach (EwsItemInfo item in list)
{
    EwsMessageInfo info = ews.GetMessageInfo(item.Id, EwsItemFields.Envelope);
    Console.WriteLine("[From: {0} To: {1}] {2}", info.From, info.To, info.Subject);
}

' create EWS client instance, connect, log in
' ...

' find messages in 'Inbox' from Joe
Dim list As EwsItemCollection = ews.SearchItems(
    EwsFolderId.Inbox,
    EwsItemFields.Id,
    EwsSearchParameter.From("joe@example.org"))

' print some info
For Each item As EwsItemInfo In list
    Dim info As EwsMessageInfo = ews.GetMessageInfo(item.Id, EwsItemFields.Envelope)
    Console.WriteLine("[From: {0} To: {1}] {2}", info.From, info.To, info.Subject)
Next

Note: Search method cannot retrieve To and Body fields. This is due to limitations in Exchange server. As a workaround, use the approach demonstrated by the code above.

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. 

// create EWS client instance, connect, log in
// ...

// find messages in Inbox from
// Joe OR John,
// AND whose subject contains "Holiday",
// AND NOT arrived today
EwsItemCollection list = ews.SearchItems(
    EwsFolderId.Inbox,
        EwsSearchParameter.Or(
            EwsSearchParameter.From("joe@example.org"),
            EwsSearchParameter.From("john@example.org")),
        EwsSearchParameter.Subject("Holiday"),
        EwsSearchParameter.Not(EwsSearchParameter.Arrived(DateTime.Now)));

' create EWS client instance, connect, log in
' ...

' find messages in Inbox from
' Joe OR John,
' AND whose subject contains "Holiday",
' AND NOT arrived today
Dim list As EwsItemCollection = ews.SearchItems(
    EwsFolderId.Inbox,
        EwsSearchParameter.Or(
            EwsSearchParameter.From("joe@example.org"),
            EwsSearchParameter.From("john@example.org")),
        EwsSearchParameter.Subject("Holiday"),
        EwsSearchParameter.Not(EwsSearchParameter.Arrived(DateTime.Now)))

Paging results 

Exchange server has a threshold for maximum number of items returned in a single search call. Depending on the server version and configuration, the threshold is at several hundreds or thousands of items.

To make it possible to work with folders that contain more items, use one of the two kinds of page views:

  • Indexed page view - specify an index (offset) of the first item to be retrieved.
    This is suitable for paged views where the number of pages is displayed and the user can navigate between pages by clicking 'Next' and 'Previous' buttons.
  • Fractional page view
    The first item to be retrieved is determined by a fraction (such as 1/2 or 33/100), where the whole represents the total number of items in the specified folder.
    This is suitable for scrolling views where the user can drag the scrollbar to any position.

The following code shows how to use indexed page views: 

// create EWS client instance, connect, log in
// ...


// find messages in 'Inbox' from Joe and
// retrieve up to 25 messages
// starting with the one with an offset of 150
EwsItemCollection list = ews.SearchItems(
    EwsFolderId.Inbox,
    EwsPageView.CreateIndexed(100, 25),
    EwsSearchParameter.From("joe@example.org"));

' create EWS client instance, connect, log in
' ...

' find messages in 'Inbox' from Joe and
' retrieve up to 25 messages
' starting with the one with an offset of 150
Dim list As EwsItemCollection = ews.SearchItems(
    EwsFolderId.Inbox,
    EwsPageView.CreateIndexed(150, 25),
    EwsSearchParameter.From("joe@example.org"))

The following code shows how to use fractional page views: 

// create EWS client instance, connect, log in
// ...

// find messages in 'Inbox' from Joe and
// retrieve up to 25 messages
// starting with the one at 33 % (33/100) of the results
EwsItemCollection list = ews.SearchItems(
    EwsFolderId.Inbox,
    EwsPageView.CreateFractional(33, 100, 25),
    EwsSearchParameter.From("joe@example.org"));

' create EWS client instance, connect, log in
' ...

' find messages in 'Inbox' from Joe and
' retrieve up to 25 messages
' starting with the one at 33 % (33/100) of the results
Dim list As EwsItemCollection = ews.SearchItems(
    EwsFolderId.Inbox,
    EwsPageView.CreateFractional(33, 100, 25),
    EwsSearchParameter.From("joe@example.org"))

To determine additional information about the paged result, check the PageResult property of the returned collection: 

// print some info
Console.WriteLine("Items found: {0}", list.PageResult.ItemsTotal);
Console.WriteLine("Items in page: {0}", list.Count);
if (list.PageResult.IsLastPage)
    Console.WriteLine("This is last page.");
else
    Console.WriteLine("Continue at offset: {0}", list.PageResult.NextOffset);

' print some info
Console.WriteLine("Items found: {0}", list.PageResult.ItemsTotal)
Console.WriteLine("Items in page: {0}", list.Count)
If list.PageResult.IsLastPage Then
    Console.WriteLine("This is last page.")
Else
    Console.WriteLine("Continue at offset: {0}", list.PageResult.NextOffset)
End If

Tip: See Message listing for more information about paging.

Back to feature list...