You want to read and write calendar events for iCloud, and the only protocol it exposes is CalDAV, the same one Fastmail and other CalDAV servers use. The question is whether to speak CalDAV directly or call a unified REST calendar API that hides it. This page compares the two at the protocol level, so you can decide before you write a single PROPFIND.
This is a decision guide, not an iCloud how-to. For the iCloud task recipes, see the Apple Calendar API guide. For listing and creating calendars across providers, see Create and list calendars.
What’s CalDAV?
Section titled “What’s CalDAV?”CalDAV is a calendar access protocol defined in RFC 4791, published in March 2007 as an extension of WebDAV over HTTP. It models calendars as collections and events as resources, transports iCalendar (RFC 5545) bodies inside XML envelopes, and uses HTTP verbs like PROPFIND and REPORT to query data. iCloud and Fastmail both expose CalDAV as their only programmatic calendar interface, with no JSON or OAuth layer on top.
CalDAV predates the REST and JSON conventions most developers expect today. A single “list events in March” operation becomes a REPORT request whose body is a nested XML filter, and the response is a multistatus document you parse element by element. Every event you get back is a raw VEVENT block you decode yourself.
How does CalDAV authentication work?
Section titled “How does CalDAV authentication work?”CalDAV authenticates over HTTP Basic auth, scoped per user, with no OAuth and no central developer console. iCloud requires each user to hand-generate a 16-character app-specific password in their Apple ID settings, because a normal account password fails against the CalDAV endpoint. Fastmail works the same way, issuing per-app passwords from account settings. You store and rotate one secret per connected user.
Because there is no token-refresh flow, a revoked password fails silently on the next sync with no advance signal. A unified API moves this off your plate: it manages credentials per grant across iCloud, Google, and Microsoft and emits a grant.expired event you can subscribe to. The Nylas authentication guide covers the hosted OAuth and bring-your-own flows that replace per-user password handling.
How’s event data modeled in each approach?
Section titled “How’s event data modeled in each approach?”CalDAV returns events as iCalendar VEVENT text, the same format RFC 5545 defines for .ics files. A unified REST calendar API returns events as JSON objects with typed fields. The difference is who parses the data: with CalDAV you decode VEVENT properties yourself, while a REST API hands you title, when, and participants already structured.
Here is the gap in concrete terms. Reading the start time of one event from CalDAV means pulling the DTSTART line out of a VEVENT block, interpreting its VALUE and TZID parameters, and resolving the referenced VTIMEZONE. The 3 fields below show what that same event looks like once normalized to JSON.
BEGIN:VEVENTDTSTART;TZID=America/New_York:20260620T140000SUMMARY:Design reviewEND:VEVENTThe Nylas Calendar API returns the equivalent event as JSON, where when.start_time is a Unix timestamp, title holds the summary, and the time zone is a named field. You read 3 keys instead of parsing a text block and a separate VTIMEZONE component.
How do you sync changes with CalDAV?
Section titled “How do you sync changes with CalDAV?”CalDAV has no push notifications, so detecting changes means polling. The efficient pattern uses ETags: you issue a REPORT to fetch the ETag of every event, compare against your stored copies, and re-fetch only the resources whose ETag changed. RFC 6578 adds sync-collection tokens, but iCloud’s support is partial, so most integrations fall back to ETag diffing on an interval you maintain.
That polling loop is code you own: scheduling, change detection, and reconciliation per user. A unified API replaces it with webhooks that fire on event.created, event.updated, and event.deleted across providers. One subscribed endpoint covers iCloud, Google, and Microsoft, so you react to changes instead of asking for them every few minutes. See Sync calendar events with webhooks for the subscription setup.
How does recurrence differ between CalDAV and a REST API?
Section titled “How does recurrence differ between CalDAV and a REST API?”Both approaches use RFC 5545 RRULE strings, so a weekly standup is FREQ=WEEKLY;BYDAY=MO in either case. The difference is expansion: CalDAV often returns the base VEVENT plus separate override components, and you compute the individual occurrences yourself. A REST calendar API can expand the series server-side and return each instance as its own event.
With raw CalDAV you handle the base recurrence rule, the EXDATE exclusions, and the modified instances (RECURRENCE-ID overrides) as 3 distinct cases, then merge them into a timeline. The Nylas Calendar API accepts the same RRULE on write and can return expanded instances on read, so a 52-week series comes back as 52 events without client-side date math. The recurring events guide shows the recurrence array format.
CalDAV vs the Nylas Calendar API
Section titled “CalDAV vs the Nylas Calendar API”The table below maps each protocol concern to what you build with raw CalDAV against what a unified REST API gives you. The pattern is consistent: CalDAV exposes 1 provider through low-level primitives, while the unified API covers iCloud, Google, and Microsoft behind typed JSON. For multi-provider apps or any team that wants to ship in days, the Nylas Calendar API is the recommended path.
| Concern | CalDAV (RFC 4791, direct) | Nylas Calendar API |
|---|---|---|
| Transport | XML over HTTP (PROPFIND, REPORT) | JSON over REST (GET, POST) |
| Event format | iCalendar VEVENT you parse | Typed JSON object |
| Authentication | HTTP Basic, per-user app password | Hosted OAuth or BYO, managed per grant |
| Change detection | Poll and diff ETags yourself | Webhooks across every provider |
| Recurrence expansion | Compute occurrences client-side | Expanded instances returned on read |
| Provider coverage | iCloud or Fastmail, one at a time | iCloud, Google, and Microsoft |
If iCloud is your only target and you are comfortable with XML and ICS parsing, direct CalDAV avoids a dependency. Raw CalDAV is also the path when your calendar source is Fastmail or another CalDAV-only server that the unified API doesn’t connect. For most teams targeting iCloud, Google, or Microsoft, the unified API removes weeks of protocol work, which is why it’s the default recommendation in the table.
Read events with one JSON call
Section titled “Read events with one JSON call”The whole point of a unified API is collapsing the CalDAV request-and-parse cycle into a single call. You list events with GET /v3/grants/{grant_id}/events?calendar_id=..., which returns up to 200 events per page as JSON sorted by start time, with a default page size of 50. No XML filter body, no VEVENT decoding, no VTIMEZONE resolution.
The request below reads events from one calendar for a connected iCloud user. It replaces the CalDAV REPORT plus multistatus parsing with a single GET, and the same call works unchanged against Google and Microsoft accounts.
curl --request GET \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --header 'Accept: application/json'Pass a real calendar_id rather than the primary alias, since iCloud rejects that shortcut. Fetch the ID first with Create and list calendars, then reuse it on every events call.
What’s next
Section titled “What’s next”- Apple Calendar API guide for the iCloud read and write recipes
- Create and list calendars to get the
calendar_idyou pass to events - Schedule rooms with virtual calendars for resources that have no email account
- Sync calendar events with webhooks to replace CalDAV polling
- Events API reference for every endpoint and parameter