0
# Account and Authentication
1

2
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.
3

4
## Capabilities
5

6
### Account Creation and Configuration
7

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

10
```python { .api }
11
class Account:
12
    def __init__(
13
        self,
14
        primary_smtp_address: str,
15
        credentials: Credentials,
16
        autodiscover: bool = True,
17
        config: Configuration = None,
18
        access_type: str = DELEGATE,
19
        default_timezone: EWSTimeZone = None,
20
        locale: str = None
21
    ):
22
        """
23
        Create an Exchange account connection.
24
        
25
        Parameters:
26
        - primary_smtp_address: The primary SMTP address of the account
27
        - credentials: Authentication credentials
28
        - autodiscover: Whether to use autodiscovery to find server settings
29
        - config: Manual configuration (if autodiscover=False)
30
        - access_type: DELEGATE or IMPERSONATION
31
        - default_timezone: Default timezone for datetime operations
32
        - locale: Locale for server communication
33
        """
34
    
35
    # Folder properties
36
    inbox: Folder
37
    outbox: Folder
38
    sent: Folder
39
    drafts: Folder
40
    deleted_items: Folder
41
    calendar: Folder
42
    contacts: Folder
43
    tasks: Folder
44
    notes: Folder
45
    journal: Folder
46
    
47
    # Bulk operations
48
    def bulk_create(self, folder, items, message_disposition='SaveOnly', send_meeting_invitations='SendToNone', chunk_size=None):
49
        """Create multiple items in a folder."""
50
    
51
    def bulk_update(self, items, conflict_resolution='AutoResolve', message_disposition='SaveOnly', send_meeting_invitations_or_cancellations='SendToNone', chunk_size=None):
52
        """Update multiple items."""
53
    
54
    def bulk_delete(self, ids, delete_type='MoveToDeletedItems', send_meeting_cancellations='SendToNone', affected_task_occurrences='AllOccurrences', chunk_size=None):
55
        """Delete multiple items."""
56
    
57
    def export(self, items):
58
        """Export items to their native EWS format."""
59
    
60
    def upload(self, data, folder):
61
        """Upload items from their native EWS format."""
62
```
63

64
### Basic Authentication
65

66
Simple username/password authentication for basic Exchange setups.
67

68
```python { .api }
69
class Credentials:
70
    def __init__(self, username: str, password: str):
71
        """
72
        Basic username/password credentials.
73
        
74
        Parameters:
75
        - username: Username (often email address)
76
        - password: Password
77
        """
78
```
79

80
Usage example:
81

82
```python
83
from exchangelib import Account, Credentials, DELEGATE
84

85
credentials = Credentials(username='user@company.com', password='password')
86
account = Account(
87
    primary_smtp_address='user@company.com',
88
    credentials=credentials,
89
    autodiscover=True,
90
    access_type=DELEGATE
91
)
92
```
93

94
### OAuth2 Authentication
95

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

98
```python { .api }
99
class OAuth2Credentials:
100
    def __init__(
101
        self,
102
        client_id: str,
103
        client_secret: str,
104
        tenant_id: str,
105
        identity: Identity = None
106
    ):
107
        """
108
        OAuth2 client credentials flow.
109
        
110
        Parameters:
111
        - client_id: Azure AD application client ID
112
        - client_secret: Azure AD application client secret
113
        - tenant_id: Azure AD tenant ID
114
        - identity: User identity for impersonation
115
        """
116

117
class OAuth2AuthorizationCodeCredentials:
118
    def __init__(
119
        self,
120
        client_id: str,
121
        client_secret: str,
122
        tenant_id: str,
123
        authorization_code: str,
124
        redirect_uri: str
125
    ):
126
        """
127
        OAuth2 authorization code flow.
128
        
129
        Parameters:
130
        - client_id: Azure AD application client ID
131
        - client_secret: Azure AD application client secret  
132
        - tenant_id: Azure AD tenant ID
133
        - authorization_code: Authorization code from OAuth flow
134
        - redirect_uri: Redirect URI used in OAuth flow
135
        """
136

137
class OAuth2LegacyCredentials:
138
    def __init__(self, username: str, password: str):
139
        """
140
        Legacy OAuth2 credentials using username/password.
141
        
142
        Parameters:
143
        - username: Username (email address)
144
        - password: Password
145
        """
146
```
147

148
Usage example:
149

