Rebex Secure Mail
SMTP, IMAP, POP3, Graph, EWS, S/MIME .NET library
Download 30-day free trial Buy from $299More .NET libraries
-
Rebex Graph
MS Graph API library
-
Rebex MSG
Outlook MSG file format library
-
Rebex Total Pack
All Rebex .NET libraries together
Back to feature list...
EWS - 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...