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, 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.
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
Scheduling is optional
A server that implements CalDAV scheduling tells attendees about changes. One that does not leaves invitations to the client. RFC 6638
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
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 or 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 calendarUrlcalendar_url and contactsUrlcontacts_url out to discover them from the address.
const account = await workwae.imapAccounts.create({
email: "ada@fastmail.com",
password: appPassword,
dav: {}, // discover CalDAV and CardDAV from the address
externalRef: user.id,
});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 have no push, so Workwae polls. An API write triggers a pass at once. See the matrix for how each provider detects changes.
Should Google and Microsoft calendars use CalDAV?
No. Those providers have native paths with push: Google Calendar and 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.
Early access
Put DAV calendars on the same API as Google.
Tell us which CalDAV and CardDAV hosts your users have.