150
```python
151
from exchangelib import Account, OAuth2Credentials, DELEGATE
152

153
credentials = OAuth2Credentials(
154
    client_id='your-client-id',
155
    client_secret='your-client-secret',
156
    tenant_id='your-tenant-id'
157
)
158

159
account = Account(
160
    primary_smtp_address='user@company.com',
161
    credentials=credentials,
162
    autodiscover=True,
163
    access_type=DELEGATE
164
)
165
```
166

167
### Manual Configuration
168

169
Manual server configuration when autodiscovery is not available or desired.
170

171
```python { .api }
172
class Configuration:
173
    def __init__(
174
        self,
175
        server: str,
176
        credentials: Credentials,
177
        version: Version = None,
178
        auth_type: str = None,
179
        retry_policy: BaseProtocol = None
180
    ):
181
        """
182
        Manual Exchange server configuration.
183
        
184
        Parameters:
185
        - server: Exchange server hostname or URL
186
        - credentials: Authentication credentials
187
        - version: Exchange server version
188
        - auth_type: Authentication type (NTLM, BASIC, etc.)
189
        - retry_policy: Retry policy for failed requests
190
        """
191

192
class O365InteractiveConfiguration:
193
    def __init__(self, username: str):
194
        """
195
        Interactive OAuth2 configuration for Office365.
196
        
197
        Parameters:
198
        - username: Username for interactive authentication
199
        """
200
```
201

202
Usage example:
203

204
```python
205
from exchangelib import Account, Credentials, Configuration, Version, Build
206

207
credentials = Credentials(username='user@company.com', password='password')
208
config = Configuration(
209
    server='mail.company.com',
210
    credentials=credentials,
211
    version=Version(build=Build(15, 0, 1236, 3))
212
)
213

214
account = Account(
215
    primary_smtp_address='user@company.com',
216
    config=config,
217
    autodiscover=False
218
)
219
```
220

221
### Identity and Impersonation
222

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

225
```python { .api }
226
class Identity:
227
    def __init__(
228
        self,
229
        primary_smtp_address: str = None,
230
        name: str = None,
231
        sid: str = None,
232
        upn: str = None
233
    ):
234
        """
235
        User identity for impersonation.
236
        
237
        Parameters:
238
        - primary_smtp_address: Primary SMTP address
239
        - name: Display name
240
        - sid: Security identifier
241
        - upn: User principal name
242
        """
243

244
# Constants for access types
245
DELEGATE: str = 'Delegate'
246
IMPERSONATION: str = 'Impersonation'
247
```
248

249
Usage example:
250

251
```python
252
from exchangelib import Account, Credentials, Identity, IMPERSONATION
253

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

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

260
account = Account(
261
    primary_smtp_address='target@company.com',
262
    credentials=credentials,
263
    access_type=IMPERSONATION,
264
    identity=identity
265
)
266
```
267

268
### Connection Management
269

270
Utilities for managing connections and cleaning up resources.
271

272
```python { .api }
273
def close_connections():
274
    """
275
    Close all open connections to Exchange servers.
276
    Should be called when finished with exchangelib operations.
277
    """
278

279
def discover(email: str, credentials: Credentials = None) -> Account:
280
    """
281
    Autodiscover Exchange settings for an email address.
282
    
283
    Parameters:
284
    - email: Email address to discover settings for
285
    - credentials: Optional credentials for authentication
286
    
287
    Returns:
288
    Account object with discovered settings
289
    """
290
```
291

292
Usage example:
293

294
```python
295
from exchangelib import discover, close_connections, Credentials
296

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

301
# Use the account...
302

303
# Clean up connections when done
304
close_connections()
305
```
306

307
## Authentication Types
308

309
exchangelib supports multiple authentication methods:
310

311
- **BASIC**: Basic HTTP authentication
312
- **NTLM**: Windows NTLM authentication
313
- **DIGEST**: HTTP Digest authentication
314
- **OAUTH2**: OAuth2 token-based authentication
315
- **GSSAPI**: Kerberos/GSSAPI authentication (with optional dependency)
316
- **SSPI**: Windows SSPI authentication (Windows only)
317
- **CBA**: Certificate-based authentication
318

319
```python { .api }
320
# Authentication type constants
321
BASIC: str
322
NTLM: str
323
DIGEST: str
324
OAUTH2: str
325
GSSAPI: str
326
SSPI: str
327
CBA: str
328
```