Skip to main content

A Python package to interact with both on-premises and Office 365 Exchange Web Services

Project description

Welcome to py-ews's documentation!


    .______   ____    ____       ___________    __    ____   _______.
    |   _  \  \   \  /   /      |   ____\   \  /  \  /   /  /       |
    |  |_)  |  \   \/   / ______|  |__   \   \/    \/   /  |   (----`
    |   ___/    \_    _/ |______|   __|   \            /    \   \    
    |  |          |  |          |  |____   \    /\    / .----)   |   
    | _|          |__|          |_______|   \__/  \__/  |_______/    



    A Python package to interact with Exchange Web Services

py-ews is a cross platform python package to interact with both Exchange 2010 to 2019 on-premises and Exchange Online (Office 365).

This package will wrap all Exchange Web Service endpoints, but currently is focused on providing eDiscovery endpoints.

Features

py-ews has the following notable features in it's current release:

  • Autodiscover support
  • Delegation support
  • Impersonation support
  • Retrieve all mailboxes that can be searched based on credentials provided
  • Search a list of (or single) mailboxes in your Exchange environment using all supported search attributes
  • Delete email items from mailboxes in your Exchange environment
  • Retrieve mailbox inbox rules for a specific account
  • Find additional hidden inbox rules for a specified account

Currently this package supports the following endpoint's:

Installation

OS X & Linux:

pip install py-ews

Windows:

pip install py-ews

Usage example

The first step in using py-ews is that you need to create a UserConfiguration object. Think of this as all the connection information for Exchange Web Services. An example of creating a UserConfiguration using Office 365 Autodiscover is:

from pyews import UserConfiguration

userconfig = UserConfiguration(
      'myaccount@company.com',
      'Password1234'
)

If you would like to use an alternative Autodiscover endpoint (or any alternative endpoint) then please provide one using the endpoint named parameter:

from pyews import UserConfiguration

userconfig = UserConfiguration(
      'myaccount@company.com',
      'Password1234',
      endpoint='https://outlook.office365.com/autodiscover/autodiscover.svc'
)

For more information about creating a UserConfiguration object, please see the full documentation.

Now that you have a UserConfiguration object, we can now use any of the available service endpoints. This example will demonstrate how you can identify which mailboxes you have access to by using the GetSearchableMailboxes EWS endpoint.

Once you have identified a list of mailbox reference ids, then you can begin searching all of those mailboxes by using the SearchMailboxes EWS endpoint.

The returned results will then be deleted (moved to Deleted Items folder) from Exchange using the DeleteItem EWS endpoint.

from pyews import UserConfiguration
from pyews import GetSearchableMailboxes
from pyews import SearchMailboxes
from pyews import DeleteItem

userconfig = UserConfiguration(
      'myaccount@company.com',
      'Password1234'
)

# get searchable mailboxes based on your accounts permissions
referenceid_list = []
for mailbox in GetSearchableMailboxes(userconfig).run():
      referenceid_list.append(mailbox['reference_id'])

# let's search all the referenceid_list items
messages_found = []
for search in SearchMailboxes(userconfig).run('subject:account', referenceid_list):
      messages_found.append(search['id'])
      # we can print the results first if we want
      print(search['subject'])
      print(search['id'])
      print(search['sender'])
      print(search['to_recipients'])
      print(search['created_time'])
      print(search['received_time'])
      #etc.

# 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(userconfig).run(messages_found[2])

print(deleted_message_response)

The following is an example of the output returned when calling the above code:

YOUR ACCOUNT IS ABOUT TO EXPIRE! UPGRADE NOW!!!
AAMkAGZjOTlkOWExLTM2MDEtNGI3MS0..............
Josh Rickard
Research
2019-02-28T18:28:36Z
2019-02-28T18:28:36Z
Upgrade Your Account!
AAMkADAyNTZhNmMyLWNmZTctNDIyZC0..............
Josh Rickard
Josh Rickard 
2019-01-24T18:41:11Z
2019-01-24T18:41:11Z
New or modified user account information
AAMkAGZjOTlkOWExLTM2MDEtNGI3MS04.............. 
Microsoft Online Services Team
Research
2019-01-24T18:38:06Z
2019-01-24T18:38:06Z
[{'MessageText': 'Succesfull'}]

For more examples and usage, please refer to the individual class documentation

Development setup

I have provided a Dockerfile with all the dependencies and it is currently calling test.py. If you want to test new features, I recommend that you use this Dockerfile. You can call the following to build a new container, but keep the dependencies unless they have changed in your requirements.txt or any other changes to the Dockerfile.

docker build --force-rm -t pyews .

To run the container, use the following:

docker run pyews

I am new to Unit Testing, but I am working on that as time permits. If you would like to help, I wouldn't be sad about it. :)

Release History

  • 1.0.0
    • Initial release of py-ews and it is still considered a work in progress
  • 2.0.0
    • Revamped logic and overhauled all endpoints and classes

Meta

Josh Rickard – @MSAdministrator

Distributed under the MIT license. See LICENSE for more information.

Contributing

  1. Fork it (https://github.com/swimlane/pyews/fork)
  2. Create your feature branch (git checkout -b feature/fooBar)
  3. Commit your changes (git commit -am 'Add some fooBar')
  4. Push to the branch (git push origin feature/fooBar)
  5. Create a new Pull Request
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   services/root
   configuration/root
   utils/root

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py-ews-2.0.2.tar.gz (17.3 kB view details)

Uploaded Source

Built Distributions

py_ews-2.0.2-py3-none-any.whl (29.2 kB view details)

Uploaded Python 3

py_ews-2.0.2-py2-none-any.whl (29.2 kB view details)

Uploaded Python 2

File details

Details for the file py-ews-2.0.2.tar.gz.

File metadata

  • Download URL: py-ews-2.0.2.tar.gz
  • Upload date:
  • Size: 17.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.6.1 requests/2.25.0 setuptools/51.1.1 requests-toolbelt/0.9.1 tqdm/4.55.1 CPython/3.9.1

File hashes

Hashes for py-ews-2.0.2.tar.gz
Algorithm Hash digest
SHA256 4b316f337d593584998831d9eca9c24abdf356ba3dc5cacaaf20e94cbe470c6a
MD5 519a2de1663ce55d6799b8f76385a07b
BLAKE2b-256 bb98d20de08d53d9b16263ad06c23192320da1bf7798f7a9d2a60794f2568d3f

See more details on using hashes here.

File details

Details for the file py_ews-2.0.2-py3-none-any.whl.

File metadata

  • Download URL: py_ews-2.0.2-py3-none-any.whl
  • Upload date:
  • Size: 29.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.6.1 requests/2.25.0 setuptools/51.1.1 requests-toolbelt/0.9.1 tqdm/4.55.1 CPython/3.9.1

File hashes

Hashes for py_ews-2.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 4609892c4494c4f95ce1e9b507979d18cc4e8ec48e4e014a200a7c300850a1b9
MD5 ac332f36c6e0db7212d5e157a01a19c8
BLAKE2b-256 ca25ae673fe1ec148466b107e8d3535bf8aaa0ee7b7bbc6184c94a6cae10feb5

See more details on using hashes here.

File details

Details for the file py_ews-2.0.2-py2-none-any.whl.

File metadata

  • Download URL: py_ews-2.0.2-py2-none-any.whl
  • Upload date:
  • Size: 29.2 kB
  • Tags: Python 2
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.6.1 requests/2.25.0 setuptools/51.1.1 requests-toolbelt/0.9.1 tqdm/4.55.1 CPython/3.9.1

File hashes

Hashes for py_ews-2.0.2-py2-none-any.whl
Algorithm Hash digest
SHA256 0b41d1a2136f2cafe5309f3b05abcc3894234a6f833ff0bb8aec104b54f24e27
MD5 45633fabe4b74756530c82bb22b06fb1
BLAKE2b-256 fffb64c412985bd4e7fcd39666a4d869ce611f81520696e5d34da756e32209bf

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page