exchangelib

https://ecederstrand.github.io/exchangelib
Admin
exchangelib is a Python client library providing Django-style ORM access to Microsoft Exchange Web...
Tokens:814,189
Snippets:7,420
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Instance Property: server

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Gets the server configuration.

```APIDOC
## Instance Property: server

### Description
Gets the server configuration.

### Returns
(object) The server configuration.
```

--------------------------------

### Instance Property: server

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Gets the server information from the session configuration.

```APIDOC
## Instance Property: server

### Description
Returns the server details configured for the session.

### Getter
```python
@property
def server(self):
    return self.config.server
```
```

--------------------------------

### Configuration with max connections

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Example of setting the maximum number of allowed connections for a server.

```python
'max_connections' defines the max number of connections allowed for this server. This may be restricted by policies on the Exchange server.
```

--------------------------------

### Instance Property: credentials

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Gets the authentication credentials.

```APIDOC
## Instance Property: credentials

### Description
Gets the authentication credentials.

### Returns
(object) The credentials.
```

--------------------------------

### Get all supported versions

Source: https://ecederstrand.github.io/exchangelib/exchangelib/version.html

Returns a list of all supported Version objects, sorted from newest to oldest.

```python
    @classmethod
    def all_versions(cls):
        # Return all supported versions, sorted newest to oldest
        return [cls(build=build, api_version=api_version) for build, api_version, _ in VERSIONS]
```

--------------------------------

### Get Timezone Field for Field Name - Python

Source: https://ecederstrand.github.io/exchangelib/exchangelib/items/calendar_item.html

Determines the appropriate timezone field for a given field name ('start' or 'end') based on the Exchange account version. Raises a ValueError for unsupported field names.

```python
def tz_field_for_field_name(self, field_name):
    meeting_tz_field, start_tz_field, end_tz_field = CalendarItem.timezone_fields()
    if self.account.version.build < EXCHANGE_2010:
        return meeting_tz_field
    if field_name == "start":
        return start_tz_field
    if field_name == "end":
        return end_tz_field
    raise ValueError("Unsupported field_name")
```

--------------------------------

### Configuration with Credentials

Source: https://ecederstrand.github.io/exchangelib/exchangelib/configuration.html

Example of creating a Configuration object with explicit credentials. Ensure 'Credentials' and '...' are replaced with actual values.

```python
config = Configuration(credentials=Credentials('john@example.com', 'MY_SECRET'), …)
```

--------------------------------

### Create Recurring Calendar Items

Source: https://ecederstrand.github.io/exchangelib

Example of creating a recurring calendar item with weekly recurrence. It shows how to define the pattern, start date, and number of occurrences. It also demonstrates how to access and modify individual occurrences.

```python
import datetime
from exchangelib import Account, CalendarItem
from exchangelib.fields import MONDAY, WEDNESDAY
from exchangelib.recurrence import Recurrence, WeeklyPattern

a = Account(...)
start = datetime.datetime(2017, 9, 1, 11, tzinfo=a.default_timezone)
end = start + datetime.timedelta(hours=2)
master_recurrence = 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,
    ),
).save()
```

```python
# Occurrence data for the master item
i = a.calendar.get(id=master_recurrence.id)
print(i.subject, i.start, i.end)
print(i.recurrence)
print(i.first_occurrence)
print(i.last_occurrence)
for o in i.modified_occurrences:
    print(o)
for o in i.deleted_occurrences:
    print(o)
```

```python
# All occurrences expanded. The recurrence will span over 4 iterations of a
# 3-week period.
for i in a.calendar.view(start=start, end=start + datetime.timedelta(days=4 * 3 * 7)):
    print(i.subject, i.start, i.end)
```

```python
# '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:
for occurrence in a.calendar.view(
    start=start, end=start + datetime.timedelta(days=4 * 3 * 7)
):
    # Delete or update random occurrences. This will affect
    # 'modified_occurrences' and  'deleted_occurrences' of the master item.
    if occurrence.start.microsecond % 2:
        # We receive timestamps as UTC but want to write back as local timezone
        occurrence.start = occurrence.start.astimezone(a.default_timezone)
        occurrence.start += datetime.timedelta(minutes=30)
        occurrence.end = occurrence.end.astimezone(a.default_timezone)
        occurrence.end += datetime.timedelta(minutes=30)
        occurrence.subject = "My new subject"
        occurrence.save()
    else:
        occurrence.delete()
```

```python
# If you want to access a specific occurrence any you only have the master:
third_occurrence = master_recurrence.occurrence(index=3)
# Get all fields on this occurrence
third_occurrence.refresh()
# Change a field on the occurrence
third_occurrence.start += datetime.timedelta(hours=3)
# Delete occurrence
third_occurrence.save(update_fields=["start"])
```

```python
# Similarly, you can reach the master recurrence from the occurrence
master = third_occurrence.recurring_master()
master.subject = "An update"
master.save(update_fields=["subject"])
```

--------------------------------

### Initialize Configuration with Credentials

Source: https://ecederstrand.github.io/exchangelib/exchangelib/configuration.html

Instantiate the Configuration class with user credentials. Ensure the Credentials object is correctly formatted.

```python
config = Configuration(credentials=Credentials('john@example.com', 'MY_SECRET'), ...)
```

--------------------------------

