事件
Working with calendars and events using the Microsoft Graph API
The Microsoft Graph Calendar API provides calendar, calendarGroup, event, and other resources that enable you to create events and meetings, find workable meeting times, manage attendees, and more. With the Calendar API, you can build a variety of experiences with calendar data.
The event type represents a scheduled occurrence on a calendar, such as a meeting, holiday, or time block. Meetings, such as team meetings or one-on-ones, are all represented by event resources. You can directly manage the event lifecycle by creating, canceling, and deleting events directly, among other actions. Also, you can create draft event messages, send them, forward them, and create draft replies, and more. By working with event messages, you enable the user to take an active role in creating events and meetings. You also enable them to communicate to meeting originators, other recipients, and attendees.
The Microsoft Graph API provides methods for operations such as creating, updating, deleting, and canceling events. The following table lists some common lifecycle event use cases and the APIs that Microsoft Graph provides for working with them.
| Use case | Verb | Example URL |
|---|---|---|
| Create an event. | POST | /users/{id | userPrincipalName}/events |
| Delete an event from a calendar. | DELETE | /users/{id | userPrincipalName}/events/{id} |
| Cancel an event and send a cancellation message. Note: Specify the optional cancellation message in the request body. |
POST | /users/{id | userPrincipalName}/events/{id}/cancel |
| Update an event. Note: Specify the event details to update in the request body. |
PATCH | /users/{id | userPrincipalName}/events/{id} |
| Accept an event. | POST | /users/{id | userPrincipalName}/events/{id}/accept |
| Tentatively accept an event. | POST | /users/{id | userPrincipalName}/events/{id}/tentativelyAccept |
| Decline an event. | POST | /users/{id | userPrincipalName}/events/{id}/decline |
| Dismiss an event reminder. | POST | /users/{id | userPrincipalName}/events/{id}/dismissReminder |
| Snooze an event reminder. | POST | /users/{id | userPrincipalName}/events/{id}/snoozeReminder |
The eventMessage resource is an abstract type that represents meeting requests, cancellations, and responses. Responses are generated when the message recipient accepts, tentatively accepts, or declines the request. Handling eventMessageRequest and eventMessageResponse moves the event through its lifecycle. The messaging APIs in the Calendar API support both MIME and JSON content.
The following table lists some common event message use cases and the APIs for working with them.
| Use case | Verb | Example URL |
|---|---|---|
| Send an existing draft message. | POST | /users/{id | userPrincipalName}/messages/{id}/send |
| Create a draft reply. | POST | /users/{id | userPrincipalName}/messages/{id}/createReply |
| Reply to an event message. | POST | /users/{id | userPrincipalName}/messages/{id}/reply |
| Create a draft reply-all message. | POST | /users/{id | userPrincipalName}/messages/{id}/createReplyAll |
| Reply to all in an event message. | POST | /users/{id | userPrincipalName}/messages/{id}/replyAll |
| Create a draft forward. | POST | /users/{id | userPrincipalName}/messages/{id}/createForward |
| Forward an event message. | POST | /users/{id | userPrincipalName}/messages/{id}/forward |
The abstract attachment type serves as a base for files, items, and references that are attached to events, messages, and posts. You can view the attachments for an event, for example, with the List attachments method. You can delete an attachment with the Delete attachment method. Events in group calendars don't support attachments.
The fileAttachment, itemAttachment, and referenceAttatchment types represent the three kinds of items that can be attached to calendar items. An itemAttachment object represents a contact, event, or message that is directly attached to a user event, message, or post. A fileAttachment represents a file that is directly attached. A referenceAttachment represents an item, such as a Word document or text file, that is located on a OneDrive for work or school cloud drive or other supported storage location. To see all of the attachments for an event, for example, you can use the GET /users/{id | userPrincipalName}/events/{id}/attachments endpoint.
You can directly upload attachments less than 3 MB in size to an event for a user with the Add attachment method. For an attachment that is larger than 3 MB, however, you must use the attachment: createUploadSession method to get an upload URL that you use to iteratively upload the attachment.
With the Calendar API, you can create, read, update, and delete calendars, create and view calendar events, get free/busy information for users, and find suggested meeting times.
The Calendar API provides methods to operate on calendars and calendar groups. The following table shows some use cases with selected URLs.
Note: Many of the methods shown in the following table have other URLs for related use cases. For example, to update a user's calendar in a specific calendar group, send a PATCH operation with the URL
/users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}.
| Use case | Verb | Example URL |
|---|---|---|
| List calendars for a user. | GET | /users/{id | userPrincipalName}/calendars |
| List a user's calendars in a group. | GET | /users/{id | userPrincipalName}/calendarGroups/{calendarGroupId}/calendars |
| Create a calendar. | POST | /users/{id | userPrincipalName}/calendars |
| Get a calendar. | GET | /users/{id | userPrincipalName}/calendars/{id} |
| Update a calendar. | PATCH | /users/{id | userPrincipalName}/calendars/{id} |
| Delete a calendar. | DELETE | /users/{id | userPrincipalName}/calendars/{id} |
| Create a calendar group. | POST | /users/{id | userPrincipalName}/calendarGroups |
| Get a calendar group. | GET | /users/{id | userPrincipalName}/calendarGroups/{id} |
| Update a calendar group. | PATCH | /users/{id | userPrincipalName}/calendarGroups/{id} |
| Delete a calendar group. | DELETE | /users/{id | userPrincipalName}/calendarGroups/{id} |
Two of the core functions of calendaring are to find free/busy information and find meeting times in order to schedule meetings. The Calendar API provides the Get free/busy schedule method that returns a collection of scheduleInformation objects for a time period and a collection of users, resources, or distribution lists. You can present this information to the user so that they can manually pick an appropriate time at which to schedule a meeting. Use the user: findMeetingTimes method to get a meetingTimeSuggestionResult that contains a collection of meetingTimeSuggestion objects that represent detailed information about proposed meeting times for the participants and constraints that you sent.
A calendar category is a combination of a description and a categoryColor that together define a category for an Outlook item and control how Outlook displays the item. Outlook users can group messages and events, for example, by category. For more information, see outlookCategory.
When users share calendars with other users from within Outlook clients, they can control the calendar items that the recipients can view or edit. The calendarPermissions relationship contains permissions for every user with whom a user shared their calendar. This relationship allows you to, for example, see which users can view free/busy information for the owner, view all calendar information, or edit events on the calendar.
Open extensions, formerly known as Office 365 data extensions, represent the preferred way to store and access custom data for resources in a user's mailbox. If an Outlook MAPI property isn't available in the Microsoft Graph API metadata, then you can fall back to Outlook extended properties. For more information, see Outlook extended properties overview.
The Calendar API in Microsoft Graph allows you to build a range of experiences with calendar data. To learn more:
- Drill down on the methods and properties of the resources most helpful to your scenario.
- Try the API in the Graph Explorer.