---
title: "CalDAV and CardDAV API · Workwae"
description: "Sync calendars and contacts from CalDAV and CardDAV servers through one REST API, with discovery, change detection and invitations handled."
url: https://workwae.com/providers/caldav-carddav
---

Providers

# A CalDAV and CardDAV API that looks like Google and Graph.

Add DAV settings to an IMAP account and its calendars and address books appear in the same calendar and contacts routes as every other provider.

What the protocols require

## XML over HTTP, one server per service.

These are the specifications. Workwae adds no feature that they do not allow.

### Discovery

Clients find a server from `/.well-known/caldav` or DNS SRV and TXT records, then follow the current user principal to the calendar home. [RFC 6764](https://www.rfc-editor.org/rfc/rfc6764), [CalDAV](https://www.rfc-editor.org/rfc/rfc4791), [CardDAV](https://www.rfc-editor.org/rfc/rfc6352)

### Change detection

A server may support the WebDAV sync report. Where it does not, a client compares collection tags and lists of etags. Nothing pushes. [RFC 6578](https://www.rfc-editor.org/rfc/rfc6578)

### Scheduling is optional

A server that implements [CalDAV](https://workwae.com/glossary#caldav) scheduling tells attendees about changes. One that does not leaves invitations to the client. [RFC 6638](https://www.rfc-editor.org/rfc/rfc6638)

### Credentials differ

Some providers require an app-specific password for third-party apps. Apple does for iCloud, and needs two-factor authentication on the account. [Apple app-specific passwords](https://support.apple.com/en-us/102654)

What Workwae does

## Discover, poll, diff and invite.

### Server discovery

Workwae tries a built-in table first, then the domain’s well-known URLs, then SRV and TXT records. The table has entries for iCloud, Fastmail, Yahoo (calendar only), GMX, Zoho, mailbox.org and Posteo. Every host passes the same private-address check as mail servers.

### Poll with sync-collection or etags

Each pass uses the sync report where the collection offers it, otherwise the collection tag and an etag listing. Passes run at connect, after an API write, when the day changes and every 15 minutes by default. Your webhooks follow what the pass finds.

### Recurring events

Series are expanded locally into the calendar window (90 days back to 365 ahead by default), as for Google. Occurrences and exceptions are listed as separate kinds.

### Invitations from SMTP

If the CalDAV server has no scheduling, Workwae mails invitations, updates, cancellations and replies from the account’s SMTP server, for meetings the account organizes. With `notify` on and no SMTP server the write is refused as `provider_unsupported`.

### Meetings and calendars

CalDAV has no server-made video link, but `onlineMeetingService` adds a [Zoom](https://workwae.com/providers/zoom) or [Webex](https://workwae.com/providers/webex) link. Calendar create and update store name, description and color. A time zone is refused.

### A DAV password of its own

Where DAV does not log in with the IMAP password, pass `dav.password` and `dav.user`. A failed DAV login answers `login_failed` and names the server.

SDK

## Connect a mailbox with calendar and contacts.

Leave `calendarUrl``calendar_url` and `contactsUrl``contacts_url` out to discover them from the address.

dav.tsdav.py

```ts
const account = await workwae.imapAccounts.create({
  email: "ada@fastmail.com",
  password: appPassword,
  dav: {}, // discover CalDAV and CardDAV from the address
  externalRef: user.id,
});
```

```python
account = workwae.imap_accounts.create(
    email="ada@fastmail.com",
    password=app_password,
    dav={},  # discover CalDAV and CardDAV from the address
    external_ref=user.id,
)
```

FAQ

## Questions teams ask.

**Can I connect CalDAV without a mailbox?**

An account is an IMAP account, so it needs a mailbox. DAV settings add calendars and contacts to it. A receive-only account with no SMTP server is allowed.

**Do changes arrive instantly?**

No. CalDAV and [CardDAV](https://workwae.com/glossary#carddav) have no push, so Workwae polls. An API write triggers a pass at once. See the [matrix](https://workwae.com/providers/) for how each provider detects changes.

**Should Google and Microsoft calendars use CalDAV?**

No. Those providers have native paths with push: [Google Calendar](https://workwae.com/providers/google-calendar) and [Microsoft 365](https://workwae.com/providers/microsoft-365). CalDAV and CardDAV are for servers without a vendor API.

**Will you connect to a server on a private network?**

No. Private and loopback addresses are refused, and plaintext logins too. See [IMAP](https://workwae.com/providers/imap).

Early access

## Put DAV calendars on the same API as Google.

Tell us which CalDAV and CardDAV hosts your users have.

[Request early access](https://workwae.com/early-access/) [All providers](https://workwae.com/providers/)