Work with contacts

List address books

address_books = client.get_address_books()
for book in address_books:
    print(book.id, book.name)

If the account doesn’t advertise Contacts support, this returns [] instead of raising. Pass account_id to browse an address book another user has shared with you.

Search contacts

results = client.search_contacts(text="alice")
results = client.search_contacts(email="alice@example.com")

for contact in results:
    print(contact.display_name(), contact.primary_email())

Omitting both text and email returns every contact in the account. Unlike get_address_books(), an account that doesn’t support Contacts raises here rather than returning an empty list, since a caller searching for a contact is usually about to act on the result.

email matches as a substring against any address on the card, on both Cyrus and Stalwart. text matches as a substring against the whole card on Cyrus, including the name, but on Stalwart it only matches the email address, not the name: a name-only search that finds a contact on Cyrus can silently return nothing on Stalwart. Use email whenever the value you’re searching for might be an email address.