CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-exchangelib

Client for Microsoft Exchange Web Services (EWS) providing Django-style ORM interface for Exchange mailboxes.

—

Pending
Overview
Eval results
Files

account-auth.mddocs/

Account and Authentication

Core functionality for connecting to Exchange servers with support for multiple authentication methods, autodiscovery, and account configuration. Includes support for both on-premise Exchange and Office365.

Capabilities

Account Creation and Configuration

The Account class is the main entry point for all Exchange operations, representing a user's mailbox and providing access to folders and services.

class Account:
    def __init__(
        self,
        primary_smtp_address: str,
        credentials: Credentials,
        autodiscover: bool = True,
        config: Configuration = None,
        access_type: str = DELEGATE,
        default_timezone: EWSTimeZone = None,
        locale: str = None
    ):
        """
        Create an Exchange account connection.
        
        Parameters:
        - primary_smtp_address: The primary SMTP address of the account
        - credentials: Authentication credentials
        - autodiscover: Whether to use autodiscovery to find server settings
        - config: Manual configuration (if autodiscover=False)
        - access_type: DELEGATE or IMPERSONATION
        - default_timezone: Default timezone for datetime operations
        - locale: Locale for server communication
        """
    
    # Folder properties
    inbox: Folder
    outbox: Folder
    sent: Folder
    drafts: Folder
    deleted_items: Folder
    calendar: Folder
    contacts: Folder
    tasks: Folder
    notes: Folder
    journal: Folder
    
    # Bulk operations
    def bulk_create(self, folder, items, message_disposition='SaveOnly', send_meeting_invitations='SendToNone', chunk_size=None):
        """Create multiple items in a folder."""
    
    def bulk_update(self, items, conflict_resolution='AutoResolve', message_disposition='SaveOnly', send_meeting_invitations_or_cancellations='SendToNone', chunk_size=None):
        """Update multiple items."""
    
    def bulk_delete(self, ids, delete_type='MoveToDeletedItems', send_meeting_cancellations='SendToNone', affected_task_occurrences='AllOccurrences', chunk_size=None):
        """Delete multiple items."""
    
    def export(self, items):
        """Export items to their native EWS format."""
    
    def upload(self, data, folder):
        """Upload items from their native EWS format."""

Basic Authentication

Simple username/password authentication for basic Exchange setups.

class Credentials:
    def __init__(self, username: str, password: str):
        """
        Basic username/password credentials.
        
        Parameters:
        - username: Username (often email address)
        - password: Password
        """

Usage example:

from exchangelib import Account, Credentials, DELEGATE

credentials = Credentials(username='user@company.com', password='password')
account = Account(
    primary_smtp_address='user@company.com',
    credentials=credentials,
    autodiscover=True,
    access_type=DELEGATE
)

OAuth2 Authentication

Modern OAuth2 authentication for secure, token-based authentication with Exchange Online and Office365.

class OAuth2Credentials:
    def __init__(
        self,
        client_id: str,
        client_secret: str,
        tenant_id: str,
        identity: Identity = None
    ):
        """
        OAuth2 client credentials flow.
        
        Parameters:
        - client_id: Azure AD application client ID
        - client_secret: Azure AD application client secret
        - tenant_id: Azure AD tenant ID
        - identity: User identity for impersonation
        """

class OAuth2AuthorizationCodeCredentials:
    def __init__(
        self,
        client_id: str,
        client_secret: str,
        tenant_id: str,
        authorization_code: str,
        redirect_uri: str
    ):
        """
        OAuth2 authorization code flow.
        
        Parameters:
        - client_id: Azure AD application client ID
        - client_secret: Azure AD application client secret  
        - tenant_id: Azure AD tenant ID
        - authorization_code: Authorization code from OAuth flow
        - redirect_uri: Redirect URI used in OAuth flow
        """

class OAuth2LegacyCredentials:
    def __init__(self, username: str, password: str):
        """
        Legacy OAuth2 credentials using username/password.
        
        Parameters:
        - username: Username (email address)
        - password: Password
        """