### Install exchangelib with pip

Source: https://ecederstrand.github.io/exchangelib

Install the exchangelib package using pip. For additional authentication support, install with the 'kerberos', 'msal', or 'sspi' extras.

```bash
pip install exchangelib
```

```bash
pip install exchangelib[kerberos]
```

```bash
pip install exchangelib[msal]
```

```bash
pip install exchangelib[sspi]
```

```bash
pip install exchangelib[complete]
```

--------------------------------

### HTTP Adapter Configuration Example

Source: https://ecederstrand.github.io/exchangelib/exchangelib/protocol.html

Demonstrates how to configure a Requests Session with a custom HTTPAdapter, specifying retry logic. This is useful for fine-tuning connection behavior.

```python
import requests
s = requests.Session()
a = requests.adapters.HTTPAdapter(max_retries=3)
s.mount('http://', a)
```

--------------------------------

### Folder Get Operation

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/index.html

Performs a 'get' operation on the folder, typically used to retrieve a specific item. This method is a shortcut to the FolderCollection's get method.

```python
    def get(self, *args, **kwargs):
        return FolderCollection(account=self.account, folders=[self]).get(*args, **kwargs)
```

--------------------------------

### Initialize Configuration with Service Endpoint URL

Source: https://ecederstrand.github.io/exchangelib/exchangelib/configuration.html

Configure the connection by providing the full service endpoint URL. This is an alternative to specifying the server domain.

```python
config = Configuration(service_endpoint='https://mail.example.com/EWS/Exchange.asmx', ...)
```

--------------------------------

### Install exchangelib from GitHub

Source: https://ecederstrand.github.io/exchangelib

Install the latest development version of exchangelib directly from its GitHub repository.

```bash
pip install git+https://github.com/ecederstrand/exchangelib.git
```

--------------------------------

### Initialize Configuration with Server Version Hint

Source: https://ecederstrand.github.io/exchangelib/exchangelib/configuration.html

Specify the Exchange server version to avoid version detection. The Version object should be correctly instantiated.

```python
config = Configuration(version=Version(build=Build(15, 1, 2, 3)), ...)
```

--------------------------------

### Get and Set Out-of-Office (OOF) Settings

Source: https://ecederstrand.github.io/exchangelib/exchangelib

This property allows getting and setting the user's out-of-office settings. Getting OOF settings is not cached to ensure up-to-date information, while setting them uses a dedicated service call.

```python
@property
    def oof_settings(self):
        # We don't want to cache this property because then we can't easily get updates. 'threaded_cached_property'
        # supports the 'del self.oof_settings' syntax to invalidate the cache, but does not support custom setter
        # methods. Having a non-cached service call here goes against the assumption that properties are cheap, but the
        # alternative is to create get_oof_settings() and set_oof_settings(), and that's just too Java-ish for my taste.
        return GetUserOofSettings(account=self).get(
            mailbox=Mailbox(email_address=self.primary_smtp_address),
        )

    @oof_settings.setter
    def oof_settings(self, value):
        SetUserOofSettings(account=self).get(
            oof_settings=value,
            mailbox=Mailbox(email_address=self.primary_smtp_address),
        )
```

--------------------------------

### Install Test Dependencies

Source: https://ecederstrand.github.io/exchangelib

Installs the necessary dependencies for running the exchangelib test suite using pip.

```bash
# Install dependencies
python -m pip install -r test-requirements.txt
```

--------------------------------

### Folder Class Initialization and Properties

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Explains the initialization of the Folder class, its relationship with the root folder, and how to access the account and parent folder. It also covers the setter for the parent property.

```APIDOC
## class Folder

### Description
Represents a folder in the Exchange hierarchy. It inherits from BaseFolder and provides methods for managing folder properties and relationships.

### Method
`__init__(**kwargs)`: Initializes a new Folder instance. It handles the `root` and `parent` arguments to establish the folder's context within the hierarchy.

### Properties
- `account`: Returns the `Account` object associated with the folder's root.
- `root`: Returns the root folder object.
- `parent`: Returns the parent folder of the current folder. Can be set to assign a new parent.

### Methods
- `clean(version=None)`: Cleans the folder object, ensuring the root is of the correct type.
- `get_distinguished(root)`: A class method to retrieve a distinguished folder (e.g., Inbox, Sent Items) for a given root.
- `from_xml_with_root(elem, root)`: A class method to create a Folder object from XML, associating it with a root object.
```

--------------------------------

### Install Pre-commit Hooks

Source: https://ecederstrand.github.io/exchangelib

Installs and runs pre-commit hooks for the exchangelib project to ensure code quality and consistency before committing changes.

```bash
pip install pre-commit
pre-commit install
pre-commit run

```

--------------------------------

### Folder Initialization and Properties

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/base.html

Details the initialization of the Folder class, its relationship with the root and parent folders, and read-only properties.

```APIDOC
## class Folder(BaseFolder)

### Description
Represents a folder in the Exchange hierarchy. It inherits from BaseFolder and includes specific fields for permissions and effective rights.

### Initialization
```python
def __init__(self, **kwargs)
```
Initializes a Folder instance. It handles the `root` and `parent` arguments to establish the folder's position within the hierarchy and ensures consistency with the root object.

### Properties
- `permission_set` (PermissionSetField): Field URI 'folder:PermissionSet'. Supported from EXCHANGE_2007_SP1.
- `effective_rights` (EffectiveRightsField): Field URI 'folder:EffectiveRights'. Read-only. Supported from EXCHANGE_2007_SP1.
- `account` (Account): Returns the account associated with the folder's root. Returns None if the root is not set.
- `root` (RootOfHierarchy): Returns the root of the folder hierarchy this folder belongs to.
```

