Swimlane research team open sources py-ews

2 Minute Read


Phishing impacts every organization, and security operations (SecOps) teams need to act quickly to remediate and prevent unknown threats within their email infrastructure. To help combat these threats, the Swimlane research team has open sourced py-ews to enable security and IT teams to interact with Microsoft Exchange Web Services (EWS) using Python.

Why py-ews?

Organizations continue to battle against malicious phishing emails in their email environments, but security and IT teams have limited visibility into what currently resides in their users’ mailboxes. Py-ews was written to give control back to your security and IT teams so they can remediate threats faster.

On-premises Microsoft Exchange and Microsoft Office 365 can be accessed programmatically using PowerShell or C#-based programs, which is great if you are strictly working on Windows operating systems. Additionally, if you are on macOS or *nix-based system and utilizing PowerShell Core, you can create a remote session to connect to your Exchange environment.

These are all great options, but py-ews is cross-platform and works with Python 2 and 3 to interact directly with Exchange Web Services for both on-premises Exchange (2010 to 2019) and Office 365. There is no middle man or compiled code to deal with, which means py-ews is faster.

By utilizing Exchange Web Services SOAP XML, we interact directly with Exchange eDiscovery and other EWS service endpoints. At the time of writing this post, py-ews supports the following endpoints:

  • GetSearchableMailboxes: Automatically identify all mailboxes in your environment that you have access rights to search.
  • SearchMailboxes: By using Microsoft’s Advanced Query Syntax you can search a single or all mailboxes in your environment.
  • DeleteItem: You can HardDelete, SoftDelete or MoveToDeletedItems a mail item.
  • Autodiscover: Autodiscover enables you to call a single endpoint when communicating with EWS.
  • ResolveNames: Translate a users email address into a detailed user object to retrieve properties from.
  • GetInboxRules: Determine the inbox rules of a single mailbox.

To use the eDiscovery endpoints you must have Discovery Management rights within Exchange. Py-ews also supports the ability to impersonate a user/mailbox but you must have impersonation rights within Exchange.


Many security teams, like yours, need to respond to malicious emails within their environment. By using py-ews, you can retrieve a list of mailboxes within your Exchange environment, search them and then delete any malicious emails identified.

Here is an example of how to do this with py-ews:

from pyews import UserConfiguration
from pyews import GetSearchableMailboxes
from pyews import SearchMailboxes
from pyews import DeleteItem
userconfig = UserConfiguration(
 '[email protected]',
# get searchable mailboxes based on your accounts permissions
referenceid_list = []
for mailbox in GetSearchableMailboxes(userconfig).response:
# let's search all the referenceid_list items
messages_found = []
for search in SearchMailboxes('subject:account', userconfig,
# if we wanted to now delete a specific message then we would call the DeleteItem
# class like this but we can also pass in the entire messages_found list
deleted_message_response = DeleteItem(messages_found[2], userconfig).response

Py-ews is available on pypi as of today and can be installed by running pip install pyews.

Continue reading about py-ews.

Continue the conversation

SecOps Hub is a community of security pros gathered to discuss SecOps strategies, incident response best practices and ways to simplify SecOps with security orchestration, automation and response (SOAR). Continue this conversation and jump in on conversations like this one today!

Join Now

Request a Live Demo