Personal CardDAV vs server directory in webmail

DarDev Roundcube exposes two contact systems that look similar in the UI but serve different jobs: personal CardDAV address books synced from Stalwart, and the read-only server directory backed by JMAP principals. Confusing them leads to wrong export flags, missing autocomplete entries, and support tickets about empty Contacts after deploy. This guide explains when to use each.

Both layers read from Stalwart infrastructure on the internal Docker network. Neither replaces Twenty CRM as the sales system of record. For directory plugin internals see stalwart-directory-roundcube-plugin; for mail stack topology see inside-unified-mailer-stack; for how shared platform primitives back multiple products see multi-product-saas-one-core.

Personal CardDAV

The carddav plugin—rcmcarddav—auto-discovers Stalwart address books on login using the same IMAP credentials. Discovery URL is http://stalwart:18080/.well-known/carddav via stalwart-admin-proxy. Config in roundcube/carddav/config.inc.php marks the Stalwart account fixed: username %u, password %p, rediscover every 24 hours, refresh hourly, editable not read-only.

• Per-user personal contacts the mailbox owner creates and edits
• Survives in Stalwart CardDAV storage tied to that account
• Appears as carddav_* addressbook ids appended on login
• Suitable for one-off external contacts not worth a CRM record
• Export with scripts/mail/export-webmail-contacts.sh --carddav

Server directory

stalwart_directory queries Principal/query across all hosted domains. It is read-only, cached five minutes, and wired as default_addressbook for compose autocomplete. Every Stalwart mailbox with a principal appears—news@send.dardev.net, contact@send.dardev.net, sales roles—not only contacts the logged-in user saved manually.

• Cross-domain internal directory for compose To/Cc autocomplete
• Authoritative list comes from Stalwart account provisioning
• No create or edit from Roundcube UI
• Default first in autocomplete_addressbooks before sql
• Default export without --carddav flag uses same JMAP principals

Side-by-side comparison

• Ownership — CardDAV: mailbox user. Directory: Stalwart admin and scripts.
• Mutability — CardDAV: read-write. Directory: read-only.
• Scope — CardDAV: one user's books. Directory: all principals on the MTA.
• Protocol — CardDAV: HTTP well-known discovery. Directory: JMAP Principal/query.
• Typical use — CardDAV: external partners. Directory: email a colleague quickly.

Autocomplete order

custom.inc.php sets autocomplete_addressbooks to stalwart_directory then sql. After login, carddav plugin hooks append personal carddav_* sources. Roundcube merges results as the user types. If only personal contacts appear, directory JMAP may be unreachable—run validate-webmail.sh. If directory works but personal books are empty, log out and back in once after CardDAV deploy so discovery runs with fresh credentials.

Operator workflows

Provisioning a new role mailbox in Stalwart WebAdmin automatically surfaces it in server directory within cache TTL—no Roundcube SQL import. Adding a personal contact for a conference lead happens in Roundcube Contacts against the CardDAV book. Exporting for a marketing spreadsheet: default export script for all principals; --carddav user@send.dardev.net for one user's personal book only.

Do not duplicate CRM outreach lists into CardDAV. Cold prospects belong in Twenty CRM with consent discipline described in deployed-realities-explained and product outreach docs—not in webmail personal books that sync to one user's phone CardDAV client.

Troubleshooting

• Contacts empty after upgrade — re-login once; confirm CardDAV enabled on Stalwart account
• Directory stale after bulk import — wait five minutes or restart roundcube container
• Duplicate entries — same email in CardDAV and directory is normal; autocomplete dedupes by address
• TLS errors on CardDAV discovery — internal proxy uses HTTP on Docker network by design

Privacy and visibility

Server directory exposes every Stalwart mailbox email to all authenticated webmail users on allowed domains. That is acceptable for internal staff on a company MTA but would be wrong for a multi-tenant public host. Personal CardDAV books are visible only to the owning mailbox unless shared out of band. Choose architecture per threat model—not every Roundcube deployment should copy both layers.

Mobile and desktop clients

Staff using Thunderbird or mobile mail clients against Stalwart IMAP do not get stalwart_directory autocomplete—that plugin is Roundcube-only. They may configure CardDAV separately against Stalwart if the client supports it. Directory remains the webmail-native way to discover colleagues without maintaining a parallel LDAP directory.

Inside-unified-mailer-stack documents how webmail sits beside Listmonk and MTA admin. Contacts are not a fourth mail pipeline—they are read paths on existing Stalwart data. Keeping that distinction clear prevents accidental CRM imports from webmail export scripts.

Onboarding checklist for new staff

1. Receive Stalwart mailbox on send.dardev.net from ops
2. Log into webmail.dardev.net and set signature
3. Type a colleague name in compose to confirm directory autocomplete
4. Add optional personal CardDAV contact for external partner
5. Do not expect @dardev.net Zoho contacts in either book

Support questions labeled contacts broke after migration usually mean CardDAV discovery—not missing directory. Ask whether the issue is compose autocomplete or the Contacts tab; the fix differs. Re-login resolves most CardDAV discovery failures.