--------------------------------

### Install OS packages for exchangelib

Source: https://ecederstrand.github.io/exchangelib

Install necessary operating system packages for exchangelib, including dependencies for lxml and Kerberos support on Ubuntu, CentOS, and FreeBSD.

```bash
apt-get install libxml2-dev libxslt1-dev

# For Kerberos support, also install these:
apt-get install libkrb5-dev build-essential libssl-dev libffi-dev python-dev
```

```bash
# For Kerberos support, install these:
yum install gcc python-devel krb5-devel krb5-workstation python-devel
```

```bash
pkg install libxml2 libxslt
CFLAGS=-I/usr/local/include pip install lxml

# For Kerberos support, also install these:
pkg install krb5
CFLAGS=-I/usr/local/include pip install kerberos pykerberos
```

--------------------------------

### Folder Initialization and Parent Handling

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/index.html

Initializes a Folder instance, handling parent folder relationships and ensuring consistency with the root account. Raises ValueError if parent and root mismatch.

```python
class Folder(BaseFolder):
    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/folder"""

    permission_set = PermissionSetField(field_uri="folder:PermissionSet", supported_from=EXCHANGE_2007_SP1)
    effective_rights = EffectiveRightsField(
        field_uri="folder:EffectiveRights", is_read_only=True, supported_from=EXCHANGE_2007_SP1
    )

    __slots__ = ("_root",)

    def __init__(self, **kwargs):
        self._root = kwargs.pop("root", None)  # This is a pointer to the root of the folder hierarchy
        parent = kwargs.pop("parent", None)
        if parent:
            if self.root:
                if parent.root != self.root:
                    raise ValueError("'parent.root' must match 'root'")
            else:
                self._root = parent.root
            if "parent_folder_id" in kwargs and parent.id != kwargs["parent_folder_id"]:
                raise ValueError("'parent_folder_id' must match 'parent' ID")
            kwargs["parent_folder_id"] = ParentFolderId(id=parent.id, changekey=parent.changekey)
        super().__init__(**kwargs)

```

--------------------------------

### Class Method: Get Distinguished Folder

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/roots.html

A class method to get the distinguished folder for a given account. It constructs a folder object with the necessary distinguished ID and mailbox information.

```python
@classmethod
def get_distinguished(cls, account):
        """Get the distinguished folder for this folder class.

        :param account:
        :return:
        """
        return cls._get_distinguished(
            folder=cls(
                _distinguished_id=DistinguishedFolderId(
                    id=cls.DISTINGUISHED_FOLDER_ID,
                    mailbox=Mailbox(email_address=account.primary_smtp_address),
                ),
                account=account,
            )
        )
```

--------------------------------

### Get Inbox Rules Service - Get Payload Method

Source: https://ecederstrand.github.io/exchangelib/exchangelib/services/inbox_rules.html

The `get_payload` method for the `GetInboxRules` service. It constructs the XML payload required for the GetInboxRules operation, including the mailbox SMTP address.

```python
def get_payload(self, mailbox):
    payload = create_element(f"m:{self.SERVICE_NAME}")
    add_xml_child(payload, "m:MailboxSmtpAddress", mailbox)
    return payload
```

--------------------------------

### Initialize Configuration with Server Domain

Source: https://ecederstrand.github.io/exchangelib/exchangelib/configuration.html

Configure the connection using only the server's domain name. The service endpoint URL will be automatically constructed.

```python
config = Configuration(server='example.com', ...)
```

--------------------------------

### Occurrence Class

Source: https://ecederstrand.github.io/exchangelib/exchangelib/recurrence.html

Represents a specific occurrence of a recurring calendar item. It stores the modified start and end times, as well as the original start time, allowing for tracking of individual instances within a series.

```APIDOC
## Class Occurrence

### Description
Represents a single occurrence of a recurring calendar item, potentially with modified start and end times. It also stores the original start time for reference.

### MSDN Reference
https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/occurrence

### Fields
- **_id** (IdElementField): The ItemId of the occurrence.
- **start** (DateTimeField): The modified start time of the occurrence.
- **end** (DateTimeField): The modified end time of the occurrence.
- **original_start** (DateTimeField): The original start time of the occurrence.

### Inheritance
- Inherits from `IdChangeKeyMixIn`.

### Subclasses
- `FirstOccurrence`
- `LastOccurrence`
```

--------------------------------

### Initialize BaseItem with Account and Folder

Source: https://ecederstrand.github.io/exchangelib/exchangelib/items/base.html

Initializes a BaseItem instance, optionally accepting 'account' and 'folder' keyword arguments. Ensures type correctness and handles account propagation from the folder if not explicitly provided.

