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.
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.
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="email@example.com" pass="supersecret" curl -X PROPFIND --header "Depth: 1" -u "$email:$pass" https://carddav.fastmail.com/dav/addressbooks/user/$email/
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/
<D:propfind-finite-depth/>in the server response, you most likely forgot to pass a Depth header with your HTTP request. Just pass
Depth: 1and the error should disappear. Other Resources vdirsyncer - A program that can syncronise with CardDAV servers