Package: exchangelibtmp
Exchange Web Services client libraryThis 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.TeaserHere's a short example of howexchangelibworks. Let's print the first
100 inbox messages in reverse order:fromexchangelibimportCredentials,Accountcredentials=Credentials('john@example.com','topsecret')account=Account('john@example.com',credentials=credentials,autodiscover=True)foriteminaccount.inbox.all().order_by('-datetime_received')[:100]:print(item.subject,item.sender,item.datetime_received)InstallationYou can install this package from PyPI:pipinstallexchangelibThe default installation does not support Kerberos. For additional Kerberos support, install
with the extrakerberosdependencies:pipinstallexchangelib[kerberos]To install the very latest code, install directly from GitHub instead:pipinstallgit+https://github.com/ecederstrand/exchangelib.gitexchangelibuses thelxmlpackage, andpykerberosto support Kerberos authentication.
To be able to install these, you may need to install some additional operating system packages.On Ubuntu:apt-getinstalllibxml2-devlibxslt1-dev# For Kerberos support, also install these:apt-getinstalllibkrb5-devbuild-essentiallibssl-devlibffi-devpython-devOn CentOS:# For Kerberos support, install these:yuminstallgccpython-develkrb5-develkrb5-workstationpython-develOn FreeBSD,pipneeds a little help:pkginstalllibxml2libxsltCFLAGS=-I/usr/local/includepipinstalllxml# For Kerberos support, also install these:pkginstallkrb5CFLAGS=-I/usr/local/includepipinstallkerberospykerberosFor other operating systems, please consult the documentation for the Python package that
fails to install.Setup and connectingfromexchangelibimportDELEGATE,IMPERSONATION,Account,Credentials,ServiceAccount,\Configuration,NTLM,GSSAPI,Build,Version# Specify your credentials. Username is usually in WINDOMAIN\username format, where WINDOMAIN is# the name of the Windows Domain your username is connected to, but some servers also# accept usernames in PrimarySMTPAddress ('myusername@example.com') format (Office365 requires it).# UPN format is also supported, if your server expects that.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')# An Account is the account on the Exchange server that you want to connect to. This can be# the account associated with the credentials you connect with, or any other account on the# server that you have been granted access to. If, for example, you want to access a shared# folder, create an Account instance using the email address of the account that the shared# folder belongs to, and access the shared folder through this account.# 'primary_smtp_address' is the primary SMTP address assigned the account. If you enable# autodiscover, an alias address will work, too. In this case, 'Account.primary_smtp_address'# will be set to the primary SMTP address.my_account=Account(primary_smtp_address='myusername@example.com',credentials=credentials,autodiscover=True,access_type=DELEGATE)johns_account=Account(primary_smtp_address='john@example.com',credentials=credentials,autodiscover=True,access_type=DELEGATE)marys_account=Account(primary_smtp_address='mary@example.com',credentials=credentials,autodiscover=True,access_type=DELEGATE)still_marys_account=Account(primary_smtp_address='alias_for_mary@example.com',credentials=credentials,autodiscover=True,access_type=DELEGATE)# Set up a target account and do an autodiscover lookup to find the target EWS endpoint.account=Account(primary_smtp_address='john@example.com',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(primary_smtp_address='john@example.com',credentials=credentials,autodiscover=True,access_type=IMPERSONATION)# If the server doesn't support autodiscover, or you want to avoid the overhead of autodiscover,# use a Configuration object to set the server location instead:config=Configuration(server='mail.example.com',credentials=credentials)account=Account(primary_smtp_address='john@example.com',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)# Kerberos authentication is supported via the 'gssapi' auth type. Enabling it is slightly awkward,# does not work with autodiscover (yet) and is likely to change in future versions.credentials=Credentials('','')config=Configuration(server='example.com',credentials=credentials,auth_type=GSSAPI)# 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_endpointews_auth_type=account.protocol.auth_typeprimary_smtp_address=account.primary_smtp_address# You can now create the Account without autodiscovering, using the cached values: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,)# Autodiscover can take a lot of time, specially the part that figures out the autodiscover# server to contact for a specific email domain. For this reason, we will create a persistent,# per-user, on-disk cache containing a map of previous, successful domain -> autodiscover server# lookups. This cache is shared between processes and is not deleted when your program exits.# A cache entry for a domain is removed automatically if autodiscovery fails for an email in that# domain. It's possible to clear the entire cache completely if you want:fromexchangelib.autodiscoverimport_autodiscover_cache_autodiscover_cache.clear()Proxies and custom TLS validationIf you need proxy support or custom TLS validation, you can supply a
custom 'requests' transport adapter class, as described inhttp://docs.python-requests.org/en/master/user/advanced/#transport-adapters.Here's an example using different custom root certificates depending on
the server to connect to:fromurllib.parseimporturlparseimportrequests.adaptersfromexchangelib.protocolimportBaseProtocolclassRootCAAdapter(requests.adapters.HTTPAdapter):# An HTTP adapter that uses a custom root CA certificate at a hard coded locationdefcert_verify(self,conn,url,verify,cert):cert_file={'example.com':'/path/to/example.com.crt','mail.internal':'/path/to/mail.internal.crt',}[urlparse(url).hostname]super(RootCAAdapter,self).cert_verify(conn=conn,url=url,verify=cert_file,cert=cert)# Tell exchangelib to use this adapter class instead of the defaultBaseProtocol.HTTP_ADAPTER_CLS=RootCAAdapterHere's an example of adding proxy support:importrequests.adaptersfromexchangelib.protocolimportBaseProtocolclassProxyAdapter(requests.adapters.HTTPAdapter):defsend(self,*args,**kwargs):kwargs['proxies']={'http':'http://10.0.0.1:1243','https':'http://10.0.0.1:4321',}returnsuper(ProxyAdapter,self).send(*args,**kwargs)# Tell exchangelib to use this adapter class instead of the defaultBaseProtocol.HTTP_ADAPTER_CLS=ProxyAdapterexchangelibprovides a sample adapter which ignores TLS validation
errors. Use at own risk.fromexchangelib.protocolimportBaseProtocol,NoVerifyHTTPAdapter# Tell exchangelib to use this adapter class instead of the defaultBaseProtocol.HTTP_ADAPTER_CLS=NoVerifyHTTPAdapterFoldersAll wellknown folders are available as properties on the account, e.g. asaccount.root,account.calendar,account.trash,account.inbox,account.outbox,account.sent,account.junk,account.tasksandaccount.contacts.# There are multiple ways of navigating the folder tree and searching for folders. Globbing and# absolute path may create unexpected results if your folder names contain slashes.# The folder structure is cached after first access to a folder hierarchy. This means that external# changes to the folder structure will not show up until you clear the cache. Here's how to clear# the cache of each of the currently supported folder hierarchies:fromexchangelibimportAccount,Foldera=Account(...)a.root.refresh()a.public_folders_root.refresh()a.archive_root.refresh()some_folder=a.root/'Some Folder'some_folder.parentsome_folder.parent.parent.parentsome_folder.root# Returns the root of the folder structure, at any level. Same as Account.rootsome_folder.children# A generator of child folderssome_folder.absolute# Returns the absolute path, as a stringsome_folder.walk()# A generator returning all subfolders at arbitrary depth this level# Globbing uses the normal UNIX globbing syntaxsome_folder.glob('foo*')# Return child folders matching the patternsome_folder.glob('*/foo')# Return subfolders named 'foo' in any child foldersome_folder.glob('**/foo')# Return subfolders named 'foo' at any depthsome_folder/'sub_folder'/'even_deeper'/'leaf'# Works like pathlib.Path# You can also drill down into the folder structure without using the cache. This works like# the single slash syntax, but does not start by creating a cache the folder hierarchy. This is# useful if your account contains a huge number of folders, and you already know where to go.some_folder//'sub_folder'//'even_deeper'//'leaf'some_folder.parts# returns some_folder and all its parents, as Folder instances# tree() returns a string representation of the tree structure at the given levelprint(a.root.tree())'''root├── inbox│   └── todos└── archive├── Last Job├── exchangelib issues└── Mom'''# Folders have some useful counters:a.inbox.total_counta.inbox.child_folder_counta.inbox.unread_count# Update the countersa.inbox.refresh()# Folders can be created, updated and deleted:f=Folder(parent=a.inbox,name='My New Folder')f.save()f.name='My New Subfolder'f.save()f.delete()# Delete all items in a folderf.empty()# Also delete all subfolders in the folderf.empty(delete_sub_folders=True)# Recursively delete all items in a folder, and all subfolders and their content. This is# like `empty(delete_sub_folders=True)` but attempts to protect distinguished folders from# being deleted. Use with caution!f.wipe()Dates, datetimes and timezonesEWS has some special requirements on datetimes and timezones. You need
to use the specialEWSDate,EWSDateTimeandEWSTimeZoneclasses
when working with dates.fromdatetimeimportdatetime,timedeltaimportpytzfromexchangelibimportEWSTimeZone,EWSDateTime,EWSDate# EWSTimeZone works just like pytz.timezone()tz=EWSTimeZone.timezone('Europe/Copenhagen')# You can also get the local timezone defined in your operating systemtz=EWSTimeZone.localzone()# EWSDate and EWSDateTime work just like datetime.datetime and datetime.date. Always create# timezone-aware datetimes with EWSTimeZone.localize():localized_dt=tz.localize(EWSDateTime(2017,9,5,8,30))right_now=tz.localize(EWSDateTime.now())# Datetime math works transparentlytwo_hours_later=localized_dt+timedelta(hours=2)two_hours=two_hours_later-localized_dttwo_hours_later+=timedelta(hours=2)# Datesmy_date=EWSDate(2017,9,5)today=EWSDate.today()also_today=right_now.date()also_today+=timedelta(days=10)# UTC helpers. 'UTC' is the UTC timezone as an EWSTimeZone instance.# 'UTC_NOW' returns a timezone-aware UTC timestamp of current time.fromexchangelibimportUTC,UTC_NOWright_now_in_utc=UTC.localize(EWSDateTime.now())right_now_in_utc=UTC_NOW()# Already have a Python datetime object you want to use? Make sure it's localized. Then pass# it to from_datetime().pytz_tz=pytz.timezone('Europe/Copenhagen')py_dt=pytz_tz.localize(datetime(2017,12,11,10,9,8))ews_now=EWSDateTime.from_datetime(py_dt)Creating, updating, deleting, sending and moving# Here's an example of creating a calendar item 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:fromexchangelibimportAccount,CalendarItem,Message,Mailbox,FileAttachment,HTMLBodyfromexchangelib.itemsimportSEND_ONLY_TO_ALL,SEND_ONLY_TO_CHANGEDa=Account(...)item=CalendarItem(folder=a.calendar,subject='foo')item.save()# This gives the item an 'id' and a 'changekey' valueitem.save(send_meeting_invitations=SEND_ONLY_TO_ALL)# Send a meeting invitation to attendees# Update a field. All fields have a corresponding Python type that must be used.item.subject='bar'# Print all available fields on the 'CalendarItem' class. Beware that some fields are read-only, or# read-only after the item has been saved or sent, and some fields are not supported on old# versions of Exchange.print(CalendarItem.FIELDS)item.save()# When the items has an item_id, this will update the itemitem.save(update_fields=['subject'])# Only updates certain fields. Accepts a list of field names.item.save(send_meeting_invitations=SEND_ONLY_TO_CHANGED)# Send invites only to attendee changesitem.delete()# Hard deletinonitem.delete(send_meeting_cancellations=SEND_ONLY_TO_ALL)# Send cancellations to all attendeesitem.soft_delete()# Delete, but keep a copy in the recoverable items folderitem.move_to_trash()# Move to the trash folderitem.move(a.trash)# Also moves the item to the trash folderitem.copy(a.trash)# Creates a copy of the item to the trash folder# 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_address='anne@example.com'),Mailbox(email_address='bob@example.com'),],cc_recipients=['carl@example.com','denice@example.com'],# Simple strings work, toobcc_recipients=[Mailbox(email_address='erik@example.com'),'felicity@example.com',],# Or a mix of both)m.send()# Or, if you want a copy in e.g. the 'Sent' folderm=Message(account=a,folder=a.sent,subject='Daily motivation',body='All bodies are beautiful',to_recipients=[Mailbox(email_address='anne@example.com')])m.send_and_save()# Likewise, you can reply to and forward messages that are stored in your mailbox (i.e. they# have an item ID).m=a.sent.get(subject='Daily motivation')m.reply(subject='Re: Daily motivation',body='I agree',to_recipients=['carl@example.com','denice@example.com'])m.reply_all(subject='Re: Daily motivation',body='I agree')m.forward(subject='Fwd: Daily motivation',body='Hey, look at this!',to_recipients=['carl@example.com','denice@example.com'])# You can also edit a draft of a reply or forwardforward_draft=m.create_forward(subject='Fwd: Daily motivation',body='Hey, look at this!',to_recipients=['carl@example.com','denice@example.com']).save(a.drafts)# gives you back the itemforward_draft.reply_to='eric@example.com'forward_draft.attach(FileAttachment(name='my_file.txt',content='hello world'.encode('utf-8')))forward_draft.send()# now our forward has an extra reply_to field and an extra attachment.# EWS distinguishes 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>')Bulk operations# Build a list of calendar itemsfromexchangelibimportAccount,CalendarItem,EWSDateTime,EWSTimeZone,Attendee,Mailboxa=Account(...)tz=EWSTimeZone.timezone('Europe/Copenhagen')year,month,day=2016,3,20calendar_items=[]forhourinrange(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_address='user1@example.com'),response_type='Accept')]))# Create all items at oncereturn_ids=a.bulk_create(folder=a.calendar,items=calendar_items)# Bulk fetch, when you have a list of item IDs and want the full objects. Returns a generator.calendar_ids=[(i.id,i.changekey)foriincalendar_items]items_iter=a.fetch(ids=calendar_ids)# If you only want some fields, use the 'only_fields' attributeitems_iter=a.fetch(ids=calendar_ids,only_fields=['start','subject'])# Bulk update items. Each item must be accompanied by a list of attributes to updateupdated_ids=a.bulk_update(items=[(i,('start','subject'))foriincalendar_items])# Move many items to a new foldernew_ids=a.bulk_move(ids=calendar_ids,to_folder=a.other_calendar)# Send draft messages in bulkmessage_ids=a.drafts.all().only('id','changekey')new_ids=a.bulk_send(ids=message_ids,save_copy=False)# Delete in bulkdelete_results=a.bulk_delete(ids=calendar_ids)# Bulk delete items found as a queryseta.inbox.filter(subject__startswith='Invoice').delete()SearchingSearching 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:fromdatetimeimporttimedeltafromexchangelibimportAccount,EWSDateTime,FolderCollection,Qa=Account(...)all_items=a.inbox.all()# Get everythingall_items_without_caching=a.inbox.all().iterator()# Get everything, but don't cache# Chain multiple modifiers ro refine the queryfiltered_items=a.inbox.filter(subject__contains='foo').exclude(categories__icontains='bar')status_report=a.inbox.all().delete()# Delete the items returned by the QuerySetstart=a.default_timezone.localize(EWSDateTime(2017,1,1))end=a.default_timezone.localize(EWSDateTime(2018,1,1))items_for_2017=a.calendar.filter(start__range=(start,end))# Filter by a date range# Same as filter() but throws an error if exactly one item isn't returneditem=a.inbox.get(subject='unique_string')# If you only have the ID and possibly the changekey of an item, you can get the full item:a.inbox.get(id='AAMkADQy=')a.inbox.get(id='AAMkADQy=',changekey='FwAAABYA')# 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, except when a calendar view sorting on# multiple fields.ordered_items=a.inbox.all().order_by('subject')reverse_ordered_items=a.inbox.all().order_by('-subject')# Indexed properties can be ordered on their individual componentssorted_by_home_street=a.contacts.all().order_by('physical_addresses__Home__street')# Beware that sorting is done client-side herea.calendar.view(start=start,end=end).order_by('subject','categories')# Counting and existsn=a.inbox.all().count()# Efficient countingfolder_is_empty=nota.inbox.all().exists()# Efficient tasting# Restricting returned attributessparse_items=a.inbox.all().only('subject','start')# Dig deeper on indexed propertiessparse_items=a.contacts.all().only('phone_numbers')sparse_items=a.contacts.all().only('phone_numbers__CarPhone')sparse_items=a.contacts.all().only('physical_addresses__Home__street')# Return values as dicts, not objectsids_as_dict=a.inbox.all().values('id','changekey')# Return values as nested listsvalues_as_list=a.inbox.all().values_list('subject','body')# Return values as a flat listall_subjects=a.inbox.all().values_list('physical_addresses__Home__street',flat=True)# A QuerySet can be indexed and sliced like a normal Python list. Slicing and indexing of the# QuerySet is efficient because it only fetches the necessary items to perform the slicing.# Slicing from the end is also efficient, but then you might as well reverse the sorting.first_ten=a.inbox.all().order_by('-subject')[:10]# Efficient. We only fetch 10 itemslast_ten=a.inbox.all().order_by('-subject')[:-10]# Efficient, but convolutednext_ten=a.inbox.all().order_by('-subject')[10:20]# Efficient. We only fetch 10 itemssingle_item=a.inbox.all().order_by('-subject')[34298]# Efficient. We only fetch 1 itemten_items=a.inbox.all().order_by('-subject')[3420:3430]# Efficient. We only fetch 10 itemsrandom_emails=a.inbox.all().order_by('-subject')[::3]# This is just stupid, but works# The syntax for filter() is modeled after Django QuerySet filters. The following filter lookup# types are supported. Some lookups only work with string attributes. Range and less/greater# operators only work for date or numerical attributes. Some attributes are not searchable at all# via EWS:qs=a.calendar.all()qs.filter(subject='foo')# Returns items where subject is exactly 'foo'. Case-sensitiveqs.filter(start__range=(start,end))# Returns items within rangeqs.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=start)# Returns items starting after 'dt'qs.filter(start__gte=start)# Returns items starting on or after 'dt'qs.filter(start__lt=start)# Returns items starting before 'dt'qs.filter(start__lte=start)# Returns items starting on or before 'dt'qs.filter(subject__exact='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'# Returns items where subject starts with 'foo', 'FOO' or 'Foo'qs.filter(subject__istartswith='foo')# Returns items that have at least one category assigned, 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.aspxa.inbox.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')a.inbox.filter(q)# In this example, we filter by categories so we only get the items created by us.a.calendar.filter(start__lt=a.default_timezone.localize(EWSDateTime(2019,1,1)),end__gt=a.default_timezone.localize(EWSDateTime(2019,1,31)),categories__contains=['foo','bar'],)# 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=a.calendar.view(start=a.default_timezone.localize(EWSDateTime(2019,1,31)),end=a.default_timezone.localize(EWSDateTime(2019,1,31))+timedelta(days=1),)foriteminitems:print(item.start,item.end,item.subject,item.body,item.location)# You can combine view() with other modifiers. For example, to check for conflicts before# adding a meeting from 8:00 to 10:00:has_conflicts=a.calendar.view(start=a.default_timezone.localize(EWSDateTime(2019,1,31,8)),end=a.default_timezone.localize(EWSDateTime(2019,1,31,10)),max_items=1).exists()# The filtering syntax also works on collections of folders, so you can search multiple folders in# a single request.a.inbox.children.filter(subject='foo')a.inbox.walk().filter(subject='foo')a.inbox.glob('foo*').filter(subject='foo')# Or select the folders individuallyFolderCollection(account=a,folders=[a.inbox,a.calendar]).filter(subject='foo')PagingPaging EWS services, e.g. FindItem and, have a default page size of 100. You can
change this value globally if you want:importexchangelib.servicesexchangelib.services.CHUNK_SIZE=25If you are working with very small or very large items, this may not be a reasonable
value. For example, if you want to retrieve and save emails with large attachments,
you can change this value on a per-queryset basis:fromexchangelibimportAccounta=Account(...)qs=a.inbox.all().only('mime_content')qs.page_size=5formsginqs.iterator():withopen('%s.eml'%msg.item_id,'wb')asf:f.write(msg.mime_content)Finally, the bulk methods defined on theAccountclass have an optionalchunk_sizeargument that you can use to set a non-default page size when fetching, creating, updating
or deleting items.fromexchangelibimportAccount,Messagea=Account(...)huge_list_of_items=[Message(...)foriinrange(10000)]return_ids=a.bulk_create(folder=a.inbox,items=huge_list_of_items,chunk_size=5)MeetingsTheCalendarItemclass allows you send out requests for meetings that
you initiate or to cancel meetings that you already set out before. It
is also possible to processMeetingRequestmessages that are received.
You can reply to these messages using theAcceptItem,TentativelyAcceptItemandDeclineItemclasses. If you receive a
cancellation for a meeting (classMeetingCancellation) that you
already accepted then you can also process these by removing the entry
from the calendar.fromexchangelibimportAccount,CalendarItem,EWSDateTimefromexchangelib.itemsimportMeetingRequest,MeetingCancellation,SEND_TO_ALL_AND_SAVE_COPYa=Account(...)# create a meeting request and send it outitem=CalendarItem(account=a,folder=a.calendar,start=a.default_timezone.localize(EWSDateTime(2019,1,31,8,15)),end=a.default_timezone.localize(EWSDateTime(2019,1,31,8,45)),subject="Subject of Meeting",body="Please come to my meeting",required_attendees=['anne@example.com','bob@example.com'])item.save(send_meeting_invitations=SEND_TO_ALL_AND_SAVE_COPY)# cancel a meeting that was sent out using the CalendarItem classforcalendar_itemina.calendar.all().order_by('-datetime_received')[:5]:# only the organizer of a meeting can cancel itifcalendar_item.organizer.email_address==a.primary_smtp_address:calendar_item.cancel()# processing an incoming MeetingRequestforitemina.inbox.all().order_by('-datetime_received')[:5]:ifisinstance(item,MeetingRequest):item.accept(body="Sure, I'll come")# Or:item.decline(body="No way!")# Or:item.tentatively_accept(body="Maybe...")# meeting requests can also be handled from the calendar - e.g. decline the meeting that was# received last.forcalendar_itemina.calendar.all().order_by('-datetime_received')[:1]:calendar_item.decline()# processing an incoming MeetingCancellation (also delete from calendar)foritemina.inbox.all().order_by('-datetime_received')[:5]:ifisinstance(item,MeetingCancellation):ifitem.associated_calendar_item_id:calendar_item=a.inbox.get(id=item.associated_calendar_item_id.id,changekey=item.associated_calendar_item_id.changekey)calendar_item.delete()item.move_to_trash()Searching contactsFetching personas from a contact folder is supported using the same
syntax as folders. Just start your query with.people():# Navigate to a contact folder and start the searchfromexchangelibimportAccounta=Account(...)folder=a.root/'AllContacts'forpinfolder.people():print(p)forpinfolder.people().only('display_name').filter(display_name='john').order_by('display_name'):print(p)Extended propertiesExtended properties makes it possible to attach custom key-value pairs
to items and folders 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:fromexchangelibimportAccount,ExtendedProperty,CalendarItem,Folder,Messagea=Account(...)classLunchMenu(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 choiceCalendarItem.register('lunch_menu',LunchMenu)# Now your property is available as the attribute 'lunch_menu', just like any other attributeitem=CalendarItem(...,lunch_menu='Foie gras et consommé de légumes')item.save()foriina.calendar.all():print(i.lunch_menu)# If you change your mind, jsut remove the property againCalendarItem.deregister('lunch_menu')# You can also create named properties (e.g. created from User Defined Fields in Outlook, see# issue #137):classLunchMenu(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):classFlag(ExtendedProperty):property_tag=0x1090property_type='Integer'# Or with property ID:classMyMeetingArray(ExtendedProperty):property_set_id='00062004-0000-0000-C000-000000000046'property_type='BinaryArray'property_id=32852# Or using distinguished property sets combined with property ID (here as a hex value to align# with the format usually mentioned in Microsoft docs). This is the definition for a response to# an Outlook Vote request (see issue #198):classVoteResponse(ExtendedProperty):distinguished_property_set_id='Common'property_id=0x00008524property_type='String'# Extended properties also work with folders. Here's an example of getting the size (in bytes) of# a folder:classFolderSize(ExtendedProperty):property_tag=0x0e08property_type='Integer'Folder.register('size',FolderSize)print(a.inbox.size)# In general, here's how to work with any MAPI property as listed in e.g.# https://msdn.microsoft.com/EN-US/library/office/cc815517.aspx. Let's take `PidLidTaskDueDate` as# an example. This is the due date for a message maked with the follow-up flag in Microsoft# Outlook.## PidLidTaskDueDate is documented at https://msdn.microsoft.com/en-us/library/office/cc839641.aspx.# The property ID is `0x00008105` and the property set is `PSETID_Task`. But EWS wants the UUID for# `PSETID_Task`, so we look that up in the MS-OXPROPS pdf:# https://msdn.microsoft.com/en-us/library/cc433490(v=exchg.80).aspx. The UUID is# `00062003-0000-0000-C000-000000000046`. The property type is `PT_SYSTIME` which is also called# `SystemTime` (see# https://msdn.microsoft.com/en-us/library/microsoft.exchange.webservices.data.mapipropertytype(v=exchg.80).aspx).## In conclusion, the definition for the due date becomes:classFlagDue(ExtendedProperty):property_set_id='00062003-0000-0000-C000-000000000046'property_id=0x8105property_type='SystemTime'Message.register('flag_due',FlagDue)Attachments# 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.importos.pathfromexchangelibimportAccount,FileAttachment,ItemAttachment,Message,CalendarItem,HTMLBodya=Accountforitemina.inbox.all():forattachmentinitem.attachments:ifisinstance(attachment,FileAttachment):local_path=os.path.join('/tmp',attachment.name)withopen(local_path,'wb')asf:f.write(attachment.content)print('Saved attachment to',local_path)elifisinstance(attachment,ItemAttachment):ifisinstance(attachment.item,Message):print(attachment.item.subject,attachment.item.body)# Streaming downloads of file attachment is supported. This reduces memory consumption since we# never store the full content of the file in-memory:foritemina.inbox.all():forattachmentinitem.attachments:ifisinstance(attachment,FileAttachment):local_path=os.path.join('/tmp',attachment.name)withopen(local_path,'wb')asf,attachment.fpasfp:buffer=fp.read(1024)whilebuffer:f.write(buffer)buffer=fp.read(1024)print('Saved attachment to',local_path)# Create a new item with an attachmentitem=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 itemmy_other_file=FileAttachment(name='my_other_file.txt',content=binary_file_content)item.attach(my_other_file)# Remove the attachment againitem.detach(my_file)# If you want to embed an image in the item body, you can link to the file in the HTMLmessage=Message(...)logo_filename='logo.png'withopen(logo_filename,'rb')asf:my_logo=FileAttachment(name=logo_filename,content=f.read(),is_inline=True,content_id=logo_filename)message.attach(my_logo)message.body=HTMLBody('<html><body>Hello logo: <img src="cid:%s"></body></html>'%logo_filename)# Attachments cannot be updated via EWS. In this case, you must to detach the attachment, update# the relevant fields, and attach the updated attachment.# 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.Recurring calendar itemsThere is full read-write support for creating recurring calendar items.
You can create daily, weekly, monthly and yearly recurrences (the latter
two in relative and absolute versions).Here's an example of creating 7 occurrences on Mondays and Wednesdays of
every third week, starting September 1, 2017:fromdatetimeimporttimedeltafromexchangelibimportAccount,CalendarItem,EWSDateTimefromexchangelib.fieldsimportMONDAY,WEDNESDAYfromexchangelib.recurrenceimportRecurrence,WeeklyPatterna=Account(...)start=a.default_timezone.localize(EWSDateTime(2017,9,1,11))end=start+timedelta(hours=2)item=CalendarItem(folder=a.calendar,start=start,end=end,subject='Hello Recurrence',recurrence=Recurrence(pattern=WeeklyPattern(interval=3,weekdays=[MONDAY,WEDNESDAY]),start=start.date(),number=7),)# Occurrence data for the master itemforiina.calendar.filter(start__lt=end,end__gt=start):print(i.subject,i.start,i.end)print(i.recurrence)print(i.first_occurrence)print(i.last_occurrence)foroini.modified_occurrences:print(o)foroini.deleted_occurrences:print(o)# All occurrences expanded. The recurrence will span over 4 iterations of a 3-week periodforiina.calendar.view(start=start,end=start+timedelta(days=4*3*7)):print(i.subject,i.start,i.end)# 'modified_occurrences' and 'deleted_occurrences' of master items are read-only fields. To# delete or modify an occurrence, you must use 'view()' to fetch the occurrence and modify or# delete it:foroccurrenceina.calendar.view(start=start,end=start+timedelta(days=4*3*7)):# Delete or update random occurrences. This will affect 'modified_occurrences' and# 'deleted_occurrences' of the master item.ifoccurrence.start.milliseconds%2:# We receive timestamps as UTC but want to write them back as local timezoneoccurrence.start=occurrence.start.astimezone(a.default_timezone)occurrence.start+=timedelta(minutes=30)occurrence.end=occurrence.end.astimezone(a.default_timezone)occurrence.end+=timedelta(minutes=30)occurrence.subject='My new subject'occurrence.save()else:occurrence.delete()Message timestamp fieldsEachMessageitem has four timestamp fields:datetime_createddatetime_sentdatetime_receivedlast_modified_timeThe values for these fields are set by the Exchange server and are not
modifiable via EWS. All values are timezone-awareEWSDateTimeinstances.Thedatetime_sentvalue may be earlier thandatetime_created.Out of FacilityYou can get and set OOF messages using theAccount.oof_settingsproperty:fromexchangelibimportAccount,OofSettings,EWSDateTimea=Account(...)# Get the current OOF settingsa.oof_settings# Change the OOF settings to something elsea.oof_settings=OofSettings(state=OofSettings.SCHEDULED,external_audience='Known',internal_reply="I'm in the pub. See ya guys!",external_reply="I'm having a business dinner in town",start=a.default_timezone.localize(EWSDateTime(2017,11,1,11)),end=a.default_timezone.localize(EWSDateTime(2017,12,1,11)),)# Disable OOF messagesa.oof_settings=OofSettings(state=OofSettings.DISABLED,internal_reply='',external_reply='',)Export and uploadExchange supports backup and restore of folder contents using special
export and upload services. They are available on theAccountmodel:fromexchangelibimportAccounta=Account(...)items=a.inbox.all().only('id','changekey')data=a.export(items)# Pass a list of Item instances or (item_id, changekey) tuplesa.upload((a.inbox,d)fordindata)# Restore the items. Expects a list of (folder, data) tuplesNon-account methodsfromexchangelibimportAccount,DLMailboxa=Account(...)# Get timezone information from the servera.protocol.get_timezones()# Get room lists defined on the servera.protocol.get_roomlists()# Get rooms belonging to a specific room listforrlina.protocol.get_roomlists():a.protocol.get_rooms(rl)# Get account information for a list of names or email addressesformailboxina.protocol.resolve_names(['ann@example.com','bart@example.com']):print(mailbox.email_address)formailbox,contactina.protocol.resolve_names(['anne','bart'],return_full_contact_data=True):print(mailbox.email_address,contact.display_name)# Get all mailboxes on a distribution listformailboxina.protocol.expand_dl(DLMailbox(email_address='distro@example.com',mailbox_type='PublicDL'):print(mailbox.email_address)# Or just pass a string containing the SMTP addressformailboxina.protocol.expand_dl('distro@example.com'):print(mailbox.email_address)# Get searchable mailboxes. This method is only available to users who have been assigned# the Discovery Management RBAC role. (This feature works on Exchange 2013 onwards)formailboxina.protocol.get_searchable_mailboxes():print(mailbox)EWS supports getting availability information for a set of users in a certain
timeframe. The server returns an object for each account containing free/busy
information, including a list of calendar events in the user's calendar, and
the working hours and timezone of the user.fromdatetimeimporttimedeltafromexchangelibimportAccount,EWSDateTimea=Account(...)start=a.default_timezone.localize(EWSDateTime.now())end=start+timedelta(hours=6)accounts=[(a,'Organizer',False)]forbusy_infoina.protocol.get_free_busy_info(accounts=accounts,start=start,end=end):print(busy_info)The calendar events and working hours are returned as naive datetimes. To convert
to timezone-aware datetimes, a bit of extra work is needed if the users are not
known to be in the same timezone.# Get all server timezones. We need that to convert 'working_hours_timezone'fromdatetimeimporttimedeltafromexchangelibimportAccount,EWSDateTime,EWSTimeZonea=Account(...)timezones=list(a.protocol.get_timezones(return_full_timezone_data=True))# Get availability information for a list of accountsstart=a.default_timezone.localize(EWSDateTime.now())end=start+timedelta(hours=6)# get_free_busy_info() expects a list of (account, attendee_type, exclude_conflicts) tuplesaccounts=[(a,'Organizer',False)]forbusy_infoina.protocol.get_free_busy_info(accounts=accounts,start=start,end=end):# Convert the TimeZone object to a Microsoft timezone IDms_id=busy_info.working_hours_timezone.to_server_timezone(timezones,start.year)account_tz=EWSTimeZone.from_ms_id(ms_id)print(account_tz,busy_info.working_hours)foreventinbusy_info.calendar_events:print(account_tz.localize(event.start),account_tz.localize(event.end))TroubleshootingIf 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
going over the wire. This can be really handy to see which fields are
being sent and received.importlogging# This handler will pretty-print and syntax highlight the request and response XML documentsfromexchangelib.utilimportPrettyXmlHandlerlogging.basicConfig(level=logging.DEBUG,handlers=[PrettyXmlHandler()])# Your code using exchangelib goes hereMost class definitions have a docstring containing at least a URL to the
MSDN page for the corresponding XML element.fromexchangelibimportCalendarItemprint(CalendarItem.__doc__)NotesAlmost all item fields are supported. The remaining ones are tracked inhttps://github.com/ecederstrand/exchangelib/issues/203.