0
# Calendar and Appointments
1
2
Full calendar functionality for creating, updating, and managing appointments, meetings, and recurring events. Includes support for attendees, meeting requests, and complex recurrence patterns.
3
4
## Capabilities
5
6
### Calendar Item Creation and Properties
7
8
The CalendarItem class represents appointments, meetings, and calendar events with comprehensive scheduling features.
9
10
```python { .api }
11
class CalendarItem:
12
def __init__(
13
self,
14
account: Account = None,
15
folder: Folder = None,
16
**kwargs
17
):
18
"""
19
Create a new calendar item.
20
21
Parameters:
22
- account: Account the item belongs to
23
- folder: Calendar folder to save the item in
24
- **kwargs: Calendar item properties
25
"""
26
27
# Basic properties
28
subject: str
29
body: Body | HTMLBody
30
start: EWSDateTime
31
end: EWSDateTime
32
location: str
33
is_all_day: bool
34
35
# Meeting properties
36
organizer: Mailbox
37
required_attendees: list[Attendee]
38
optional_attendees: list[Attendee]
39
resources: list[Attendee]
40
41
# Status and response
42
my_response_type: str # 'NoResponseReceived', 'Organizer', 'Tentative', 'Accept', 'Decline'
43
response_requested: bool
44
45
# Meeting settings
46
allow_new_time_proposal: bool
47
is_online_meeting: bool
48
meeting_workspace_url: str
49
net_show_url: str
50
51
# Recurrence
52
recurrence: Recurrence
53
54
# Categories and importance
55
categories: list[str]
56
importance: str
57
sensitivity: str
58
59
# Status
60
legacy_free_busy_status: str # 'Free', 'Tentative', 'Busy', 'OOF', 'NoData'
61
show_as: str # Same as legacy_free_busy_status
62
63
# Reminders
64
reminder_is_set: bool
65
reminder_minutes_before_start: int
66
67
# Time zones
68
start_timezone: EWSTimeZone
69
end_timezone: EWSTimeZone
70
```
71
72
### Meeting Management
73
74
Create and manage meetings with attendees and meeting requests.
75
76
```python { .api }
77
class CalendarItem:
78
def save(
79
self,
80
send_meeting_invitations: str = 'SendToNone',
81
update_fields: list = None
82
):
83
"""
84
Save the calendar item.
85
86
Parameters:
87
- send_meeting_invitations: 'SendToNone', 'SendOnlyToAll', 'SendToAllAndSaveCopy'
88
- update_fields: List of specific fields to update
89
"""
90
91
def delete(
92
self,
93
delete_type: str = 'MoveToDeletedItems',
94
send_meeting_cancellations: str = 'SendToNone'
95
):
96
"""
97
Delete the calendar item.
98
99
Parameters:
100
- delete_type: Type of deletion
101
- send_meeting_cancellations: How to handle meeting cancellations
102
"""
103
104
def cancel(self, body: str | Body | HTMLBody = None):
105
"""
106
Cancel the meeting and send cancellation notices.
107
108
Parameters:
109
- body: Cancellation message body
110
"""
111
```
112
113
Usage example:
114
115
```python
116
from exchangelib import CalendarItem, Attendee, Mailbox, EWSDateTime, HTMLBody
117
from datetime import datetime, timedelta
118
119
# Create a meeting
120
start_time = EWSDateTime.from_datetime(datetime.now() + timedelta(days=1))
121
end_time = start_time + timedelta(hours=1)
122
123
meeting = CalendarItem(
124
account=account,
125
folder=account.calendar,
126
subject='Project Planning Meeting',
127
body=HTMLBody('<p>Let\'s discuss the Q4 project timeline.</p>'),
128
start=start_time,
129
end=end_time,
130
location='Conference Room A',
131
required_attendees=[
132
Attendee(mailbox=Mailbox(email_address='manager@company.com')),
133
Attendee(mailbox=Mailbox(email_address='colleague@company.com'))
134
],
135
optional_attendees=[
136
Attendee(mailbox=Mailbox(email_address='consultant@company.com'))
137
]
138
)
139
140
meeting.save(send_meeting_invitations='SendToAllAndSaveCopy')
141
```
142
143
### Meeting Responses
144
145
Handle meeting invitations and responses.
146
147
```python { .api }
148
class CalendarItem:
149
def accept(
150
self,
151
body: str | Body | HTMLBody = None,
152
tentative: bool = False
153
) -> AcceptItem | TentativelyAcceptItem:
154
"""
155
Accept a meeting invitation.
156
157
Parameters:
158
- body: Response message body
159
- tentative: Whether to accept tentatively
160
161
Returns:
162
AcceptItem or TentativelyAcceptItem response object
163
"""
164
165
def decline(self, body: str | Body | HTMLBody = None) -> DeclineItem:
166
"""
167
Decline a meeting invitation.
168
169
Parameters:
170
- body: Response message body
171
172
Returns:
173
DeclineItem response object
174
"""
175
176
def tentatively_accept(self, body: str | Body | HTMLBody = None) -> TentativelyAcceptItem:
177
"""
178
Tentatively accept a meeting invitation.
179
180
Parameters:
181
- body: Response message body
182
183
Returns:
184
TentativelyAcceptItem response object
185
"""
186
```
187
188
### Attendee Management
189
190
Manage meeting attendees with response tracking.
191
192
```python { .api }
193
class Attendee:
194
def __init__(
195
self,
196
mailbox: Mailbox,
197
response_type: str = 'NoResponseReceived'
198
):
199
"""
200
Create a meeting attendee.
201
202
Parameters:
203
- mailbox: Attendee's mailbox
204
- response_type: Response status
205
"""
206
207
mailbox: Mailbox
208
response_type: str # 'NoResponseReceived', 'Organizer', 'Tentative', 'Accept', 'Decline'
209
last_response_time: EWSDateTime
210
```
211
212
Usage example:
213
214
```python
215
from exchangelib import Attendee, Mailbox
216
217
# Create attendees with different roles
218
required_attendees = [
219
Attendee(
220
mailbox=Mailbox(
221
email_address='john@company.com',
222
name='John Smith'
223
)
224
),
225
Attendee(
226
mailbox=Mailbox(
227
email_address='jane@company.com',
228
name='Jane Doe'
229
)
230
)
231
]
232
233
optional_attendees = [
234
Attendee(
235
mailbox=Mailbox(
236
email_address='consultant@external.com',
237
name='External Consultant'
238
)
239
)
240
]
241
242
# Add to calendar item
243
meeting.required_attendees = required_attendees
244
meeting.optional_attendees = optional_attendees
245
```
246
247
### Recurring Events
248
249
Create and manage recurring calendar events with complex patterns.
250
251
```python { .api }
252
class Recurrence:
253
def __init__(
254
self,
255
pattern: RecurrencePattern,
256
boundary: RecurrenceBoundary
257
):
258
"""
259
Define recurrence for a calendar item.
260
261
Parameters:
262
- pattern: How often the event recurs
263
- boundary: When the recurrence ends
264
"""
265
266
pattern: RecurrencePattern
267
boundary: RecurrenceBoundary
268
269
class DailyRecurrence:
270
def __init__(self, interval: int = 1):
271
"""Daily recurrence pattern."""
272
273
class WeeklyRecurrence:
274
def __init__(
275
self,
276
interval: int = 1,
277
weekdays: list[str] = None,
278
first_day_of_week: str = 'Monday'
279
):
280
"""Weekly recurrence pattern."""
281
282
class MonthlyRecurrence:
283
def __init__(self, interval: int = 1, day_of_month: int = 1):
284
"""Monthly recurrence pattern."""
285
286
class YearlyRecurrence:
287
def __init__(self, interval: int = 1, month: int = 1, day_of_month: int = 1):
288
"""Yearly recurrence pattern."""
289
290
class EndDateRecurrenceBoundary:
291
def __init__(self, end: EWSDate):
292
"""End recurrence on a specific date."""
293
294
class NoEndRecurrenceBoundary:
295
def __init__(self):
296
"""Recurrence with no end date."""
297
298
class NumberedRecurrenceBoundary:
299
def __init__(self, number_of_occurrences: int):
300
"""End recurrence after a specific number of occurrences."""
301
```
302
303
Usage example:
304
305
```python
306
from exchangelib.recurrence import WeeklyRecurrence, EndDateRecurrenceBoundary, Recurrence
307
from exchangelib import EWSDate
308
from datetime import date, timedelta
309
310
# Create a weekly recurring meeting
311
weekly_pattern = WeeklyRecurrence(
312
interval=1, # Every week
313
weekdays=['Monday', 'Wednesday', 'Friday']
314
)
315
316
end_boundary = EndDateRecurrenceBoundary(
317
end=EWSDate.from_date(date.today() + timedelta(days=90))
318
)
319
320
recurring_meeting = CalendarItem(
321
account=account,
322
folder=account.calendar,
323
subject='Daily Standup',
324
start=EWSDateTime.from_datetime(datetime.now().replace(hour=9, minute=0)),
325
end=EWSDateTime.from_datetime(datetime.now().replace(hour=9, minute=30)),
326
location='Team Room',
327
recurrence=Recurrence(pattern=weekly_pattern, boundary=end_boundary)
328
)
329
330
recurring_meeting.save(send_meeting_invitations='SendToAllAndSaveCopy')
331
```
332
333
### All-Day Events
334
335
Create and manage all-day calendar events.
336
337
```python { .api }
338
class CalendarItem:
339
is_all_day: bool
340
341
def create_all_day_event(
342
subject: str,
343
start_date: EWSDate,
344
end_date: EWSDate = None,
345
**kwargs
346
):
347
"""
348
Create an all-day event.
349
350
Parameters:
351
- subject: Event subject
352
- start_date: Start date
353
- end_date: End date (defaults to same as start_date)
354
- **kwargs: Additional event properties
355
"""
356
```
357
358
Usage example:
359
360
```python
361
from exchangelib import EWSDate
362
from datetime import date
363
364
# Create an all-day event
365
all_day_event = CalendarItem(
366
account=account,
367
folder=account.calendar,
368
subject='Company Holiday',
369
start=EWSDateTime.from_date(date.today() + timedelta(days=30)),
370
end=EWSDateTime.from_date(date.today() + timedelta(days=31)),
371
is_all_day=True,
372
show_as='Free',
373
categories=['Holiday']
374
)
375
376
all_day_event.save()
377
```
378
379
### Free/Busy Status
380
381
Manage calendar availability and free/busy status.
382
383
```python { .api }
384
class CalendarItem:
385
show_as: str # 'Free', 'Tentative', 'Busy', 'OOF' (Out of Office)
386
legacy_free_busy_status: str # Same values as show_as
387
388
def get_free_busy_info(
389
start: EWSDateTime,
390
end: EWSDateTime,
391
requested_view: str = 'Detailed'
392
):
393
"""
394
Get free/busy information for a time period.
395
396
Parameters:
397
- start: Start time
398
- end: End time
399
- requested_view: Level of detail ('FreeBusy', 'Detailed')
400
401
Returns:
402
Free/busy information
403
"""
404
```
405
406
### Room and Resource Booking
407
408
Book meeting rooms and resources.
409
410
```python { .api }
411
class Room:
412
def __init__(self, email_address: str, name: str = None):
413
"""
414
Meeting room representation.
415
416
Parameters:
417
- email_address: Room's email address
418
- name: Room display name
419
"""
420
421
class RoomList:
422
def __init__(self, email_address: str, name: str = None):
423
"""
424
Room list representation.
425
426
Parameters:
427
- email_address: Room list email address
428
- name: Room list name
429
"""
430
431
def get_rooms(self) -> list[Room]:
432
"""Get all rooms in this room list."""
433
```
434
435
Usage example:
436
437
```python
438
from exchangelib import Room, Attendee
439
440
# Book a conference room
441
conference_room = Room(
442
email_address='conference-room-a@company.com',
443
name='Conference Room A'
444
)
445
446
meeting_with_room = CalendarItem(
447
account=account,
448
folder=account.calendar,
449
subject='Board Meeting',
450
start=start_time,
451
end=end_time,
452
location='Conference Room A',
453
resources=[
454
Attendee(mailbox=conference_room)
455
]
456
)
457
458
meeting_with_room.save(send_meeting_invitations='SendToAllAndSaveCopy')
459
```
460
461
### Calendar Item Response Objects
462
463
Special calendar response item types for meeting management.
464
465
```python { .api }
466
class AcceptItem:
467
def __init__(self, reference_item_id: ItemId, **kwargs):
468
"""Accept a meeting request."""
469
470
def send(self):
471
"""Send the acceptance response."""
472
473
class DeclineItem:
474
def __init__(self, reference_item_id: ItemId, **kwargs):
475
"""Decline a meeting request."""
476
477
def send(self):
478
"""Send the decline response."""
479
480
class TentativelyAcceptItem:
481
def __init__(self, reference_item_id: ItemId, **kwargs):
482
"""Tentatively accept a meeting request."""
483
484
def send(self):
485
"""Send the tentative acceptance response."""
486
487
class CancelCalendarItem:
488
def __init__(self, reference_item_id: ItemId, **kwargs):
489
"""Cancel a calendar item."""
490
491
def send(self):
492
"""Send the cancellation."""
493
```