Client for Microsoft Exchange Web Services (EWS)
This module provides an well-performing, well-behaving, platform-independent and simple interface for communicating with a Microsoft Exchange 2007-2016 Server or Office365 using Exchange Web Services (EWS). It currently implements autodiscover, and functions for searching, creating, updating, deleting, exporting and uploading calendar, mailbox, task, contact and distribution list items.
Here are some examples of how exchangelib works:
Setup and connecting
from exchangelib import DELEGATE, IMPERSONATION, Account, Credentials, ServiceAccount, \ EWSDateTime, EWSTimeZone, Configuration, NTLM, CalendarItem, Message, \ Mailbox, Attendee, Q, ExtendedProperty, FileAttachment, ItemAttachment, \ HTMLBody, Build, Version # Username in WINDOMAIN\username format. Office365 wants usernames in PrimarySMTPAddress # ('email@example.com') format. UPN format is also supported. credentials = Credentials(username='MYWINDOMAIN\\myusername', password='topsecret') # If you're running long-running jobs, you may want to enable fault-tolerance. Fault-tolerance # means that requests to the server do an exponential backoff and sleep for up to a certain # threshold before giving up, if the server is unavailable or responding with error messages. # This prevents automated scripts from overwhelming a failing or overloaded server, and hides # intermittent service outages that often happen in large Exchange installations. # If you want to enable the fault tolerance, create credentials as a service account instead: credentials = ServiceAccount(username='FOO\\bar', password='topsecret') # Set up a target account and do an autodiscover lookup to find the target EWS endpoint: account = Account(firstname.lastname@example.org', credentials=credentials, autodiscover=True, access_type=DELEGATE) # If your credentials have been given impersonation access to the target account, set a # different 'access_type': account = Account(email@example.com', credentials=credentials, autodiscover=True, access_type=IMPERSONATION) # If the server doesn't support autodiscover, use a Configuration object to set the server # location: config = Configuration(server='mail.example.com', credentials=credentials) account = Account(firstname.lastname@example.org', config=config, autodiscover=False, access_type=DELEGATE) # 'exchangelib' will attempt to guess the server version and authentication method. If you # have a really bizarre or locked-down installation and the guessing fails, or you want to avoid # the extra network traffic, you can set the auth method and version explicitly instead: version = Version(build=Build(15, 0, 12, 34)) config = Configuration(server='example.com', credentials=credentials, version=version, auth_type=NTLM) # If you're connecting to the same account very often, you can cache the autodiscover result for # later so you can skip the autodiscover lookup: ews_url = account.protocol.service_endpoint ews_auth_type = account.protocol.auth_type primary_smtp_address = account.primary_smtp_address # 5 minutes later, fetch the cached values and create the account without autodiscovering: config = Configuration(service_endpoint=ews_url, credentials=credentials, auth_type=ews_auth_type) account = Account( primary_smtp_address=primary_smtp_address, config=config, autodiscover=False, access_type=DELEGATE )
# The most common folders are available as account.calendar, account.trash, account.drafts, account.inbox, # account.outbox, account.sent, account.junk, account.tasks, and account.contacts. # # If you want to access other folders, you can either traverse the account.folders dictionary, or find # the folder by name, starting at a direct or indirect parent of the folder you want to find. To search # the full folder hirarchy, start the search from account.root: python_dev_mail_folder = account.root.get_folder_by_name('python-dev') # If you have multiple folders with the same name in your folder hierarchy, start your search further down # the hierarchy: foo1_folder = account.inbox.get_folder_by_name('foo') foo2_folder = python_dev_mail_folder.get_folder_by_name('foo') # For more advanced folder traversing, use some_folder.get_folders() # Folders have some useful counters: account.inbox.total_count account.inbox.child_folder_count account.inbox.unread_count # Update the counters account.inbox.refresh()
Creating, updating, deleting, sending and moving
# Create the calendar items in the user's standard calendar. If you want to access a # non-standard calendar, choose a different one from account.folders[Calendar] # # You can create, update and delete single items item = CalendarItem(folder=account.calendar, subject='foo') item.save() # This gives the item an item_id and a changekey item.subject = 'bar' item.save() # When the items has an item_id, this will update the item item.delete() item.move(account.trash) # Moves the item to the trash bin # You can also send emails: # If you don't want a local copy m = Message( account=a, subject='Daily motivation', body='All bodies are beautiful', to_recipients=[Mailbox(email@example.com')] ) m.send() # Or, if you want a copy in e.g. the 'Sent' folder m = Message( account=a, folder=a.sent, subject='Daily motivation', body='All bodies are beautiful', to_recipients=[Mailbox(firstname.lastname@example.org')] ) m.send_and_save() # EWS distinquishes between plain text and HTML body contents. If you want to send HTML body content, use # the HTMLBody helper. Clients will see this as HTML and display the body correctly: item.body = HTMLBody('<html><body>Hello happy <blink>OWA user!</blink></body></html>') year, month, day = 2016, 3, 20 tz = EWSTimeZone.timezone('Europe/Copenhagen')
# Build a list of calendar items calendar_items =  for hour in range(7, 17): calendar_items.append(CalendarItem( start=tz.localize(EWSDateTime(year, month, day, hour, 30)), end=tz.localize(EWSDateTime(year, month, day, hour + 1, 15)), subject='Test item', body='Hello from Python', location='devnull', categories=['foo', 'bar'], required_attendees = [Attendee( mailbox=Mailbox(email@example.com'), response_type='Accept' )] )) # bulk_update(), bulk_delete(), bulk_move() and bulk_send() methods are also supported. res = account.calendar.bulk_create(items=calendar_items) print(res)
Searching is modeled after the Django QuerySet API, and a large part of the API is supported. Like in Django, the QuerySet is lazy and doesn’t fetch anything before the QuerySet is iterated. QuerySets support chaining, so you can build the final query in multiple steps, and you can re-use a base QuerySet for multiple sub-searches. The QuerySet returns an iterator, and results are cached when the QuerySet is fully iterated the first time.
Here are some examples of using the API:
# Let's get the calendar items we just created. all_items = my_folder.all() # Get everything all_items_without_caching = my_folder.all().iterator() # Get everything, but don't cache filtered_items = my_folder.filter(subject__contains='foo').exclude(categories__icontains='bar') # Chaining status_report = my_folder.all().delete() # Delete the items returned by the QuerySet items_for_2017 = my_calendar.filter(start__range=( tz.localize(EWSDateTime(2017, 1, 1)), tz.localize(EWSDateTime(2018, 1, 1)) )) # Filter by a date range # Same as filter() but throws an error if exactly one item isn't returned item = my_folder.get(subject='unique_string') # You can sort by a single or multiple fields. Prefix a field with '-' to reverse the sorting. Sorting is efficient # since it is done server-side. ordered_items = my_folder.all().order_by('subject') reverse_ordered_items = my_folder.all().order_by('-subject') sorted_by_home_street = my_contacts.all().order_by('physical_addresses__Home__street') # Indexed properties dont_do_this = my_huge_folder.all().order_by('subject', 'categories')[:10] # This is efficient # Counting and exists n = my_folder.all().count() # Efficient counting folder_is_empty = not my_folder.all().exists() # Efficient tasting # Restricting returned attributes sparse_items = my_folder.all().only('subject', 'start') # Dig deeper on indexed properties sparse_items = my_contacts.all().only('phone_numbers') sparse_items = my_contacts.all().only('phone_numbers__CarPhone') sparse_items = my_contacts.all().only('physical_addresses__Home__street') # Returning values instead of objects ids_as_dict = my_folder.all().values('item_id', 'changekey') # Return values as dicts, not objects values_as_list = my_folder.all().values_list('subject', 'body') # Return values as nested lists all_subjects = my_folder.all().values_list('physical_addresses__Home__street', flat=True) # Return a flat list # A QuerySet can be sliced like a normal Python list. Slicing from the start of the QuerySet # is efficient (it only fetches the necessary items), but more exotic slicing requires many or all # items to be fetched from the server. Slicing from the end is also efficient, but then you might as # well just reverse the sorting. first_ten_emails = my_folder.all().order_by('-datetime_received')[:10] # Efficient last_ten_emails = my_folder.all().order_by('-datetime_received')[:-10] # Efficient, but convoluted next_ten_emails = my_folder.all().order_by('-datetime_received')[10:20] # Still quite efficient eviction_warning = my_folder.all().order_by('-datetime_received') # This is looking for trouble some_random_emails = my_folder.all().order_by('-datetime_received')[::3] # This is just stupid # The syntax for filter() is modeled after Django QuerySet filters. The following filter lookup types # are supported. Some lookups only work with string attributes, some only with date or numerical # attributes, and some attributes are not searchable at all: qs = account.calendar.all() qs.filter(subject='foo') # Returns items where subject is exactly 'foo'. Case-sensitive qs.filter(start__range=(dt1, dt2)) # Returns items starting within range. Only for date and numerical types qs.filter(subject__in=('foo', 'bar')) # Return items where subject is either 'foo' or 'bar' qs.filter(subject__not='foo') # Returns items where subject is not 'foo' qs.filter(start__gt=dt) # Returns items starting after 'dt'. Only for date and numerical types qs.filter(start__gte=dt) # Returns items starting on or after 'dt'. Only for date and numerical types qs.filter(start__lt=dt) # Returns items starting before 'dt'. Only for date and numerical types qs.filter(start__lte=dt) # Returns items starting on or before 'dt'. Only for date and numerical types qs.filter(subject__exact='foo') # Returns items where subject is 'foo'. Same as filter(subject='foo') qs.filter(subject__iexact='foo') # Returns items where subject is 'foo', 'FOO' or 'Foo' qs.filter(subject__contains='foo') # Returns items where subject contains 'foo' qs.filter(subject__icontains='foo') # Returns items where subject contains 'foo', 'FOO' or 'Foo' qs.filter(subject__startswith='foo') # Returns items where subject starts with 'foo' qs.filter(subject__istartswith='foo') # Returns items where subject starts with 'foo', 'FOO' or 'Foo' # Returns items that have at least one category set, i.e. the field exists on the item on the server qs.filter(categories__exists=True) # Returns items that have no categories set, i.e. the field does not exist on the item on the server qs.filter(categories__exists=False) # filter() also supports EWS QueryStrings. Just pass the string to filter(). QueryStrings cannot be combined with # other filters. We make no attempt at validating the syntax of the QueryString - we just pass the string verbatim # to EWS. # # Read more about the QueryString syntax here: https://msdn.microsoft.com/en-us/library/ee693615.aspx items = my_folder.filter('subject:XXX') # filter() also supports Q objects that are modeled after Django Q objects, for building complex # boolean logic search expressions. q = (Q(subject__iexact='foo') | Q(subject__contains='bar')) & ~Q(subject__startswith='baz') items = my_folder.filter(q) # In this example, we filter by categories so we only get the items created by us. items = account.calendar.filter( start__lt=tz.localize(EWSDateTime(year, month, day + 1)), end__gt=tz.localize(EWSDateTime(year, month, day)), categories__contains=['foo', 'bar'], ) for item in items: print(item.start, item.end, item.subject, item.body, item.location) # By default, EWS returns only the master recurring item. If you want recurring calendar # items to be expanded, use calendar.view(start=..., end=...) instead. items = account.calendar.view( start=tz.localize(EWSDateTime(year, month, day + 1)), end=tz.localize(EWSDateTime(year, month, day)), ) for item in items: print(item.start, item.end, item.subject, item.body, item.location)
# Delete the calendar items we found, when 'items' is a queryset res = items.delete() print(res)
Extended properties makes it possible to attach custom key-value pairs to items stored on the Exchange server. There are multiple online resources that describe working with extended properties, and list many of the magic values that are used by existing Exchange clients to store common and custom properties. The following is not a comprehensive description of the possibilities, but we do intend to support all the possibilities provided by EWS.
# If folder items have extended properties, you need to register them before you can access them. Create # a subclass of ExtendedProperty and define a set of matching setup values: class LunchMenu(ExtendedProperty): property_set_id = '12345678-1234-1234-1234-123456781234' property_name = 'Catering from the cafeteria' property_type = 'String' # Register the property on the item type of your choice CalendarItem.register('lunch_menu', LunchMenu) # Now your property is available as the attribute 'lunch_menu', just like any other attribute item = CalendarItem(..., lunch_menu='Foie gras et consommé de légumes') item.save() for i in account.calendar.all(): print(i.lunch_menu) # If you change your mind, jsut remove the property again CalendarItem.deregister('lunch_menu') # You can also create named properties (e.g. created from User Defined Fields in Outlook, see issue #137): class LunchMenu(ExtendedProperty): distinguished_property_set_id = 'PublicStrings' property_name = 'Catering from the cafeteria' property_type = 'String' # We support extended properties with tags. This is the definition for the 'completed' and 'followup' flag you can # add to items in Outlook (see also issue #85): class Flag(ExtendedProperty): property_tag = 0x1090 property_type = 'Integer' # Or with property ID: class MyMeetingArray(ExtendedProperty): property_set_id = '00062004-0000-0000-C000-000000000046' property_type = 'BinaryArray' property_id = 32852
# It's possible to create, delete and get attachments connected to any item type: # Process attachments on existing items. FileAttachments have a 'content' attribute # containing the binary content of the file, and ItemAttachments have an 'item' attribute # containing the item. The item can be a Message, CalendarItem, Task etc. for item in my_folder.all(): for attachment in item.attachments: if isinstance(attachment, FileAttachment): local_path = os.path.join('/tmp', attachment.name) with open(local_path, 'wb') as f: f.write(attachment.content) print('Saved attachment to', local_path) elif isinstance(attachment, ItemAttachment): if isinstance(attachment.item, Message): print(attachment.item.subject, attachment.item.body) # Create a new item with an attachment item = Message(...) binary_file_content = 'Hello from unicode æøå'.encode('utf-8') # Or read from file, BytesIO etc. my_file = FileAttachment(name='my_file.txt', content=binary_file_content) item.attach(my_file) my_calendar_item = CalendarItem(...) my_appointment = ItemAttachment(name='my_appointment', item=my_calendar_item) item.attach(my_appointment) item.save() # Add an attachment on an existing item my_other_file = FileAttachment(name='my_other_file.txt', content=binary_file_content) item.attach(my_other_file) # Remove the attachment again item.detach(my_file) # Be aware that adding and deleting attachments from items that are already created in Exchange # (items that have an item_id) will update the changekey of the item.
If you are having trouble using this library, the first thing to try is to enable debug logging. This will output a huge amount of information about what is going on, most notable the actual XML documents that are doing over the wite. This can be really handy to see which fields are being sent and received.
import logging logging.basicConfig(level=logging.DEBUG) # Your code using exchangelib goes here
When you capture a blob of interesting XML from the output, you’ll want to pretty-print it to make it readable. Paste the blob in your favourite editor (e.g. TextMate has a pretty-print keyboard shortcut when the editor window is in XML mode which also highlights the XML), or use this Python snippet:
import io from lxml.etree import parse, tostring xml_str = ''' paste your XML blob here ''' print(tostring(parse( io.BytesIO(xml_str.encode())), xml_declaration=True, pretty_print=True ).decode())
Most class definitions have a docstring containing at least a URL to the MSDN page for the corresponding XML element.
from exchangelib import CalendarItem print(CalendarItem.__doc__)
Most, but not all, item attributes are supported. Addeing more attributes is usually uncomplicated. Feel free to open a PR or an issue.
Item export and upload is supported, for efficient backup, restore and migration.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|File Name & Checksum SHA256 Checksum Help||Version||File Type||Upload Date|
|exchangelib-1.9.4-py2.py3-none-any.whl (129.3 kB) Copy SHA256 Checksum SHA256||3.6||Wheel||Jun 22, 2017|
|exchangelib-1.9.4.tar.gz (99.4 kB) Copy SHA256 Checksum SHA256||–||Source||Jun 22, 2017|