```python
class BaseItem(RegisterMixIn, metaclass=EWSMeta):
    """Base class for all other classes that implement EWS items."""

    ID_ELEMENT_CLS = ItemId
    _id = IdElementField(field_uri="item:ItemId", value_cls=ID_ELEMENT_CLS)

    __slots__ = "account", "folder"

    def __init__(self, **kwargs):
        """Pick out optional 'account' and 'folder' kwargs, and pass the rest to the parent class.

        :param kwargs:
            'account' is optional but allows calling 'send()' and 'delete()'
            'folder' is optional but allows calling 'save()'. If 'folder' has an account, and 'account' is not set,
                we use folder.account.
        """
        from ..account import Account
        from ..folders import BaseFolder

        self.account = kwargs.pop("account", None)
        if self.account is not None and not isinstance(self.account, Account):
            raise InvalidTypeError("account", self.account, Account)
        self.folder = kwargs.pop("folder", None)
        if self.folder is not None:
            if not isinstance(self.folder, BaseFolder):
                raise InvalidTypeError("folder", self.folder, BaseFolder)
            if self.folder.account is not None:
                if self.account is not None:
                    # Make sure the account from kwargs matches the folder account
                    if self.account != self.folder.account:
                        raise ValueError("'account' does not match 'folder.account'")
                self.account = self.folder.account
        super().__init__(**kwargs)
```

--------------------------------

### Create user configuration

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/base.html

Creates a new user configuration with specified name, dictionary, XML, or binary data.

```python
from ..services import CreateUserConfiguration

user_configuration = UserConfiguration(
    user_configuration_name=UserConfigurationName(name=name, folder=self),
    dictionary=dictionary,
    xml_data=xml_data,
    binary_data=binary_data,
)
return CreateUserConfiguration(account=self.account).get(user_configuration=user_configuration)
```

--------------------------------

### Handle push notifications (Flask example)

Source: https://ecederstrand.github.io/exchangelib

Example of a Flask application implementing a callback URL to handle push notifications from the Exchange server. It parses the `SendNotification` XML document and can respond with an acknowledgement or an unsubscribe payload.

```APIDOC
## Handle push notifications (Flask example)

### Description
Example of a Flask application implementing a callback URL to handle push notifications from the Exchange server. It parses the `SendNotification` XML document and can respond with an acknowledgement or an unsubscribe payload.

### Method
```python
from exchangelib.services import SendNotification
from flask import Flask, request

app = Flask(__name__)


@app.route("/callback_url", methods=["POST"])
def notify_me():
    ws = SendNotification(protocol=None)
    for notification in ws.parse(request.data):
        # ws.parse() returns Notification objects
        pass
    data = ws.ok_payload()
    # Or, if you want to end the subscription:
    data = ws.unsubscribe_payload()

    return data, 201, {"Content-Type": "text/xml; charset=utf-8"}
```
```

--------------------------------

### Generate Get Items Payload

Source: https://ecederstrand.github.io/exchangelib/exchangelib/services/index.html

This method constructs the XML payload required for the 'Get Items' operation in the Exchange Web Services API. It includes configurations for item shape, view type, restrictions, sorting, and folder identification.

```APIDOC
## get_payload

### Description
Constructs the XML payload for the Get Items operation.

### Method Signature
def get_payload(
    self,
    folders,
    additional_fields,
    restriction,
    order_fields,
    query_string,
    shape,
    depth,
    calendar_view,
    page_size,
    offset=0
)

### Parameters
- **folders**: The folders to retrieve items from.
- **additional_fields**: A list of additional fields to include in the item response.
- **restriction**: A Restriction object to filter the items.
- **order_fields**: A list of fields to sort the items by.
- **query_string**: A QueryString object for advanced querying.
- **shape**: The shape of the item response (e.g., 'Default', 'IdOnly').
- **depth**: The traversal depth for searching items in subfolders.
- **calendar_view**: A CalendarView object for calendar-specific views.
- **page_size**: The maximum number of items to return per page.
- **offset**: The offset from the beginning of the item collection.

### Returns
The constructed XML payload as an element.
```

--------------------------------

### Create user configuration

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/index.html

Creates a new user configuration with specified name, dictionary, XML, or binary data.

```python
@require_id
def create_user_configuration(self, name, dictionary=None, xml_data=None, binary_data=None):
        from ..services import CreateUserConfiguration

        user_configuration = UserConfiguration(
            user_configuration_name=UserConfigurationName(name=name, folder=self),
            dictionary=dictionary,
            xml_data=xml_data,
            binary_data=binary_data,
        )
        return CreateUserConfiguration(account=self.account).get(user_configuration=user_configuration)
```

--------------------------------

### Initialize Account with Configuration

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Initializes an account using a provided configuration object. Raises an AttributeError if no config is given for non-autodiscover accounts.

```python
else:
                if not config:
                    raise AttributeError("non-autodiscover requires a config")
                self.ad_response = None
                self.protocol = Protocol(config=config)
```

--------------------------------

### Create User Configuration

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/index.html

Creates a new user configuration with provided name, dictionary, XML, or binary data. Requires the folder to have an ID.

```python
self.create_user_configuration(name, dictionary=dictionary, xml_data=xml_data, binary_data=binary_data)
```

--------------------------------

### domain

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Get the domain from the primary SMTP address.

```APIDOC
## domain

### Description
Get the domain from the primary SMTP address.

### Method
GET

### Endpoint
/domain

### Response
#### Success Response (200)
- **domain** (string) - The domain name.
```

