{"id":28473271,"url":"https://github.com/nylas/exchangelib","last_synced_at":"2025-07-02T02:31:14.896Z","repository":{"id":29662691,"uuid":"120348655","full_name":"nylas/exchangelib","owner":"nylas","description":"Python client for Microsoft Exchange Web Services (EWS)","archived":false,"fork":false,"pushed_at":"2024-02-01T16:04:53.000Z","size":3516,"stargazers_count":68,"open_issues_count":2,"forks_count":19,"subscribers_count":62,"default_branch":"master","last_synced_at":"2025-06-07T12:06:43.354Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/ecederstrand/exchangelib","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nylas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-02-05T19:06:28.000Z","updated_at":"2025-01-14T07:43:31.000Z","dependencies_parsed_at":"2023-12-14T20:29:28.710Z","dependency_job_id":"c9868498-a1df-4ae8-9db3-b282d9b08f6b","html_url":"https://github.com/nylas/exchangelib","commit_stats":null,"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"purl":"pkg:github/nylas/exchangelib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylas%2Fexchangelib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylas%2Fexchangelib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylas%2Fexchangelib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylas%2Fexchangelib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nylas","download_url":"https://codeload.github.com/nylas/exchangelib/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nylas%2Fexchangelib/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263063966,"owners_count":23408027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-07T12:06:42.602Z","updated_at":"2025-07-02T02:31:14.881Z","avatar_url":"https://github.com/nylas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"This is a fork of the original library\n======================================\nSee https://github.com/ecederstrand/exchangelib for the master repository.\n\nExchange Web Services client library\n====================================\n\nThis module provides an well-performing, well-behaving,\nplatform-independent and simple interface for communicating with a\nMicrosoft Exchange 2007-2016 Server or Office365 using Exchange Web\nServices (EWS). It currently implements autodiscover, and functions for\nsearching, creating, updating, deleting, exporting and uploading\ncalendar, mailbox, task, contact and distribution list items.\n\n[![image](https://img.shields.io/pypi/v/exchangelib.svg)](https://pypi.org/project/exchangelib/)\n[![image](https://img.shields.io/pypi/pyversions/exchangelib.svg)](https://pypi.org/project/exchangelib/)\n[![image](https://api.codacy.com/project/badge/Grade/5f805ad901054a889f4b99a82d6c1cb7)](https://www.codacy.com/app/ecederstrand/exchangelib?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=ecederstrand/exchangelib\u0026amp;utm_campaign=Badge_Grade)\n[![image](https://secure.travis-ci.org/ecederstrand/exchangelib.png)](http://travis-ci.org/ecederstrand/exchangelib)\n[![image](https://coveralls.io/repos/github/ecederstrand/exchangelib/badge.svg?branch=master)](https://coveralls.io/github/ecederstrand/exchangelib?branch=master)\n\nTeaser\n------\n\nHere's a short example of how `exchangelib` works. Let's print the first\n100 inbox messages in reverse order:\n\n```python\nfrom exchangelib import Credentials, Account\n\ncredentials = Credentials('john@example.com', 'topsecret')\naccount = Account('john@example.com', credentials=credentials, autodiscover=True)\n\nfor item in account.inbox.all().order_by('-datetime_received')[:100]:\n    print(item.subject, item.sender, item.datetime_received)\n```\n\n\n## Installation\nYou can install this package from PyPI:\n\n```bash\npip install exchangelib\n```\n\nTo install the very latest code, install directly from GitHub instead:\n\n```bash\npip install git+https://github.com/ecederstrand/exchangelib.git\n```\n\n`exchangelib` uses the `lxml` package, and `pykerberos` to support Kerberos authentication.\nTo be able to install these, you may need to install some additional operating system packages.\n\nOn Ubuntu:\n```bash\napt-get install libxml2-dev libxslt-dev libkrb5-dev build-essential libssl-dev libffi-dev python-dev\n```\n\nOn CentOS:\n```bash\nyum install gcc python-devel krb5-devel krb5-workstation python-devel\n```\n\nOn FreeBSD:\n```bash\npkg install libxml2 libxslt krb5\nCFLAGS=-I/usr/local/include pip install kerberos pykerberos lxml\n```\n\nFor other operating systems, please consult the documentation for the Python package that\nfails to install.\n\n\n### Setup and connecting\n\n```python\nfrom datetime import datetime, timedelta\nimport pytz\nfrom exchangelib import DELEGATE, IMPERSONATION, Account, Credentials, ServiceAccount, \\\n    EWSDateTime, EWSTimeZone, Configuration, NTLM, GSSAPI, CalendarItem, Message, \\\n    Mailbox, Attendee, Q, ExtendedProperty, FileAttachment, ItemAttachment, \\\n    HTMLBody, Build, Version, FolderCollection\n\n# Specify your credentials. Username is usually in WINDOMAIN\\username format, where WINDOMAIN is\n# the name of the Windows Domain your username is connected to, but some servers also\n# accept usernames in PrimarySMTPAddress ('myusername@example.com') format (Office365 requires it).\n# UPN format is also supported, if your server expects that.\ncredentials = Credentials(username='MYWINDOMAIN\\\\myusername', password='topsecret')\n\n# If you're running long-running jobs, you may want to enable fault-tolerance. Fault-tolerance\n# means that requests to the server do an exponential backoff and sleep for up to a certain\n# threshold before giving up, if the server is unavailable or responding with error messages.\n# This prevents automated scripts from overwhelming a failing or overloaded server, and hides\n# intermittent service outages that often happen in large Exchange installations.\n\n# If you want to enable the fault tolerance, create credentials as a service account instead:\ncredentials = ServiceAccount(username='FOO\\\\bar', password='topsecret')\n\n# An Account is the account on the Exchange server that you want to connect to. This can be\n# the account associated with the credentials you connect with, or any other account on the\n# server that you have been granted access to. If, for example, you want to access a shared\n# folder, create an Account instance using the email address of the account that the shared \n# folder belongs to, and access the shared folder through this account.\n\n# 'primary_smtp_address' is the primary SMTP address assigned the account. If you enable\n# autodiscover, an alias address will work, too. In this case, 'Account.primary_smtp_address'\n# will be set to the primary SMTP address.\nmy_account = Account(primary_smtp_address='myusername@example.com', credentials=credentials,\n                     autodiscover=True, access_type=DELEGATE)\njohns_account = Account(primary_smtp_address='john@example.com', credentials=credentials,\n                        autodiscover=True, access_type=DELEGATE)\nmarys_account = Account(primary_smtp_address='mary@example.com', credentials=credentials,\n                        autodiscover=True, access_type=DELEGATE)\nstill_marys_account = Account(primary_smtp_address='alias_for_mary@example.com',\n                              credentials=credentials, autodiscover=True, access_type=DELEGATE)\n\n# Set up a target account and do an autodiscover lookup to find the target EWS endpoint.\naccount = Account(primary_smtp_address='john@example.com', credentials=credentials,\n                  autodiscover=True, access_type=DELEGATE)\n\n# If your credentials have been given impersonation access to the target account, set a\n# different 'access_type':\naccount = Account(primary_smtp_address='john@example.com', credentials=credentials,\n                  autodiscover=True, access_type=IMPERSONATION)\n\n# If the server doesn't support autodiscover, or you want to avoid the overhead of autodiscover,\n# use a Configuration object to set the server location instead:\nconfig = Configuration(server='mail.example.com', credentials=credentials)\naccount = Account(primary_smtp_address='john@example.com', config=config,\n                  autodiscover=False, access_type=DELEGATE)\n\n# 'exchangelib' will attempt to guess the server version and authentication method. If you\n# have a really bizarre or locked-down installation and the guessing fails, or you want to avoid\n# the extra network traffic, you can set the auth method and version explicitly instead:\nversion = Version(build=Build(15, 0, 12, 34))\nconfig = Configuration(\n    server='example.com', credentials=credentials, version=version, auth_type=NTLM\n)\n\n# Kerberos authentication is supported via the 'gssapi' auth type. Enabling it is slightly awkward,\n# does not work with autodiscover (yet) and is likely to change in future versions.\ncredentials = Credentials('', '')\nconfig = Configuration(server='example.com', credentials=credentials, auth_type=GSSAPI)\n\n# If you're connecting to the same account very often, you can cache the autodiscover result for\n# later so you can skip the autodiscover lookup:\news_url = account.protocol.service_endpoint\news_auth_type = account.protocol.auth_type\nprimary_smtp_address = account.primary_smtp_address\n\n# 5 minutes later, fetch the cached values and create the account without autodiscovering:\nconfig = Configuration(service_endpoint=ews_url, credentials=credentials, auth_type=ews_auth_type)\naccount = Account(\n    primary_smtp_address=primary_smtp_address, \n    config=config, autodiscover=False, \n    access_type=DELEGATE,\n)\n```\n\n### Proxies and custom TLS validation\n\nIf you need proxy support or custom TLS validation, you can supply a\ncustom 'requests' transport adapter class, as described in\n\u003chttp://docs.python-requests.org/en/master/user/advanced/#transport-adapters\u003e.\n\nHere's an example using different custom root certificates depending on\nthe server to connect to:\n\n```python\nfrom urllib.parse import urlparse\nimport requests.adapters\nfrom exchangelib.protocol import BaseProtocol\n\nclass RootCAAdapter(requests.adapters.HTTPAdapter):\n    # An HTTP adapter that uses a custom root CA certificate at a hard coded location\n    def cert_verify(self, conn, url, verify, cert):\n        cert_file = {\n            'example.com': '/path/to/example.com.crt',\n            'mail.internal': '/path/to/mail.internal.crt',\n            ...\n        }[urlparse(url).hostname]\n        super(RootCAAdapter, self).cert_verify(conn=conn, url=url, verify=cert_file, cert=cert)\n\n# Tell exchangelib to use this adapter class instead of the default\nBaseProtocol.HTTP_ADAPTER_CLS = RootCAAdapter\n```\n\nHere's an example of adding proxy support:\n\n```python\nclass ProxyAdapter(requests.adapters.HTTPAdapter):\n    def send(self, *args, **kwargs):\n        kwargs['proxies'] = {\n            'http': 'http://10.0.0.1:1243',\n            'https': 'http://10.0.0.1:4321',\n        }\n        return super(ProxyAdapter, self).send(*args, **kwargs)\n\n# Tell exchangelib to use this adapter class instead of the default\nBaseProtocol.HTTP_ADAPTER_CLS = ProxyAdapter\n```\n\n`exchangelib` provides a sample adapter which ignores TLS validation\nerrors. Use at own risk.\n\n```python\nfrom exchangelib.protocol import NoVerifyHTTPAdapter\n\n# Tell exchangelib to use this adapter class instead of the default\nBaseProtocol.HTTP_ADAPTER_CLS = NoVerifyHTTPAdapter\n```\n\n### Folders\nAll wellknown folders are available as properties on the account, e.g. as `account.root`, `account.calendar`,\n`account.trash`, `account.inbox`, `account.outbox`, `account.sent`, `account.junk`, `account.tasks` and\n`account.contacts`.\n\n```python\n# There are multiple ways of navigating the folder tree and searching for folders. Globbing and \n# absolute path may create unexpected results if your folder names contain slashes.\nsome_folder.parent\nsome_folder.parent.parent.parent\nsome_folder.root  # Returns the root of the folder structure, at any level. Same as Account.root\nsome_folder.children  # A generator of child folders\nsome_folder.absolute  # Returns the absolute path, as a string\nsome_folder.walk()  # A generator returning all subfolders at arbitrary depth this level\n# Globbing uses the normal UNIX globbing syntax\nsome_folder.glob('foo*')  # Return child folders matching the pattern\nsome_folder.glob('*/foo')  # Return subfolders named 'foo' in any child folder\nsome_folder.glob('**/foo')  # Return subfolders named 'foo' at any depth\nsome_folder / 'sub_folder' / 'even_deeper' / 'leaf'  # Works like pathlib.Path\nsome_folder.parts  # returns some_folder and all its parents, as Folder instances\n# tree() returns a string representation of the tree structure at the given level\nprint(root.tree())\n'''\nroot\n├── inbox\n│   └── todos\n└── archive\n    ├── Last Job\n    ├── exchangelib issues\n    └── Mom\n'''\n\n# Folders have some useful counters:\naccount.inbox.total_count\naccount.inbox.child_folder_count\naccount.inbox.unread_count\n# Update the counters\naccount.inbox.refresh()\n# The folder structure is cached after first access. To clear the cache, refresh the root folder\naccount.root.refresh()\n\n# Folders can be created, updated and deleted:\nf = Folder(parent=self.account.inbox, name='My New Folder')\nf.save()\n\nf.name = 'My New Subfolder'\nf.save()\n\nf.delete()\n```\n\n### Dates, datetimes and timezones\n\nEWS has some special requirements on datetimes and timezones. You need\nto use the special `EWSDate`, `EWSDateTime` and `EWSTimeZone` classes\nwhen working with dates.\n\n```python\n# EWSTimeZone works just like pytz.timezone()\ntz = EWSTimeZone.timezone('Europe/Copenhagen')\n# You can also get the local timezone defined in your operating system\ntz = EWSTimeZone.localzone()\n\n# EWSDate and EWSDateTime work just like datetime.datetime and datetime.date. Always create\n# timezone-aware datetimes with EWSTimeZone.localize():\nlocalized_dt = tz.localize(EWSDateTime(2017, 9, 5, 8, 30))\nright_now = tz.localize(EWSDateTime.now())\n\n# Datetime math works transparently\ntwo_hours_later = localized_dt + timedelta(hours=2)\ntwo_hours = two_hours_later - localized_dt\ntwo_hours_later += timedelta(hours=2)\n\n# Dates\nmy_date = EWSDate(2017, 9, 5)\ntoday = EWSDate.today()\nalso_today = right_now.date()\nalso_today += timedelta(days=10)\n\n# UTC helpers. 'UTC' is the UTC timezone as an EWSTimeZone instance.\n# 'UTC_NOW' returns a timezone-aware UTC timestamp of current time.\nfrom exchangelib import UTC, UTC_NOW\n\nright_now_in_utc = UTC.localize(EWSDateTime.now())\nright_now_in_utc = UTC_NOW()\n\n# Already have a Python datetime object you want to use? Make sure it's localized. Then pass \n# it to from_datetime().\npytz_tz = pytz.timezone('Europe/Copenhagen')\npy_dt = pytz_tz.localize(datetime(2017, 12, 11, 10, 9, 8))\news_now = EWSDateTime.from_datetime(py_dt)\n```\n\n### Creating, updating, deleting, sending and moving\n\n```python\n# Here's an example of creating a calendar item in the user's standard calendar.  If you want to\n# access a non-standard calendar, choose a different one from account.folders[Calendar].\n#\n# You can create, update and delete single items:\nfrom exchangelib.items import SEND_ONLY_TO_ALL, SEND_ONLY_TO_CHANGED\nitem = CalendarItem(folder=account.calendar, subject='foo')\nitem.save()  # This gives the item an 'id' and a 'changekey' value\nitem.save(send_meeting_invitations=SEND_ONLY_TO_ALL)  # Send a meeting invitation to attendees\n# Update a field. All fields have a corresponding Python type that must be used.\nitem.subject = 'bar'\n# Print all available fields on the 'CalendarItem' class. Beware that some fields are read-only, or\n# read-only after the item has been saved or sent, and some fields are not supported on old\n# versions of Exchange.\nprint(CalendarItem.FIELDS)\nitem.save()  # When the items has an item_id, this will update the item\nitem.save(update_fields=['subject'])  # Only updates certain fields\nitem.save(send_meeting_invitations=SEND_ONLY_TO_CHANGED)  # Send invites only to attendee changes\nitem.delete()  # Hard deletinon\nitem.delete(send_meeting_cancellations=SEND_ONLY_TO_ALL)  # Send cancellations to all attendees\nitem.soft_delete()  # Delete, but keep a copy in the recoverable items folder\nitem.move_to_trash()  # Move to the trash folder\nitem.move(account.trash)  # Also moves the item to the trash folder\nitem.copy(account.trash)  # Creates a copy of the item to the trash folder\n\n# You can also send emails. If you don't want a local copy:\nm = Message(\n    account=a,\n    subject='Daily motivation',\n    body='All bodies are beautiful',\n    to_recipients=[\n        Mailbox(email_address='anne@example.com'),\n        Mailbox(email_address='bob@example.com'),\n    ],\n    cc_recipients=['carl@example.com', 'denice@example.com'],  # Simple strings work, too\n    bcc_recipients=[\n        Mailbox(email_address='erik@example.com'),\n        'felicity@example.com',\n    ],  # Or a mix of both\n)\nm.send()\n\n# Or, if you want a copy in e.g. the 'Sent' folder\nm = Message(\n    account=a,\n    folder=a.sent,\n    subject='Daily motivation',\n    body='All bodies are beautiful',\n    to_recipients=[Mailbox(email_address='anne@example.com')]\n)\nm.send_and_save()\n\n# Likewise, you can reply to and forward messages\nm.reply(\n    subject='Re: foo',\n    body='I agree',\n    to_recipients=['carl@example.com', 'denice@example.com']\n)\nm.reply_all(subject='Re: foo', body='I agree')\nm.forward(\n    subject='Fwd: foo', \n    body='Hey, look at this!', \n    to_recipients=['carl@example.com', 'denice@example.com']\n)\n\n# EWS distinquishes between plain text and HTML body contents. If you want to send HTML body \n# content, use the HTMLBody helper. Clients will see this as HTML and display the body correctly:\nitem.body = HTMLBody('\u003chtml\u003e\u003cbody\u003eHello happy \u003cblink\u003eOWA user!\u003c/blink\u003e\u003c/body\u003e\u003c/html\u003e')\n```\n\n### Bulk operations\n\n```python\n# Build a list of calendar items\ntz = EWSTimeZone.timezone('Europe/Copenhagen')\nyear, month, day = 2016, 3, 20\ncalendar_items = []\nfor hour in range(7, 17):\n    calendar_items.append(CalendarItem(\n        start=tz.localize(EWSDateTime(year, month, day, hour, 30)),\n        end=tz.localize(EWSDateTime(year, month, day, hour + 1, 15)),\n        subject='Test item',\n        body='Hello from Python',\n        location='devnull',\n        categories=['foo', 'bar'],\n        required_attendees = [Attendee(\n            mailbox=Mailbox(email_address='user1@example.com'),\n            response_type='Accept'\n        )]\n    ))\n\n# Create all items at once\nreturn_ids = account.bulk_create(folder=account.calendar, items=calendar_items)\n\n# Bulk fetch, when you have a list of item IDs and want the full objects. Returns a generator.\ncalendar_ids = [(i.id, i.changekey) for i in calendar_items]\nitems_iter = account.fetch(ids=calendar_ids)\n# If you only want some fields, use the 'only_fields' attribute\nitems_iter = account.fetch(ids=calendar_ids, only_fields=['start', 'subject'])\n\n# Bulk update items. Each item must be accompanied by a list of attributes to update\nupdated_ids = account.bulk_create(items=[(i, ('start', 'subject')) for i in calendar_items])\n\n# Move many items to a new folder\nnew_ids = account.bulk_move(ids=calendar_ids, to_folder=account.other_calendar)\n\n# Send draft messages in bulk\nnew_ids = account.bulk_send(ids=message_ids, save_copy=False)\n\n# Delete in bulk\ndelete_results = account.bulk_delete(ids=calendar_ids)\n\n# Bulk delete items found as a queryset\naccount.inbox.filter(subject__startswith='Invoice').delete()\n```\n\n### Searching\n\nSearching is modeled after the Django QuerySet API, and a large part of\nthe API is supported. Like in Django, the QuerySet is lazy and doesn't\nfetch anything before the QuerySet is iterated. QuerySets support\nchaining, so you can build the final query in multiple steps, and you\ncan re-use a base QuerySet for multiple sub-searches. The QuerySet\nreturns an iterator, and results are cached when the QuerySet is fully\niterated the first time.\n\nHere are some examples of using the API:\n\n```python\n# Let's get the calendar items we just created.\nall_items = my_folder.all()  # Get everything\nall_items_without_caching = my_folder.all().iterator()  # Get everything, but don't cache\n# Chain multiple modifiers ro refine the query\nfiltered_items = my_folder.filter(subject__contains='foo').exclude(categories__icontains='bar')\nstatus_report = my_folder.all().delete()  # Delete the items returned by the QuerySet\nitems_for_2017 = my_calendar.filter(start__range=(\n    tz.localize(EWSDateTime(2017, 1, 1)),\n    tz.localize(EWSDateTime(2018, 1, 1))\n))  # Filter by a date range\n# Same as filter() but throws an error if exactly one item isn't returned\nitem = my_folder.get(subject='unique_string')\n\n# You can sort by a single or multiple fields. Prefix a field with '-' to reverse the sorting. \n# Sorting is efficient since it is done server-side.\nordered_items = my_folder.all().order_by('subject')\nreverse_ordered_items = my_folder.all().order_by('-subject')\n # Indexed properties can be ordered on their individual components\nsorted_by_home_street = my_contacts.all().order_by('physical_addresses__Home__street')\ndont_do_this = my_huge_folder.all().order_by('subject', 'categories')[:10]  # This is efficient\n\n# Counting and exists\nn = my_folder.all().count()  # Efficient counting\nfolder_is_empty = not my_folder.all().exists()  # Efficient tasting\n\n# Restricting returned attributes\nsparse_items = my_folder.all().only('subject', 'start')\n# Dig deeper on indexed properties\nsparse_items = my_contacts.all().only('phone_numbers')\nsparse_items = my_contacts.all().only('phone_numbers__CarPhone')\nsparse_items = my_contacts.all().only('physical_addresses__Home__street')\n\n# Return values as dicts, not objects\nids_as_dict = my_folder.all().values('id', 'changekey')\n# Return values as nested lists\nvalues_as_list = my_folder.all().values_list('subject', 'body')\n# Return values as a flat list\nall_subjects = my_folder.all().values_list('physical_addresses__Home__street', flat=True)\n\n# A QuerySet can be sliced like a normal Python list. Slicing from the start of the QuerySet\n# is efficient (it only fetches the necessary items), but more exotic slicing requires many or all\n# items to be fetched from the server. Slicing from the end is also efficient, but then you might\n# as well just reverse the sorting.\nfirst_ten = my_folder.all().order_by('-subject')[:10]  # Efficient\nlast_ten = my_folder.all().order_by('-subject')[:-10]  # Efficient, but convoluted\nnext_ten = my_folder.all().order_by('-subject')[10:20]  # Somewhat efficient, but we fetch 20 items\nsingle_item = my_folder.all().order_by('-subject')[34298]  # This is looking for trouble\nsingle_item = my_folder.all().order_by('-subject')[3420:3430]  # This is also looking for trouble\nrandom_emails = my_folder.all().order_by('-subject')[::3]  # This is just stupid\n\n# The syntax for filter() is modeled after Django QuerySet filters. The following filter lookup \n# types are supported. Some lookups only work with string attributes. Range and less/greater \n# operators only work for date or numerical attributes. Some attributes are not searchable at all \n# via EWS:\nqs = account.calendar.all()\nqs.filter(subject='foo')  # Returns items where subject is exactly 'foo'. Case-sensitive\nqs.filter(start__range=(dt1, dt2))  # Returns items within range\nqs.filter(subject__in=('foo', 'bar'))  # Return items where subject is either 'foo' or 'bar'\nqs.filter(subject__not='foo')  # Returns items where subject is not 'foo'\nqs.filter(start__gt=dt)  # Returns items starting after 'dt'\nqs.filter(start__gte=dt)  # Returns items starting on or after 'dt'\nqs.filter(start__lt=dt)  # Returns items starting before 'dt'\nqs.filter(start__lte=dt)  # Returns items starting on or before 'dt'\nqs.filter(subject__exact='foo')  # Same as filter(subject='foo')\nqs.filter(subject__iexact='foo')  #  Returns items where subject is 'foo', 'FOO' or 'Foo'\nqs.filter(subject__contains='foo')  # Returns items where subject contains 'foo'\nqs.filter(subject__icontains='foo')  # Returns items where subject contains 'foo', 'FOO' or 'Foo'\nqs.filter(subject__startswith='foo')  # Returns items where subject starts with 'foo'\n# Returns items where subject starts with 'foo', 'FOO' or 'Foo'\nqs.filter(subject__istartswith='foo')\n# Returns items that have at least one category assigned, i.e. the field exists on the item on the \n# server.\nqs.filter(categories__exists=True)\n# Returns items that have no categories set, i.e. the field does not exist on the item on the \n# server.\nqs.filter(categories__exists=False)\n\n# filter() also supports EWS QueryStrings. Just pass the string to filter(). QueryStrings cannot\n# be combined with other filters. We make no attempt at validating the syntax of the QueryString \n# - we just pass the string verbatim to EWS.\n#\n# Read more about the QueryString syntax here:\n# https://msdn.microsoft.com/en-us/library/ee693615.aspx\nitems = my_folder.filter('subject:XXX')\n\n# filter() also supports Q objects that are modeled after Django Q objects, for building complex\n# boolean logic search expressions.\nq = (Q(subject__iexact='foo') | Q(subject__contains='bar')) \u0026 ~Q(subject__startswith='baz')\nitems = my_folder.filter(q)\n\n# In this example, we filter by categories so we only get the items created by us.\nitems = account.calendar.filter(\n    start__lt=tz.localize(EWSDateTime(year, month, day + 1)),\n    end__gt=tz.localize(EWSDateTime(year, month, day)),\n    categories__contains=['foo', 'bar'],\n)\nfor item in items:\n    print(item.start, item.end, item.subject, item.body, item.location)\n\n# By default, EWS returns only the master recurring item. If you want recurring calendar\n# items to be expanded, use calendar.view(start=..., end=...) instead.\nitems = account.calendar.view(\n    start=tz.localize(EWSDateTime(year, month, day)),\n    end=tz.localize(EWSDateTime(year, month, day)) + timedelta(days=1),\n)\nfor item in items:\n    print(item.start, item.end, item.subject, item.body, item.location)\n\n# You can combine view() with other modifiers. For example, to check for conflicts before \n# adding a meeting from 8:00 to 10:00:\nhas_conflicts = a.calendar.view(\n    start=a.default_timezone.localize(EWSDateTime(year, month, day, 8)),\n    end=a.default_timezone.localize(EWSDateTime(year, month, day, 10)),\n    max_items=1\n).exists()\n\n# The filtering syntax also works on collections of folders, so you can search multiple folders in \n# a single request.\nmy_folder.children.filter(subject='foo')\nmy_folder.walk().filter(subject='foo')\nmy_folder.glob('foo*').filter(subject='foo')\n# Or select the folders individually\nFolderCollection(account=account, folders=[account.inbox, account.calendar]).filter(subject='foo')\n```\n\n### Meetings\n\nThe `CalendarItem` class allows you send out requests for meetings that\nyou initiate or to cancel meetings that you already set out before. It\nis also possible to process `MeetingRequest` messages that are received.\nYou can reply to these messages using the `AcceptItem`,\n`TentativelyAcceptItem` and `DeclineItem` classes. If you receive a\ncancellation for a meeting (class `MeetingCancellation`) that you\nalready accepted then you can also process these by removing the entry\nfrom the calendar.\n\n```python\n# create a meeting request and send it out\ncalendar_item = CalendarItem(\n    account=account,\n    folder=account.calendar,\n    start=tz.localize(EWSDateTime(year, month, day, hour, minute)),\n    end=tz.localize(EWSDateTime(year, month, day, hour, minute)),\n    subject=\"Subject of Meeting\",\n    body=\"Please come to my meeting\",\n    required_attendees=['anne@example.com', 'bob@example.com']\n)\nitem.save(send_meeting_invitations=SEND_TO_ALL_AND_SAVE_COPY)\n\n# cancel a meeting that was sent out using the CalendarItem class\nfor calendar_item in account.calendar.all().order_by('-datetime_received')[:5]:\n    # only the organizer of a meeting can cancel it\n    if calendar_item.organizer.email_address == account.primary_smtp_address:\n        calendar_item.cancel()\n\n# processing an incoming MeetingRequest\nfor item in account.inbox.all().order_by('-datetime_received')[:5]:\n    if isinstance(item, MeetingRequest):\n        item.accept(body=\"Sure, I'll come\")\n        # Or:\n        item.decline(body=\"No way!\")\n        # Or:\n        item.tentatively_accept(body=\"Maybe...\")\n\n# meeting requests can also be handled from the calendar - e.g. decline the meeting that was \n# received last.\nfor calendar_item in account.calendar.all().order_by('-datetime_received')[:1]:\n    calendar_item.decline()\n\n# processing an incoming MeetingCancellation (also delete from calendar)\nfor item in account.inbox.all().order_by('-datetime_received')[:5]:\n    if isinstance(ews_item, MeetingCancellation):\n        if item.associated_calendar_item_id:\n            calendar_item = account.inbox.get(id=item.associated_calendar_item_id.id,\n                                              changekey=item.associated_calendar_item_id.changekey)\n            calendar_item.delete()\n        item.move_to_trash()\n```\n\n### Searching contacts\n\nFetching personas from a contact folderis supported using the same\nsyntax as folders. Just start your query with `.people()`:\n\n```python\n# Navigate to a contact folder and start the search\nfolder = a.root / 'AllContacts'\nfor p in folder.people():\n    print(p)\nfor p in folder.people().only('display_name').filter(display_name='john').order_by('display_name'):\n    print(p)\n```\n\n### Extended properties\n\nExtended properties makes it possible to attach custom key-value pairs\nto items and folders on the Exchange server. There are multiple online\nresources that describe working with extended properties, and list many\nof the magic values that are used by existing Exchange clients to store\ncommon and custom properties. The following is not a comprehensive\ndescription of the possibilities, but we do intend to support all the\npossibilities provided by EWS.\n\n```python\n# If folder items have extended properties, you need to register them before you can access them. \n# Create a subclass of ExtendedProperty and define a set of matching setup values:\nclass LunchMenu(ExtendedProperty):\n    property_set_id = '12345678-1234-1234-1234-123456781234'\n    property_name = 'Catering from the cafeteria'\n    property_type = 'String'\n\n# Register the property on the item type of your choice\nCalendarItem.register('lunch_menu', LunchMenu)\n# Now your property is available as the attribute 'lunch_menu', just like any other attribute\nitem = CalendarItem(..., lunch_menu='Foie gras et consommé de légumes')\nitem.save()\nfor i in account.calendar.all():\n    print(i.lunch_menu)\n# If you change your mind, jsut remove the property again\nCalendarItem.deregister('lunch_menu')\n\n# You can also create named properties (e.g. created from User Defined Fields in Outlook, see \n# issue #137):\nclass LunchMenu(ExtendedProperty):\n    distinguished_property_set_id = 'PublicStrings'\n    property_name = 'Catering from the cafeteria'\n    property_type = 'String'\n\n# We support extended properties with tags. This is the definition for the 'completed' and \n# 'followup' flag you can add to items in Outlook (see also issue #85):\nclass Flag(ExtendedProperty):\n    property_tag = 0x1090\n    property_type = 'Integer'\n\n# Or with property ID:\nclass MyMeetingArray(ExtendedProperty):\n    property_set_id = '00062004-0000-0000-C000-000000000046'\n    property_type = 'BinaryArray'\n    property_id = 32852\n\n# Or using distinguished property sets combined with property ID (here as a hex value to align \n# with the format usually mentioned in Microsoft docs). This is the definition for a response to\n# an Outlook Vote request (see issue #198):\nclass VoteResponse(ExtendedProperty):\n    distinguished_property_set_id = 'Common'\n    property_id = 0x00008524\n    property_type = 'String'\n\n# Extended properties also work with folders. Here's an example of getting the size (in bytes) of\n# a folder:\nclass FolderSize(ExtendedProperty):\n    property_tag = 0x0e08\n    property_type = 'Integer'\n\nFolder.register('size', FolderSize)\nprint(my_folder.size)\n\n# In general, here's how to work with any MAPI property as listed in e.g.\n# https://msdn.microsoft.com/EN-US/library/office/cc815517.aspx. Let's take `PidLidTaskDueDate` as\n# an example. This is the due date for a message maked with the follow-up flag in Microsoft \n# Outlook.\n#\n# PidLidTaskDueDate is documented at https://msdn.microsoft.com/en-us/library/office/cc839641.aspx.\n# The property ID is `0x00008105` and the property set is `PSETID_Task`. But EWS wants the UUID for\n# `PSETID_Task`, so we look that up in the MS-OXPROPS pdf:\n# https://msdn.microsoft.com/en-us/library/cc433490(v=exchg.80).aspx. The UUID is\n# `00062003-0000-0000-C000-000000000046`. The property type is `PT_SYSTIME` which is also called\n# `SystemTime` (see\n# https://msdn.microsoft.com/en-us/library/microsoft.exchange.webservices.data.mapipropertytype(v=exchg.80).aspx).\n#\n# In conclusion, the definition for the due date becomes:\n\nclass FlagDue(ExtendedProperty):\n    property_set_id = '00062003-0000-0000-C000-000000000046'\n    property_id = 0x8105\n    property_type = 'SystemTime'\n\nMessage.register('flag_due', FlagDue)\n```\n\n### Attachments\n\n```python\n# It's possible to create, delete and get attachments connected to any item type:\n# Process attachments on existing items. FileAttachments have a 'content' attribute\n# containing the binary content of the file, and ItemAttachments have an 'item' attribute\n# containing the item. The item can be a Message, CalendarItem, Task etc.\nfor item in my_folder.all():\n    for attachment in item.attachments:\n        if isinstance(attachment, FileAttachment):\n            local_path = os.path.join('/tmp', attachment.name)\n            with open(local_path, 'wb') as f:\n                f.write(attachment.content)\n            print('Saved attachment to', local_path)\n        elif isinstance(attachment, ItemAttachment):\n            if isinstance(attachment.item, Message):\n                print(attachment.item.subject, attachment.item.body)\n\n# Create a new item with an attachment\nitem = Message(...)\nbinary_file_content = 'Hello from unicode æøå'.encode('utf-8')  # Or read from file, BytesIO etc.\nmy_file = FileAttachment(name='my_file.txt', content=binary_file_content)\nitem.attach(my_file)\nmy_calendar_item = CalendarItem(...)\nmy_appointment = ItemAttachment(name='my_appointment', item=my_calendar_item)\nitem.attach(my_appointment)\nitem.save()\n\n# Add an attachment on an existing item\nmy_other_file = FileAttachment(name='my_other_file.txt', content=binary_file_content)\nitem.attach(my_other_file)\n\n# Remove the attachment again\nitem.detach(my_file)\n\n# If you want to embed an image in the item body, you can link to the file in the HTML\nlogo_filename = 'logo.png'\nwith open(logo_filename, 'rb') as f:\n    my_logo = FileAttachment(name=logo_filename, content=f.read(), is_inline=True, content_id=logo_filename)\nmessage.attach(my_logo)\nmessage.body = HTMLBody('\u003chtml\u003e\u003cbody\u003eHello logo: \u003cimg src=\"cid:%s\"\u003e\u003c/body\u003e\u003c/html\u003e' % logo_filename)\n\n# Attachments cannot be updated via EWS. In this case, you must to detach the attachment, update\n# the relevant fields, and attach the updated attachment.\n\n# Be aware that adding and deleting attachments from items that are already created in Exchange\n# (items that have an item_id) will update the changekey of the item.\n```\n\n### Recurring calendar items\n\nThere is full read-write support for creating recurring calendar items.\nYou can create daily, weekly, monthly and yearly recurrences (the latter\ntwo in relative and absolute versions).\n\nHere's an example of creating 7 occurrences on Mondays and Wednesdays of\nevery third week, starting September 1, 2017:\n\n```python\nfrom exchangelib.recurrence import Recurrence, WeeklyPattern, MONDAY, WEDNESDAY\n\nstart = tz.localize(EWSDateTime(2017, 9, 1, 11))\nitem = CalendarItem(\n    folder=a.calendar,\n    start=start,\n    end=start + timedelta(hours=2),\n    subject='Hello Recurrence',\n    recurrence=Recurrence(\n        pattern=WeeklyPattern(interval=3, weekdays=[MONDAY, WEDNESDAY]),\n        start=start.date(),\n        number=7\n    ),\n)\n\n# Occurrence data for the master item\nfor i in a.calendar.filter(start__lt=end, end__gt=start):\n    print(i.subject, i.start, i.end)\n    print(i.recurrence)\n    print(i.first_occurrence)\n    print(i.last_occurrence)\n    for o in i.modified_occurrences:\n        print(o)\n    for o in i.deleted_occurrences:\n        print(o)\n\n# All occurrences expanded. The recurrence will span over 4 iterations of a 3-week period\nfor i in a.calendar.view(start=start, end=start + timedelta(days=4*3*7)):\n    print(i.subject, i.start, i.end)\n\n# 'modified_occurrences' and 'deleted_occurrences' of master items are read-only fields. To \n# delete or modify an occurrence, you must use 'view()' to fetch the occurrence and modify or \n# delete it:\nfor occurrence in a.calendar.view(start=start, end=start + timedelta(days=4*3*7)):\n    # Delete or update random occurrences. This will affect  'modified_occurrences' and \n    # 'deleted_occurrences' of the master item.\n    if i.start.milliseconds % 2:\n        # We receive timestamps as UTC but want to write them back as local timezone\n        occurrence.start = occurrence.start.astimezone(tz)\n        occurrence.start += datetime.timedelta(minutes=30)\n        occurrence.end = occurrence.end.astimezone(tz)\n        occurrence.end += datetime.timedelta(minutes=30)\n        occurrence.subject = 'My new subject'\n        occurrence.save()\n    else:\n        item.delete()\n```\n\n### Message timestamp fields\n\nEach `Message` item has four timestamp fields:\n\n-   `datetime_created`\n-   `datetime_sent`\n-   `datetime_received`\n-   `last_modified_time`\n\nThe values for these fields are set by the Exchange server and are not\nmodifiable via EWS. All values are timezone-aware `EWSDateTime`\ninstances.\n\nThe `datetime_sent` value may be earlier than `datetime_created`.\n\n### Out of Facility\n\nYou can get and set OOF messages using the `Account.oof_settings`\nproperty:\n\n```python\n# Get the current OOF settings\na.oof_settings\n# Change the OOF settings to something else\na.oof_settings = OofSettings(\n    state=OofSettings.SCHEDULED,\n    external_audience='Known',\n    internal_reply=\"I'm in the pub. See ya guys!\",\n    external_reply=\"I'm having a business dinner in town\",\n    start=tz.localize(EWSDateTime(2017, 11, 1, 11)),\n    end=tz.localize(EWSDateTime(2017, 12, 1, 11)),\n)\n# Disable OOF messages\na.oof_settings = OofSettings(\n    state=OofSettings.DISABLED,\n    internal_reply='',\n    external_reply='',\n)\n```\n\n### Export and upload\n\nExchange supports backup and restore of folder contents using special\nexport and upload services. They are available on the `Account` model:\n\n```python\ndata = a.export(items)  # Pass a list of Item instances or (item_id, changekey) tuples\na.upload((a.inbox, d) for d in data))  # Restore the items. Expects a list of (folder, data) tuples\n```\n\n### Non-account methods\n\n```python\n# Get timezone information from the server\na.protocol.get_timezones()\n\n# Get room lists defined on the server\na.protocol.get_roomlists()\n\n# Get rooms belonging to a specific room list\na.protocol.get_rooms(some_roomlist)\n\n# Get account information for a list of names or email addresses\nfor mailbox in a.protocol.resolve_names(['ann@example.com', 'bart@example.com']):\n    print(mailbox.email_address)\nfor mailbox, contact in a.protocol.resolve_names(['anne', 'bart'], return_full_contact_data=True):\n    print(mailbox.email_address, contact.display_name)\n\n# Get availability information for a list of accounts\nstart = tz.localize(EWSDateTime.now())\nend = tz.localize(EWSDateTime.now() + datetime.timedelta(hours=6))\n# Create a list of (account, attendee_type, exclude_conflicts) tuples\naccounts = [(account, 'Organizer', False)]\na.protocol.get_free_busy_info(accounts=accounts, start=start, end=end)\n\n# Get searchable mailboxes. This method is only available to users who have been assigned\n# the Discovery Management RBAC role.\nfor mailbox in a.protocol.get_searchable_mailboxes():\n    print(mailbox)\n```\n\n### Troubleshooting\n\nIf you are having trouble using this library, the first thing to try is\nto enable debug logging. This will output a huge amount of information\nabout what is going on, most notable the actual XML documents that are\ngoing over the wire. This can be really handy to see which fields are\nbeing sent and received.\n\n```python\nimport logging\n# This handler will pretty-print and syntax highlight the request and response XML documents\nfrom exchangelib.util import PrettyXmlHandler\n\nlogging.basicConfig(level=logging.DEBUG, handlers=[PrettyXmlHandler()])\n# Your code using exchangelib goes here\n```\n\nMost class definitions have a docstring containing at least a URL to the\nMSDN page for the corresponding XML element.\n\n```python\nfrom exchangelib import CalendarItem\nprint(CalendarItem.__doc__)\n```\n\n### Notes\n\nAlmost all item fields are supported. The remaining ones are tracked in\n\u003chttps://github.com/ecederstrand/exchangelib/issues/203\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnylas%2Fexchangelib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnylas%2Fexchangelib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnylas%2Fexchangelib/lists"}