Exchangelib

5.6.0 · active · verified Sat Apr 11

Exchangelib is a Python client for Microsoft Exchange Web Services (EWS), providing programmatic access to Exchange mailboxes, calendars, contacts, and tasks. It supports autodiscovery, various authentication methods (NTLM, OAuth), and aims to be a comprehensive, easy-to-use interface for EWS. The current version is 5.6.0, with a release cadence that responds to bug fixes, feature requests, and EWS changes.

Warnings

breaking Version 5.0.0 removed `BasicAuth` as a standalone class. Authentication details are now handled directly by the `Credentials` class or implicitly by the `Protocol` class. Custom protocol definitions must be updated.
Fix: Migrate authentication logic to use `exchangelib.Credentials` directly. For custom protocols, ensure `auth_type` and other parameters are correctly passed to `Protocol`.
breaking In version 5.0.0, the `protocol.ews_url` attribute was renamed to `protocol.autodiscover_url` for clarity. The attribute that points to the actual EWS service endpoint is now `protocol.ews_url` (previously `protocol.service_endpoint`). This affects direct manipulation or inspection of `Protocol` objects.
Fix: Update any code that references `protocol.ews_url` (for autodiscover URL) to `protocol.autodiscover_url` and `protocol.service_endpoint` (for service endpoint URL) to `protocol.ews_url`.
gotcha Time zone handling can be complex with EWS, especially when dealing with recurring events or ensuring consistent timestamps across systems. EWS often expects UTC or specific EWS timezones.
Fix: Always use `exchangelib.EWSTimeZone` when creating or modifying datetime objects that interact with Exchange. Ensure your local system's timezone is correctly configured if relying on `tzlocal`.
gotcha Fetching all items from large folders (`folder.all()`) can be very slow and consume excessive memory. EWS APIs are often paginated.
Fix: Use iterators or specify a maximum number of items when querying large folders (e.g., `folder.all().order_by('-datetime_received')[:100]`). For complex queries, use `folder.filter().iterator()`.
gotcha Autodiscovery might fail in complex network environments or specific Exchange configurations. This prevents `Account` from establishing a connection.
Fix: If autodiscovery fails, explicitly provide the `ews_url` when creating a `Configuration` object, then pass that configuration to the `Account`. Example: `config = Configuration(server='outlook.office365.com', credentials=credentials, ews_url='https://outlook.office365.com/EWS/Exchange.asmx')`.

Install

pip install exchangelib Install stable version

Imports

Account
```
from exchangelib import Account
```
Credentials
```
from exchangelib import Credentials
```
Configuration
```
from exchangelib import Configuration
```
DELEGATE
```
from exchangelib import DELEGATE
```
EWSTimeZone
```
from exchangelib import EWSTimeZone
```
IMPERSONATION
```
from exchangelib import IMPERSONATION
```
Message
```
from exchangelib import Message
```
Mailbox
```
from exchangelib import Mailbox
```
Folder
```
from exchangelib import Folder
```

Quickstart

This quickstart demonstrates how to connect to an Exchange mailbox using email/password credentials and autodiscovery. It then fetches and prints the subjects of the 5 most recent unread items in the inbox. It uses environment variables for security to avoid hardcoding sensitive information.

import os
from exchangelib import Account, Credentials, Configuration, DELEGATE

# Get credentials from environment variables for security
email = os.environ.get('EXCHANGE_EMAIL', 'your_email@example.com')
password = os.environ.get('EXCHANGE_PASSWORD', 'your_password')

if not email or not password or email == 'your_email@example.com':
    print("Please set EXCHANGE_EMAIL and EXCHANGE_PASSWORD environment variables.")
    print("Or replace placeholders directly in the script (not recommended for production).")
    exit(1)

credentials = Credentials(email, password)

try:
    # Autodiscover the EWS URL and connect
    account = Account(
        primary_smtp_address=email,
        credentials=credentials,
        autodiscover=True,
        access_type=DELEGATE # Or IMPERSONATION, ARCHIVE, etc.
    )
    print(f"Successfully connected to Exchange for {account.primary_smtp_address}")
    print(f"EWS URL: {account.protocol.ews_url}")

    # Example: List subjects of 5 most recent unread items in Inbox
    inbox = account.inbox
    print(f"\nListing up to 5 unread items in Inbox for {email}:")
    for item in inbox.filter(is_read=False).order_by('-datetime_received')[:5]:
        print(f"- Subject: {item.subject}, From: {item.sender.email_address}, Received: {item.datetime_received}")

except Exception as e:
    print(f"Could not connect or perform operation: {e}")
    print("Common issues: Incorrect credentials, firewall blocking EWS, autodiscovery failure.")
    print("If autodiscovery fails, try setting `autodiscover=False` and `ews_url` manually in Configuration.")

view raw JSON →