--------------------------------

### Hint Authentication Type and Server Version

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Provide hints for authentication type (e.g., NTLM) and server version to optimize connection setup.

```python
config = Configuration(auth_type=NTLM, ...)
```

```python
config = Configuration(version=Version(build=Build(15, 1, 2, 3)), ...)
```

--------------------------------

### Contact Initialization with Optional Parameters

Source: https://ecederstrand.github.io/exchangelib/exchangelib/items/contact.html

Initializes a Contact object, accepting optional 'account' and 'folder' keyword arguments. 'account' enables sending and deleting, while 'folder' enables saving. If 'folder' is provided without an 'account', it inherits the account from the folder.

```python
:param kwargs: 'account' is optional but allows calling 'send()' and 'delete()' 'folder' is optional but allows calling 'save()'. If 'folder' has an account, and 'account' is not set, we use folder.account.
```

--------------------------------

### Get Session

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Retrieves an available session from the pool.

```python
def get_session(self):
    
```

--------------------------------

### EWSDateTime.utcnow()

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Gets the current UTC time as an EWSDateTime object.

```APIDOC
## EWSDateTime.utcnow()

### Description
Gets the current UTC time as a timezone-aware EWSDateTime object.

### Method
```python
@classmethod
def utcnow(cls):
    t = super().utcnow()
    if isinstance(t, cls):
        return t
```
```

--------------------------------

### Instance Property: session_pool_size

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Gets the size of the session pool.

```APIDOC
## Instance Property: session_pool_size

### Description
Gets the size of the session pool.

### Returns
(int) The session pool size.
```

--------------------------------

### Instance Methods and Properties

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Documentation for instance methods like `copy`, `all_versions`, and properties like `fullname`, which are part of the exchangelib API surface.

```APIDOC
## Instance Methods and Properties

### `copy()`

#### Description
Creates a copy of the current `ServerVersionInfo` instance.

#### Method
Instance method.

#### Parameters
None.

#### Returns
A new `ServerVersionInfo` instance with the same build and API version.

### `all_versions()`

#### Description
Returns a list of all supported `ServerVersionInfo` instances, sorted from newest to oldest.

#### Method
Class method.

#### Parameters
None.

#### Returns
A list of `ServerVersionInfo` objects.

### `fullname` (property)

#### Description
Returns the full name of the Exchange server version based on the build and API version.

#### Method
Property accessor.

#### Parameters
None.

#### Returns
A string representing the full Exchange server version name, or 'UNKNOWN' if not found.
```

--------------------------------

### Instance Property: service_endpoint

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Gets the service endpoint configuration.

```APIDOC
## Instance Property: service_endpoint

### Description
Gets the service endpoint configuration.

### Returns
(object) The service endpoint configuration.
```

--------------------------------

### Contact Item Initialization with Optional Args

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Illustrates how optional 'account' and 'folder' keyword arguments are handled during the initialization of a Contact item. These arguments affect the availability of methods like 'send()', 'delete()', and 'save()'.

```python
# Pick out optional 'account' and 'folder' kwargs, and pass the rest to the parent class.
# :param kwargs: 'account' is optional but allows calling 'send()' and 'delete()' 'folder' is optional but allows calling 'save()'. If 'folder' has an account, and 'account' is not set, we use folder.account.
```

--------------------------------

### Create User Configuration

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/base.html

Creates a new user configuration with the specified name and optional dictionary, XML, or binary data.

```python
from ..services import CreateUserConfiguration

        user_configuration = UserConfiguration(
            user_configuration_name=UserConfigurationName(name=name, folder=self),
            dictionary=dictionary,
            xml_data=xml_data,
            binary_data=binary_data,
        )
        return CreateUserConfiguration(account=self.account).get(user_configuration=user_configuration)
```

--------------------------------

### Instance Property: retry_policy

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Gets the retry policy configuration.

```APIDOC
## Instance Property: retry_policy

### Description
Gets the retry policy configuration.

### Returns
(object) The retry policy.
```

--------------------------------

### Initialize Configuration with Authentication Type Hint

Source: https://ecederstrand.github.io/exchangelib/exchangelib/configuration.html

Provide a hint for the authentication type to bypass the automatic detection process. Supported types include NTLM and others defined in AUTH_TYPE_MAP.

```python
config = Configuration(auth_type=NTLM, ...)
```

--------------------------------

### Account Domain

Source: https://ecederstrand.github.io/exchangelib/exchangelib/account.html

Get the domain of the primary SMTP address.

```APIDOC
## Account Domain

### Description
Retrieves the domain name associated with the account's primary SMTP address.

### Property
- `domain`: Returns the domain string.

### Example
```python
domain_name = account.domain
```
```

--------------------------------

### FolderQuerySet Initialization

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/queryset.html

Initializes a FolderQuerySet with a FolderCollection. It sets up default query parameters and field restrictions.

```python
class FolderQuerySet:
    """A QuerySet-like class for finding sub-folders of a folder collection."""

    def __init__(self, folder_collection):
        from .collections import FolderCollection

        if not isinstance(folder_collection, FolderCollection):
            raise InvalidTypeError("folder_collection", folder_collection, FolderCollection)
        self.folder_collection = folder_collection
        self.q = Q()  # Default to no restrictions
        self.only_fields = None
        self._depth = None
```

