CardDAV

June 9, 2022 - Reading time: 2 minutes

This page is currently a braindump of CardDAV related information. If there is a library for this in the language you’re using, you’re probably better off using that.

CardDAV has a lot of functionality, but depending on your purposes you can keep your code simple and get the job done easily. With critical information such as address books, it is usually a good idea to keep your access read only. If you mess up with read only access, you just read incorrectly. But if you mess up when trying to read/delete contacts, you risk losing user data.

Most of URLs on this page apply to FastMail. They may or may not work with other providers. Fortunately, CardDAV responses include the URL of every resource, so all you need to do is write your code to follow those. This way, your code will work across different services, or even when your service decides to change URL structures.

Finding the CardDAV endpoint

You can send a PROPFIND request to /.well-known/carddav. It should redirect you to the correct endpoint. You will need to be authenticated to send this request.

curl -Lv -X PROPFIND --header "Depth: 0" -u "$email:$pass" https://carddav.fastmail.com/.well-known/carddav

The response XML should contain a field like <D:href>/dav/addressbooks</D:href>, which is the CardDAV endpoint.

Using CURL to access a CardDAV server

While the programming language you’re using probably has an HTTP client, it is very useful to try things in the command line by sending requests and looking at the responses. Tools like CURL and httpie can serve this purpose.

email="webdosusb@gmail.com"
pass="supersecret"

curl -X PROPFIND --header "Depth: 1" -u "$email:$pass" https://carddav.fastmail.com/dav/addressbooks/user/$email/

Getting the address book as a single VCard

If you send a GET request to the URL of an address book, the CardDAV server will reply with all the VCard objects serialized to a single response. This can be useful for making backups or importing address books for the first time.

curl -u "$email:$pass" https://carddav.fastmail.com/dav/addressbooks/user/$email/MyAddressBook/

HTTP Methods

• PROPFIND: This method is used when requesting information/properties about a certain object from the CardDAV server.
  • Examples: Addressbooks for a user, last modified date of a VCard object.
• PUT: This method is used to insert an object into the CardDAV server.
  • Examples: Creating a contact and putting the VCard object into the server.
• GET: This method is used to get objects from the CardDAV server.
  • Examples: Getting an address book, getting a VCard object

Errors

• propfind-finite-depth: If you are seeing <D:propfind-finite-depth/> in the server response, you most likely forgot to pass a Depth header with your HTTP request. Just pass Depth: 1 and the error should disappear. Other Resources vdirsyncer - A program that can syncronise with CardDAV servers