Usage example:

from exchangelib import Account, OAuth2Credentials, DELEGATE

credentials = OAuth2Credentials(
    client_id='your-client-id',
    client_secret='your-client-secret',
    tenant_id='your-tenant-id'
)

account = Account(
    primary_smtp_address='user@company.com',
    credentials=credentials,
    autodiscover=True,
    access_type=DELEGATE
)

Manual Configuration

Manual server configuration when autodiscovery is not available or desired.

class Configuration:
    def __init__(
        self,
        server: str,
        credentials: Credentials,
        version: Version = None,
        auth_type: str = None,
        retry_policy: BaseProtocol = None
    ):
        """
        Manual Exchange server configuration.
        
        Parameters:
        - server: Exchange server hostname or URL
        - credentials: Authentication credentials
        - version: Exchange server version
        - auth_type: Authentication type (NTLM, BASIC, etc.)
        - retry_policy: Retry policy for failed requests
        """

class O365InteractiveConfiguration:
    def __init__(self, username: str):
        """
        Interactive OAuth2 configuration for Office365.
        
        Parameters:
        - username: Username for interactive authentication
        """

Usage example:

from exchangelib import Account, Credentials, Configuration, Version, Build

credentials = Credentials(username='user@company.com', password='password')
config = Configuration(
    server='mail.company.com',
    credentials=credentials,
    version=Version(build=Build(15, 0, 1236, 3))
)

account = Account(
    primary_smtp_address='user@company.com',
    config=config,
    autodiscover=False
)

Identity and Impersonation

User identity management and impersonation capabilities for accessing other users' mailboxes.

class Identity:
    def __init__(
        self,
        primary_smtp_address: str = None,
        name: str = None,
        sid: str = None,
        upn: str = None
    ):
        """
        User identity for impersonation.
        
        Parameters:
        - primary_smtp_address: Primary SMTP address
        - name: Display name
        - sid: Security identifier
        - upn: User principal name
        """

# Constants for access types
DELEGATE: str = 'Delegate'
IMPERSONATION: str = 'Impersonation'

Usage example:

from exchangelib import Account, Credentials, Identity, IMPERSONATION

# Service account credentials
credentials = Credentials(username='service@company.com', password='password')

# Identity of user to impersonate
identity = Identity(primary_smtp_address='target@company.com')

account = Account(
    primary_smtp_address='target@company.com',
    credentials=credentials,
    access_type=IMPERSONATION,
    identity=identity
)

Connection Management

Utilities for managing connections and cleaning up resources.

def close_connections():
    """
    Close all open connections to Exchange servers.
    Should be called when finished with exchangelib operations.
    """

def discover(email: str, credentials: Credentials = None) -> Account:
    """
    Autodiscover Exchange settings for an email address.
    
    Parameters:
    - email: Email address to discover settings for
    - credentials: Optional credentials for authentication
    
    Returns:
    Account object with discovered settings
    """

Usage example:

from exchangelib import discover, close_connections, Credentials

# Discover account settings
credentials = Credentials(username='user@company.com', password='password')
account = discover(email='user@company.com', credentials=credentials)

# Use the account...

# Clean up connections when done
close_connections()

Authentication Types

exchangelib supports multiple authentication methods:

  • BASIC: Basic HTTP authentication
  • NTLM: Windows NTLM authentication
  • DIGEST: HTTP Digest authentication
  • OAUTH2: OAuth2 token-based authentication
  • GSSAPI: Kerberos/GSSAPI authentication (with optional dependency)
  • SSPI: Windows SSPI authentication (Windows only)
  • CBA: Certificate-based authentication
# Authentication type constants
BASIC: str
NTLM: str
DIGEST: str
OAUTH2: str
GSSAPI: str
SSPI: str
CBA: str

Install with Tessl CLI

npx tessl i tessl/pypi-exchangelib

docs

account-auth.md

advanced.md

attachments.md

calendar.md

contacts.md

datetime.md

folders.md

index.md

messages.md

search.md

tasks.md

tile.json