--------------------------------

### Get timezone information

Source: https://ecederstrand.github.io/exchangelib

Retrieve timezone information from the Exchange server.

```APIDOC
## Get timezone information

### Description
Retrieve timezone information from the Exchange server.

### Method
```python
a.protocol.get_timezones()
```
```

--------------------------------

### Instance Property: auth_type

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Gets the authentication type, autodetecting if necessary.

```APIDOC
## Instance Property: auth_type

### Description
Gets the authentication type, autodetecting if necessary.

### Returns
(str) The authentication type.
```

--------------------------------

### Item Initialization

Source: https://ecederstrand.github.io/exchangelib/exchangelib/items/item.html

Details the initialization process for the Item class, including handling of attachments.

```APIDOC
## Item Initialization

Initializes a new Item instance.

### Method

`__init__(**kwargs)`

### Parameters

- **kwargs**: dict - Arbitrary keyword arguments to initialize item attributes.

### Behavior

- Calls the parent class constructor.
- If attachments are provided, it ensures their `parent_item` attribute is set to the current item and attaches them.
```

--------------------------------

### Get IO Stream Position

Source: https://ecederstrand.github.io/exchangelib/exchangelib/util.html

Returns the current stream position.

```python
def tell(self):
    return self._tell
```

--------------------------------

### Get User-Friendly Version String

Source: https://ecederstrand.github.io/exchangelib/exchangelib/version.html

Returns a user-friendly string representation of the version, including build, API version, and full name.

```python
def __str__(self):
        return f"Build={self.build}, API={self.api_version}, Fullname={self.fullname}"
```

--------------------------------

### Initialize BaseItem with Account and Folder

Source: https://ecederstrand.github.io/exchangelib/exchangelib/items/base.html

Initializes a BaseItem instance, optionally accepting 'account' and 'folder' keyword arguments. It performs type checking and ensures consistency between the provided account and folder accounts.

```python
class BaseItem(RegisterMixIn, metaclass=EWSMeta):
    """Base class for all other classes that implement EWS items."""

    ID_ELEMENT_CLS = ItemId
    _id = IdElementField(field_uri="item:ItemId", value_cls=ID_ELEMENT_CLS)

    __slots__ = "account", "folder"

    def __init__(self, **kwargs):
        """Pick out optional 'account' and 'folder' kwargs, and pass the rest to the parent class.

        :param kwargs:
            'account' is optional but allows calling 'send()' and 'delete()'
            'folder' is optional but allows calling 'save()'. If 'folder' has an account, and 'account' is not set,
                we use folder.account.
        """
        from ..account import Account
        from ..folders import BaseFolder

        self.account = kwargs.pop("account", None)
        if self.account is not None and not isinstance(self.account, Account):
            raise InvalidTypeError("account", self.account, Account)
        self.folder = kwargs.pop("folder", None)
        if self.folder is not None:
            if not isinstance(self.folder, BaseFolder):
                raise InvalidTypeError("folder", self.folder, BaseFolder)
            if self.folder.account is not None:
                if self.account is not None:
                    # Make sure the account from kwargs matches the folder account
                    if self.account != self.folder.account:
                        raise ValueError("'account' does not match 'folder.account'")
                self.account = self.folder.account
        super().__init__(**kwargs)

    @classmethod
    def from_xml(cls, elem, account):
        item = super().from_xml(elem=elem, account=account)
        item.account = account
        return item

```

--------------------------------

### Instance Property: auth_type

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Gets the authentication type, autodetecting if necessary.

```APIDOC
## Instance Property: auth_type

### Description
Returns the authentication type configured for the session. If not explicitly set, it attempts to autodetect the authentication type.

### Getter
```python
@property
def auth_type(self):
    # Autodetect authentication type if necessary
    if self.config.auth_type is None:
        self.config.auth_type = self.get_auth_type()
    return self.config.auth_type
```
```

--------------------------------

### BaseItem Initialization

Source: https://ecederstrand.github.io/exchangelib/exchangelib/items/base.html

Initializes a BaseItem instance, optionally accepting 'account' and 'folder' keyword arguments. It validates the types of 'account' and 'folder' and ensures consistency if both are provided.

```APIDOC
class BaseItem(**kwargs)

    """Base class for all other classes that implement EWS items."""

    def __init__(self, **kwargs)
        """Pick out optional 'account' and 'folder' kwargs, and pass the rest to the parent class.

        :param kwargs:
            'account' is optional but allows calling 'send()' and 'delete()'
            'folder' is optional but allows calling 'save()'. If 'folder' has an account, and 'account' is not set,
                we use folder.account.
        """
        # ... implementation details ...

```

--------------------------------

### Get FreeBusyView from Container

Source: https://ecederstrand.github.io/exchangelib/exchangelib/services/index.html

Extracts the FreeBusyView element from a given response container.

```python
@classmethod
    def _get_elements_in_container(cls, container):
        return [container.find(f"{{{MNS}}}FreeBusyView")]
```

--------------------------------

### Configure Server and Service Endpoint

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Set the server hostname or the full service endpoint URL when initializing the Configuration.

```python
config = Configuration(server='example.com', ...)
```

```python
config = Configuration(service_endpoint='https://mail.example.com/EWS/Exchange.asmx', ...)
```

--------------------------------

