This documentation provides details about the SearchMailboxes class within the pyews package.

This class is used to search users mailboxes for a specific item.

Search mailboxes based on a search query.


To use any service class you must provide a UserConfiguration object first. Like all service classes, you can access formatted properties from the EWS endpoint using the response property.

The search query parameter takes a specific format, below are examples of different situations as well as comments that explain that situation:

# Searching for a keyword in a subject
# You can specify the word you are looking for as either `account` or `Account`
searchQuery = 'subject:account'

# Searching for an exact string in a subject
searchQuery = 'subject:"Your Account is about to expire"'

# Searching for a url in a email's body
searchQuery = 'body:""'

# You can combine your search query by adding grouping logical operators
# Here is an example of searching for two subject strings and a body string match
searchQuery = 'subject:(account OR phishing) AND body:""'

For more information take a look at Microsoft’s documentation for their= Advanced Query Syntax (AQS)

By passing in a search_query, UserConfiguration object, and a mailbox_id we can search that specific mailbox or a list of mailbox referenceIds

from pyews import UserConfiguration
from pyews import SearchMailboxes

userConfig = UserConfiguration(

referenceId = '/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=5341a4228e8c433ba81b4b4b6d75e100-last.first'
searchResults = SearchMailboxes(userConfig).run('subject:account', referenceId)
search_query (str): A EWS QueryString. More information can be found at userconfiguration (UserConfiguration): A UserConfiguration object created using the UserConfiguration class mailbox_id (str or list): A single or list of mailbox IDs to search. This mailbox id is a ReferenceId search_scope (str, optional): Defaults to ‘All’. The search scope for the provided mailbox ids. The options are [‘All’, ‘PrimaryOnly’, ‘ArchiveOnly’]
ObjectType: An incorrect object type has been used SearchScopeError: The provided search scope is not one of the following options: [‘All’, ‘PrimaryOnly’, ‘ArchiveOnly’]