Outlook Calendar API Guide
Microsoft Graph provides a REST API for calendars and events stored in Outlook.com and Microsoft 365 mailboxes. Use it to read appointments, create and update events, manage meeting invitations, and synchronize a local calendar view. This guide links to 17 complete examples using direct Chilkat.Http calls for Graph requests.
Choose a language to update all 17 example links below. Each link opens the complete example in that language. The guide text stays the same.
The examples use https://graph.microsoft.com/v1.0, Chilkat 11.6.0 or later, and an unlocked Chilkat library. Outlook does not have to be running: these requests address the online mailbox, not a local Outlook installation or PST file. National clouds use different authority and Graph hosts. See the Microsoft Graph calendar overview for the API's scope.
Begin with authorization, list the available calendars, then use Read a Date-Range Agenda with CalendarView to display upcoming events. Calendar and event IDs are opaque, case-sensitive strings. Save them with the mailbox context and URL-encode an ID when inserting it into a request path.
| Request requirement | Chilkat call or property |
|---|---|
| Bearer access token | Set Http.AuthToken to the token value, without the Bearer prefix. |
| GET or DELETE without a body | Call Http.HttpNoBody with the verb, URL, and an HttpResponse. |
| POST or PATCH with JSON | Build a JsonObject, then call Http.HttpJson with the verb, URL, JSON, application/json, and response object. |
| Headers and response fields | Use SetRequestHeader for preferences. Check StatusCode, then load a JSON response with JsonObject.Strict enabled. |
Authorization
Register an application in Microsoft Entra and select the account types it will support. A personal Outlook.com account uses delegated authorization. Microsoft 365 work/school mailboxes also support administrator-authorized application access for unattended operations.
| Model | Account and request context | How access continues |
|---|---|---|
| Delegated OAuth2 | A signed-in Outlook.com or Microsoft 365 user. /me addresses that user. | After initial consent, refresh tokens can obtain new access tokens. Sign-in can be required again. |
| Application credentials | A Microsoft 365 organization grants application permissions. Address /users/{id-or-UPN}; there is no signed-in /me. | Request another token using a fresh certificate assertion. No refresh token is issued. |
Sign in once, then refresh as needed
The interactive example uses a system browser, authorization code flow, and PKCE with S256. Register its http://localhost:3017/ redirect under Mobile and desktop applications. Chilkat handles this local callback; no hosted webhook receiver is needed. A public desktop app does not keep a client secret. Use an authority and app account-type configuration appropriate to the intended users. Web and mobile applications need redirect handling appropriate to their environment. Microsoft authorization-code flow documentation.
The example requests offline_access and Calendars.ReadWrite to cover the collection's writes. Read-only applications should request only the permissions their operations require. The refresh example uses the same client ID and authority, retains the old refresh token if no replacement is returned, and saves a rotated token when provided. Revocation or an interaction requirement means the user must sign in again.
Delegated examples read qa_data/tokens/outlookCalendar.json. Keep credentials private and associated with their original app and account. A token for SMTP, IMAP, or another resource is not a Graph token. Production applications should protect credential storage, serialize refreshes, and replace saved credentials atomically.
Run unattended with a certificate
The certificate example uses a tenant-specific token endpoint, the Graph .default scope, and application permissions with administrator consent. It reads an explicitly named organizational mailbox. Upload the public certificate to the app registration; keep the RSA private key in a trusted application environment. This flow does not apply to personal Outlook.com mailboxes. Limit mailbox access using the organization's supported Exchange application-access controls.
The example creates a short-lived PS256 assertion with a SHA-256 certificate thumbprint in x5t#S256. The assertion authenticates to the token endpoint; the returned access token authenticates to Graph. The private configuration contains tenant ID, client ID, mailbox, PFX path, and PFX password. Microsoft certificate-credentials documentation.
Calendars
List calendars before selecting a nondefault calendar. A display name is not a unique identifier; use the returned ID. Follow every @odata.nextLink exactly as returned, keeping the same request preferences. The listing examples reject unexpected hosts and repeated links and stop at a stated 100-page demonstration limit.
The secondary-calendar example performs one chosen action: create, rename, or delete. It refuses to rename or delete the default calendar. Creation saves a pending record before sending because calendar creation has no event-style transactionId. If the outcome is uncertain, reconcile the calendar list before trying another creation. Deleting a secondary calendar removes its events as well.
Shared-calendar access requires both actual sharing or delegation rights and a suitable delegated permission such as Calendars.Read.Shared. The own-calendar scope in the basic OAuth example does not cover this case; change the requested scope and obtain consent. The shared example reads /users/{owner}/calendar/calendarView. Keep the owner's mailbox context with returned IDs instead of using them against the recipient's /me/events. Shared and delegated calendar access.
Events
Choose an event list or a date-range view
An event list contains single events and recurring series masters. A calendarView expands recurring occurrences and exceptions within a specified time window, making it suitable for an agenda. The date-range example uses explicit UTC bounds for the next seven days. To address a secondary calendar, use /me/calendars/{id}/calendarView. CalendarView request and response.
The examples request UTC response times and immutable event IDs with Prefer: outlook.timezone="UTC", IdType="ImmutableId". Send the same preferences on continuation requests. The timezone preference controls returned time values; query-bound offsets determine the requested window. Keep IDs as strings and use a consistent ID preference throughout the application.
Create and update events deliberately
The basic creation example creates an appointment without attendees. It saves the request body and a generated transactionId before posting, then records the returned event ID in a receipt. Reuse that saved request after an uncertain result; do not generate a new transaction ID for a retry of the same operation. A successful receipt prevents accidental repeat creation on the next run. Use separate private files for each logical operation and account. Create an event.
The update example retrieves an event and PATCHes only its subject, location, and reminder settings. It leaves the body and attendees alone. GET does not lock an event; applications must choose how to reconcile concurrent edits. When changing a Teams meeting's body, preserve its online-meeting content. Updating a meeting can notify attendees. Event update behavior.
Recurring and all-day events
A recurrence combines a pattern and a range. The recurring example creates three daily appointments, then retrieves their instances. Save the series-master ID separately from occurrence IDs: updating a master affects the series, while an occurrence ID targets one instance. For a recurring appointment at a fixed local time, use a supported time zone consistently so daylight-saving changes are handled correctly.
An all-day event has midnight boundaries in the same time zone and an exclusive end date. A one-day event ends at midnight on the next date. The example demonstrates a two-day span in UTC and explicitly sets availability to free. Local calendar dates should not be treated as a fixed number of elapsed hours across daylight-saving transitions. Event properties and recurrence.
Meetings and Availability
The meeting example adds attendees to a calendar event. Replace the sample address before running: the request sends real invitations. Teams is optional and disabled by default. When enabled, the example first checks the calendar's allowedOnlineMeetingProviders, then requests teamsForBusiness and reads onlineMeeting.joinUrl. This creates an online meeting attached to a calendar event. It requires an appropriately configured organizational calendar. Online meetings in Outlook calendars.
To respond to an invitation, use the attendee's event ID and choose one action: accept, tentativelyAccept, or decline. The example checks that the user is not the organizer and explicitly sets sendResponse. A successful action returns HTTP 202 without a JSON body. Set sendResponse to false only when you intend to suppress the response message to the organizer; it is not a dry run.
Free/busy lookup uses getSchedule for Microsoft 365 organizational users and resources; delegated personal Microsoft accounts are not supported. The example requests eight hours in 30-minute slots. Check errors for each schedule even when the overall request returns HTTP 200. Keep availabilityView as a string so leading zeroes survive: 0 means free or working elsewhere, 1 tentative, 2 busy, and 3 out of office. A free slot does not reserve a room or guarantee acceptance of an invitation. GetSchedule permissions and limits.
Synchronization
Use delta queries when maintaining a local date-range view across runs. The v1.0 example tracks the primary calendar for a fixed 30-day window. The initial request establishes a baseline; subsequent rounds apply additions, updates, and removals. Follow @odata.nextLink within a round and save @odata.deltaLink to begin the next round. Preserve the complete URLs and request preferences; do not rebuild tokens or add $select. A moving time window requires a new baseline.
An @removed item is removed from the tracked local view; it does not always mean the event was deleted globally. The example stores small event records under JSON-safe hash keys, preserving the original string IDs. Records with removed=true are excluded from the local view. Partial updates retain omitted fields. CalendarView delta synchronization.
The private checkpoint contains both event data and its continuation URL. Each page saves a backup of the previous matching pair before replacing the checkpoint. Failed HTTP or validation checks do not advance it. Restore the backup if a write damages the main file. Replaying a page updates the same records, and an unfinished scan can resume from its saved nextLink. Production storage should commit data and cursor atomically, with one writer per account and window.
For an expired or rejected synchronization state, establish a new baseline and reconcile the old view deliberately. More generally, handle 401 by refreshing or authorizing again, investigate permissions and mailbox access for 403, and honor Retry-After on 429 before a bounded retry. A timeout or 5xx response to a write can leave its outcome uncertain; inspect the saved operation and server state before repeating it. Keep token files, event caches, and detailed diagnostics private.