### Initialize and Parse Q Object Arguments

Source: https://ecederstrand.github.io/exchangelib/exchangelib/restriction.html

Initializes a Q object, handling initialization from a query string or parsing positional and keyword arguments to build filter conditions.

```python
    __slots__ = "conn_type", "field_path", "op", "value", "children", "query_string"

    def __init__(self, *args, **kwargs):
        self.conn_type = kwargs.pop("conn_type", self.AND)

        self.field_path = None  # Name of the field we want to filter on
        self.op = None
        self.value = None
        self.query_string = None

        # Parsing of args and kwargs may require child elements
        self.children = []

        # Check for query string as the only argument
        if not kwargs and len(args) == 1 and isinstance(args[0], str):
            self.query_string = args[0]
            args = ()

        # Parse args which must now be Q objects
        for q in args:
            if not isinstance(q, self.__class__):
                raise TypeError(f"Non-keyword arg {q!r} must be of type {Q}")
        self.children.extend(args)

        # Parse keyword args and extract the filter
        is_single_kwarg = not args and len(kwargs) == 1
        for key, value in kwargs.items():
            self.children.extend(self._get_children_from_kwarg(key=key, value=value, is_single_kwarg=is_single_kwarg))

        # Simplify this object
        self.reduce()

        # Final sanity check
        self._check_integrity()
```

--------------------------------

### Get Timezone Fields

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Returns a tuple of all fields in the class that are instances of `TimeZoneField`.

```python
@classmethod
    def timezone_fields(cls):
        return tuple(f for f in cls.FIELDS if isinstance(f, TimeZoneField))
```

--------------------------------

### Configuration Class

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Initializes a Configuration object with credentials, server details, authentication type, version, retry policy, and maximum connections.

```APIDOC
## Configuration Class

### Description
Contains information needed to create an authenticated connection to an EWS endpoint.

### Parameters
- **credentials** (BaseCredentials, optional): Credentials for authentication.
- **server** (string, optional): The domain name of the Exchange server.
- **service_endpoint** (string, optional): The full URL of the EWS service endpoint.
- **auth_type** (AuthType, optional): The authentication type to use (e.g., NTLM, OAUTH2).
- **version** (Version, optional): The Exchange server version.
- **retry_policy** (RetryPolicy, optional): The policy for retrying failed connections.
- **max_connections** (int, optional): The maximum number of allowed connections to the server.

### Example
```python
from exchangelib import Configuration, Credentials, NTLM

# Example using server domain
config1 = Configuration(credentials=Credentials('john@example.com', 'MY_SECRET'), server='example.com')

# Example using full service endpoint
config2 = Configuration(credentials=Credentials('jane@example.com', 'ANOTHER_SECRET'), service_endpoint='https://mail.example.com/EWS/Exchange.asmx')

# Example specifying auth type and version
from exchangelib import Version
config3 = Configuration(credentials=Credentials('user@example.com', 'password'), server='exchange.example.com', auth_type=NTLM, version=Version(build=15)) 
```

### Attributes
- **credentials**: Returns the configured credentials.
- **service_endpoint**: The full EWS service endpoint URL.
- **auth_type**: The authentication type used.
- **version**: The Exchange server version.
- **retry_policy**: The retry policy for connection failures.
- **max_connections**: The maximum number of concurrent connections.
- **server**: The domain name of the Exchange server (derived from service_endpoint if not provided).
```

--------------------------------

### ErrorInvalidGetSharingFolderRequest

Source: https://ecederstrand.github.io/exchangelib/exchangelib/errors.html

Raised when a request to get a sharing folder is invalid. Inherits from ResponseMessageError.

```python
class ErrorInvalidGetSharingFolderRequest(ResponseMessageError):
    pass
```

--------------------------------

### Instance Property: session_pool_size

Source: https://ecederstrand.github.io/exchangelib/exchangelib/index.html

Gets the size of the session's connection pool.

```APIDOC
## Instance Property: session_pool_size

### Description
Returns the configured size of the connection pool for the session.

### Getter
```python
@property
def session_pool_size(self):
    return self._session_pool_size
```
```

--------------------------------

### Class Method: From XML

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/roots.html

Creates a folder instance from an XML element. It extracts necessary arguments from the XML and then instantiates the folder class.

```python
@classmethod
def from_xml(cls, elem, account):
        kwargs = cls._kwargs_from_elem(elem=elem, account=account)
        cls._clear(elem)
        return cls(account=account, **kwargs)
```

--------------------------------

### Get Timezone Fields

Source: https://ecederstrand.github.io/exchangelib/exchangelib/items/index.html

Returns a tuple of all fields in the class that are instances of `TimeZoneField`.

```python
@classmethod
def timezone_fields(cls):
        return tuple(f for f in cls.FIELDS if isinstance(f, TimeZoneField))
```

--------------------------------

### Initialize Account with Impersonation Access

Source: https://ecederstrand.github.io/exchangelib

Instantiate an Account object with IMPERSONATION access type. This is used when your credentials have been granted impersonation rights to the target account.

```python
# If your credentials have been given impersonation access to the target
# account, set a different 'access_type':
johns_account = Account(
    primary_smtp_address="john@example.com",
    credentials=credentials,
    autodiscover=True,
    access_type=IMPERSONATION,
)
```

--------------------------------

