Source: https://cli.nylas.com/guides/caldav-explained

# CalDAV Explained: Protocol and Pitfalls

CalDAV is the open standard that lets a client read and write calendar events on a server — the protocol behind iCloud, Fastmail, Yahoo, and many self-hosted calendars. It's powerful and interoperable, and it's also XML-heavy, discovery-by-convention, and full of per-server quirks. This explains how CalDAV actually works, which providers speak it, why it's painful to integrate directly, and how to reach those calendars without writing PROPFIND requests.

Written by [Pouya Sanooei](https://cli.nylas.com/authors/pouya-sanooei) Software Engineer

Updated June 8, 2026

> **TL;DR:** CalDAV (RFC 4791) is calendar access layered on WebDAV over HTTPS: clients discover a calendar home, then `PROPFIND` and `REPORT` to read events and `PUT` iCalendar (`.ics`) files to write them. iCloud, Fastmail, and Yahoo speak it; Google supports it but steers you to its API. The cost is verbose XML, discovery-by-convention, and per-server quirks — which is why most teams reach it through an abstraction.

Command references used in this guide: [`nylas auth login`](https://cli.nylas.com/docs/commands/auth-login), [`nylas calendar events list`](https://cli.nylas.com/docs/commands/calendar-events-list), and [`nylas calendar list`](https://cli.nylas.com/docs/commands/calendar-list).

## What is CalDAV?

CalDAV is an open protocol, defined in [RFC 4791](https://www.rfc-editor.org/rfc/rfc4791), for accessing calendar data on a remote server. It extends WebDAV ([RFC 4918](https://www.rfc-editor.org/rfc/rfc4918)), which itself extends HTTP, so every operation is an HTTP request with a calendaring twist. Events are stored as iCalendar objects — the `.ics` format from [RFC 5545](https://www.rfc-editor.org/rfc/rfc5545) — one resource per event.

Because it's a standard rather than a vendor API, the same CalDAV client can talk to Apple, Fastmail, and a self-hosted Radicale server without per-vendor code, which is its core appeal. The trade-off is that “standard” means a 2007 design built on XML request bodies and HTTP methods most developers never touch directly.

## How do CalDAV discovery and authentication work?

A CalDAV client doesn't know your calendar URL up front — it discovers it. The convention starts at `/.well-known/caldav`, which redirects to the server's principal URL; a `PROPFIND` for `current-user-principal` then `calendar-home-set` walks you to the collection that holds your calendars. Only then can you list events. This multi-step discovery is mandated precisely because URLs differ per server and per account.

Authentication is HTTP-level, almost always Basic auth over TLS. For iCloud that means an app-specific password generated under two-factor authentication — iCloud allows a maximum of 25, all revoked when the primary password changes. Many servers also relocate accounts to partition hosts after login (iCloud lands you on hosts like `p_NN_-caldav.icloud.com`), so your client must follow those redirects.

```bash
# CalDAV discovery is a sequence of WebDAV requests:
# 1. Find the principal
curl -u 'user@icloud.com:app-specific-password' \
  -X PROPFIND https://caldav.icloud.com/.well-known/caldav \
  -H 'Depth: 0' --data '<propfind xmlns="DAV:"><prop><current-user-principal/></prop></propfind>'

# 2. PROPFIND the principal for calendar-home-set
# 3. PROPFIND the home for each calendar collection
# 4. REPORT each collection for events in a date range
# ...four XML round-trips before you read a single event.
```

## Which providers use CalDAV?

CalDAV is the calendar backbone for several major providers that publish no proprietary calendar API. The table lists the common ones and how they expose it. Apple is the most significant: iCloud has no REST calendar API at all, so CalDAV is the *only* programmatic way in.

| Provider | CalDAV host | Notes |
| --- | --- | --- |
| iCloud | `caldav.icloud.com` | Only programmatic option; app password |
| Fastmail | `caldav.fastmail.com` | Full CalDAV; app password |
| Yahoo | `caldav.calendar.yahoo.com` | CalDAV; app password |
| Google | `apidata.googleusercontent.com/caldav` | Supported, but Calendar API preferred |

## What makes CalDAV hard to work with?

Three things. First, every read and write is XML — you build `PROPFIND` and `calendar-query REPORT` bodies and parse multi-status `207` responses, where a single missing namespace breaks the request. Second, there's no push: CalDAV has no standard change-notification mechanism, so staying current means polling with `sync-token` or `ETag` comparisons rather than receiving events.

Third, servers diverge despite the standard. iCloud's partition redirects, Google's OAuth-over-CalDAV exception, and varying support for `sync-collection` all mean “works against one server” rarely means “works against all.” Building a reliable multi-provider CalDAV client is significantly more work than the spec suggests — which is why most products put an abstraction in front of it.

## How do you access CalDAV calendars without the protocol?

The CLI connects to CalDAV-backed providers over a single login and exposes the calendar as commands, so you never write a `PROPFIND`. Run `nylas auth login --provider icloud` with an app-specific password, and `nylas calendar events list` returns events as JSON — discovery, XML parsing, and partition redirects handled underneath. The same commands work whether the backend is CalDAV (iCloud) or a REST API (Google), so your code doesn't branch per provider.

That uniformity is the payoff: one command reads an iCloud calendar over CalDAV and a Google calendar over its API with identical syntax. For the exact iCloud connection values and app-password rules, see [iCloud CalDAV settings](https://cli.nylas.com/guides/icloud-caldav-settings), and for managing iCloud events from the terminal, [manage the iCloud calendar](https://cli.nylas.com/guides/manage-icloud-calendar-cli).

```bash
# Reach a CalDAV calendar without touching the protocol
nylas auth login --provider icloud   # uses an app-specific password
nylas calendar list --json
nylas calendar events list --days 14 --json
```

## Next steps

- [iCloud CalDAV settings](https://cli.nylas.com/guides/icloud-caldav-settings) — hosts, ports, and app-specific passwords
- [Manage the iCloud calendar](https://cli.nylas.com/guides/manage-icloud-calendar-cli) — events from the terminal over CalDAV
- [Sync calendars across providers](https://cli.nylas.com/guides/sync-calendars-across-providers) — CalDAV and API calendars in one flow
- [Recurring events and RRULE](https://cli.nylas.com/guides/recurring-calendar-events-api) — the iCalendar recurrence grammar
- [Full command reference](https://cli.nylas.com/docs/commands) — every flag and subcommand documented