### Get all folders

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/queryset.html

Returns a copy of the queryset. Used internally for method chaining.

```python
def all(self):
    "" " " "
    new_qs = self._copy_self()
    return new_qs
```

--------------------------------

### Initialize Exchange Credentials

Source: https://ecederstrand.github.io/exchangelib

Set up authentication credentials for connecting to an Exchange server. This is a prerequisite for creating an Account object.

```python
from exchangelib import Credentials

credentials = Credentials(username="myuser@example.com", password="topsecret")
```

--------------------------------

### Autodiscover Step 3: Initial URL Discovery

Source: https://ecederstrand.github.io/exchangelib/exchangelib/autodiscover/discovery.html

Handles the initial attempt to discover server settings by making an unauthenticated GET request to a given URL. It processes potential redirects (301, 302) and validates the redirect URL before proceeding.

```python
log.info("Step 3: Trying autodiscover on %r with email %r", url, self.email)
try:
    _, r = self._get_unauthenticated_response(url=url, method="get")
except TransportError:
    pass
else:
    if r.status_code in (301, 302) and "location" in r.headers:
        redirect_url = get_redirect_url(r)
        if self._redirect_url_is_valid(url=redirect_url):
            is_valid_response, ad = self._attempt_response(url=redirect_url)
            if is_valid_response:
                return self._step_5(ad=ad)
            log.debug("Got invalid response")
            return self._step_4(hostname=hostname)
        log.debug("Got invalid redirect URL")
        return self._step_4(hostname=hostname)
log.debug("Got no redirect URL")
return self._step_4(hostname=hostname)
```

--------------------------------

### Out of Office (OOF) Settings

Source: https://ecederstrand.github.io/exchangelib/exchangelib/account.html

Get and set the Out of Office (OOF) settings for the account.

```APIDOC
## Out of Office Settings

### Description
Manages the Out of Office (OOF) settings for the account. You can retrieve the current OOF settings and update them.

### Properties
- `oof_settings`: 
  - **Getter**: Retrieves the current OOF settings.
  - **Setter**: Updates the OOF settings with the provided value.

### Example
```python
# Get OOF settings
oon_settings = account.oof_settings

# Set OOF settings
from exchangelib.protocol import GetUserOofSettings, SetUserOofSettings
from exchangelib.folders import Mailbox

new_oof_settings = OofSettings(state='Enabled', external_auto_reply_message='I am out of office.')
account.oof_settings = new_oof_settings
```
```

--------------------------------

### Create User Configuration

Source: https://ecederstrand.github.io/exchangelib/exchangelib/folders/base.html

Creates a new user configuration for the folder. Supports providing data as a dictionary, XML, or binary data.

```python
@require_id
    def create_user_configuration(self, name, dictionary=None, xml_data=None, binary_data=None):
        from ..services import CreateUserConfiguration

        user_configuration = UserConfiguration(
            user_configuration_name=UserConfigurationName(name=name, folder=self),
            dictionary=dictionary,
            xml_data=xml_data,
            binary_data=binary_data,
        )
        return CreateUserConfiguration(account=self.account).get(user_configuration=user_configuration)
```

--------------------------------

### RetryPolicy.back_off_until

Source: https://ecederstrand.github.io/exchangelib/exchangelib

Get the back-off value as a datetime. Resets the current back-off value if it has expired.

```APIDOC
## back_off_until

### Description
Return the back off value as a datetime. Reset the current back off value if it has expired.

### Method
GET

### Endpoint
N/A (Instance variable property)

### Parameters
None

### Response
#### Success Response (200)
- **back_off_until** (datetime) - The datetime until which the back off is active, or None if not backing off.

### Response Example
```json
{
  "back_off_until": "2023-10-27T10:00:00"
}
```
```

--------------------------------

### Configure Certificate Based Authentication (CBA)

Source: https://ecederstrand.github.io/exchangelib

Set up Certificate Based Authentication by specifying the client certificate file and configuring the HTTP adapter. Requires a client certificate.

```python
from exchangelib import Configuration, BaseProtocol, CBA, TLSClientAuth

TLSClientAuth.cert_file = "/path/to/client.pem"
BaseProtocol.HTTP_ADAPTER_CLS = TLSClientAuth
config = Configuration(auth_type=CBA)
```

--------------------------------

### Get room lists

Source: https://ecederstrand.github.io/exchangelib

Retrieve a list of all room lists defined on the Exchange server.

```APIDOC
## Get room lists

### Description
Retrieve a list of all room lists defined on the Exchange server.

### Method
```python
a.protocol.get_roomlists()
```
```

--------------------------------

### Create a Copy of Version Instance

Source: https://ecederstrand.github.io/exchangelib/exchangelib/version.html

Returns a new instance of the same class with the same build and API version.

```python
def copy(self):
        return self.__class__(build=self.build, api_version=self.api_version)
```

--------------------------------

### SyncFolderHierarchy

Source: https://ecederstrand.github.io/exchangelib/exchangelib/services/index.html

Synchronizes the folder hierarchy of a mailbox. This is used to get the latest folder structure.

```APIDOC
## SyncFolderHierarchy

### Description
Synchronizes the folder hierarchy of a mailbox.

### Method
Not specified, likely a service call.

### Endpoint
Not specified.

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```
Tokens:
Raw