@rapidmx/web-client 0.25.1 → 0.27.0

package/dist/lib/components/avatar/ContactAvatar.js

@@ -1,7 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-/** A fixed palette of background colors, cycled by a hash of the contact's name — no photo upload feature
- * exists yet (`Contact.photoBlobKey` is modeled server-side but nothing in this app sets/reads it), so every
- * contact gets one of these deterministically rather than a plain generic gray circle for everyone. */
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { gravatarEnabled, gravatarUrl } from "../../contacts/gravatar.js";
+/** A fixed palette of background colors, cycled by a hash of the contact's name, for the initials shown when there is no picture. */
 const PALETTE = ["#7c3aed", "#2563eb", "#0891b2", "#059669", "#d97706", "#dc2626", "#db2777", "#4f46e5"];
 function initialsOf(displayName) {
     const parts = displayName.trim().split(/\s+/).filter(Boolean);
@@ -19,8 +23,27 @@ function colorOf(displayName) {
     }
     return PALETTE[Math.abs(hash) % PALETTE.length];
 }
-/** A small circular initials avatar for a contact, matching Outlook People's list-row avatars — deterministic
- * per name (same contact always gets the same color/initials), no photo-upload dependency. */
-export default function ContactAvatar({ displayName, size = 32 }) {
+/**
+ * A small circular avatar for a contact, matching Outlook People's: the contact's own picture when they have one, else their Gravatar (when `email`
+ * is given), else initials on a color that is deterministic per name. A picture that fails to load falls through to the next.
+ */
+export default function ContactAvatar({ displayName, size = 32, photoUrl, email }) {
+    const [gravatar, setGravatar] = useState();
+    const [failed, setFailed] = useState([]);
+    useEffect(() => {
+        setGravatar(undefined);
+        if (!email || !gravatarEnabled()) {
+            return;
+        }
+        let cancelled = false;
+        void gravatarUrl(email, size * 2).then((url) => !cancelled && setGravatar(url));
+        return () => {
+            cancelled = true;
+        };
+    }, [email, size]);
+    const src = [photoUrl, gravatar].find((url) => url && !failed.includes(url));
+    if (src) {
+        return (_jsx("img", { src: src, alt: "", "aria-hidden": "true", width: size, height: size, referrerPolicy: "no-referrer", onError: () => setFailed((list) => [...list, src]), className: "inline-block rounded-full object-cover shrink-0", style: { width: size, height: size } }));
+    }
     return (_jsx("span", { "aria-hidden": "true", style: { width: size, height: size, backgroundColor: colorOf(displayName), fontSize: size * 0.4 }, className: "inline-flex items-center justify-center rounded-full text-white font-semibold shrink-0", children: initialsOf(displayName) }));
 }

package/dist/lib/components/buttons/CopyIconButton.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+export interface CopyIconButtonProps {
+    /** The text put on the clipboard. */
+    value: string;
+    /** The button's accessible name and tooltip - say what is copied, e.g. "Copy address". */
+    label: string;
+    className?: string;
+}
+/**
+ * A small icon-only "copy" button to sit right after a value (an email address). The icon turns into a check mark for a moment once the value is on
+ * the clipboard, and a polite live region says "Copied" (or "Couldn't copy") for screen readers.
+ */
+export default function CopyIconButton({ value, label, className }: CopyIconButtonProps): React.JSX.Element;

package/dist/lib/components/buttons/CopyIconButton.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HiCheck, HiOutlineClipboardDocument } from "react-icons/hi2";
+import useCopyToClipboard from "../../util/useCopyToClipboard.js";
+/**
+ * A small icon-only "copy" button to sit right after a value (an email address). The icon turns into a check mark for a moment once the value is on
+ * the clipboard, and a polite live region says "Copied" (or "Couldn't copy") for screen readers.
+ */
+export default function CopyIconButton({ value, label, className }) {
+    const { status, copy } = useCopyToClipboard();
+    return (_jsxs("span", { className: "inline-flex items-center align-middle", children: [_jsx("button", { type: "button", "aria-label": label, title: label, onClick: () => void copy(value), className: [
+                    "inline-flex items-center justify-center rounded-sm p-1 text-text-muted hover:text-text hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary",
+                    className,
+                ]
+                    .filter(Boolean)
+                    .join(" "), children: status === "copied" ? (_jsx(HiCheck, { "aria-hidden": "true", className: "size-4 text-success" })) : (_jsx(HiOutlineClipboardDocument, { "aria-hidden": "true", className: "size-4" })) }), _jsx("span", { role: "status", "aria-live": "polite", className: "sr-only", children: status === "copied" ? "Copied" : status === "failed" ? "Couldn’t copy" : "" })] }));
+}

package/dist/lib/contacts/contactsApi.d.ts

@@ -77,6 +77,9 @@ export declare function pinnedSigningFingerprintsFor(contacts: Contact[], addres
  * `limit` cap). */
 export declare const PINNED_FINGERPRINT_PAGE_SIZE = 500;
 export declare const PINNED_FINGERPRINT_MAX_PAGES = 20;
+/** Every contact in `folderUids`, paged (`PINNED_FINGERPRINT_PAGE_SIZE`, at most `PINNED_FINGERPRINT_MAX_PAGES` pages
+ * per folder). A plain contacts read - never a Discovery lookup. */
+export declare function listContactsInFolders(folderUids: string[], client?: ApiClient): Promise<Contact[]>;
 /**
  * Fetches the trusted signing-key fingerprints (pinned and previous - see `pinnedSigningFingerprintsFor()`) for a
  * message sender's `address` from the contacts in `folderUids` (the reader's contacts folders), for
@@ -151,6 +154,18 @@ export declare function updateContact(patch: ContactPatch, client?: ApiClient):
  * `setMessageRead()`/`tasksApi.ts`'s `setTaskCompleted()`. Sends only `uid`/`version`/`favorite`, never
  * the rest of `contact` (the server rejects its managed fields). */
 export declare function setContactFavorite(contact: Contact, favorite: boolean, client?: ApiClient): Promise<Contact>;
+/**
+ * The URL of a contact's own picture, or `undefined` when they have none. The version is part of it so a replaced picture is fetched again rather than
+ * served from the browser's cache.
+ */
+export declare function contactPhotoUrl(contact: Pick<Contact, "uid" | "version" | "photoBlobKey">): string | undefined;
+/** The picture types the server accepts for a contact, and the most bytes it takes. */
+export declare const CONTACT_PHOTO_TYPES: string[];
+export declare const CONTACT_PHOTO_MAX_BYTES: number;
+/** Sets a contact's own picture from an image file (the file's own bytes go up, not JSON) and returns the updated contact. */
+export declare function uploadContactPhoto(uid: string, version: number, file: Blob): Promise<Contact>;
+/** Removes a contact's own picture and returns the updated contact. */
+export declare function deleteContactPhoto(uid: string, version: number, client?: ApiClient): Promise<Contact>;
 export declare function deleteContact(uid: string, version: number, client?: ApiClient): Promise<void>;
 export interface ContactList {
     uid: string;

package/dist/lib/contacts/contactsApi.js

@@ -4,7 +4,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 /** Typed wrappers over `@rapidmx/restapi`'s `/mail/contacts` REST surface — see `mailApi.ts`'s own header
  * comment for the shared ACL/authorization model every wrapper file here follows. */
-import { withClient } from "../util/api.js";
+import { ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
 import { buildQuery } from "../util/apiQuery.js";
 import { signingKeyFingerprints, } from "../crypto/keyvaultApi.js";
 /** Lists a folder's contacts, alphabetically by display name. Never includes soft-deleted contacts — see
@@ -29,7 +29,7 @@ export const PINNED_FINGERPRINT_PAGE_SIZE = 500;
 export const PINNED_FINGERPRINT_MAX_PAGES = 20;
 /** Every contact in `folderUids`, paged (`PINNED_FINGERPRINT_PAGE_SIZE`, at most `PINNED_FINGERPRINT_MAX_PAGES` pages
  * per folder). A plain contacts read - never a Discovery lookup. */
-async function listContactsInFolders(folderUids, client) {
+export async function listContactsInFolders(folderUids, client) {
     const contacts = [];
     for (const folderUid of folderUids) {
         for (let page = 0; page < PINNED_FINGERPRINT_MAX_PAGES; page++) {
@@ -118,6 +118,35 @@ export function updateContact(patch, client) {
 export function setContactFavorite(contact, favorite, client) {
     return updateContact({ uid: contact.uid, version: contact.version, favorite }, client);
 }
+/**
+ * The URL of a contact's own picture, or `undefined` when they have none. The version is part of it so a replaced picture is fetched again rather than
+ * served from the browser's cache.
+ */
+export function contactPhotoUrl(contact) {
+    return contact.photoBlobKey ? apiUrl(`/mail/contacts/${encodeURIComponent(contact.uid)}/photo?v=${contact.version}`) : undefined;
+}
+/** The picture types the server accepts for a contact, and the most bytes it takes. */
+export const CONTACT_PHOTO_TYPES = ["image/jpeg", "image/png", "image/gif", "image/webp"];
+export const CONTACT_PHOTO_MAX_BYTES = 1024 * 1024;
+/** Sets a contact's own picture from an image file (the file's own bytes go up, not JSON) and returns the updated contact. */
+export async function uploadContactPhoto(uid, version, file) {
+    const res = await fetch(apiUrl(`/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`), {
+        method: "PUT",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": file.type }, "PUT"),
+        body: file,
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+    if (!res.ok) {
+        throw new ApiRequestError((body && (body.message || body.error)) || res.statusText || "Upload failed.", res.status, body?.code);
+    }
+    return body;
+}
+/** Removes a contact's own picture and returns the updated contact. */
+export function deleteContactPhoto(uid, version, client) {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`, { method: "DELETE" });
+}
 export function deleteContact(uid, version, client) {
     return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
 }

package/dist/lib/contacts/gravatar.d.ts

@@ -0,0 +1,12 @@
+/** The `localStorage` key of the privacy preference: `"off"` stops contact avatars from asking Gravatar for a picture. */
+export declare const GRAVATAR_PREFERENCE_KEY = "rapidmx:gravatar";
+/**
+ * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). On unless the reader turned
+ * it off (`localStorage["rapidmx:gravatar"] = "off"`); a browser without storage keeps the default.
+ */
+export declare function gravatarEnabled(): boolean;
+/**
+ * The Gravatar picture URL for `email`, `size` pixels square. It answers `404` (`d=404`) for a person with no Gravatar, so an `<img>` fails to load
+ * and the caller falls back to initials rather than showing Gravatar's placeholder. `undefined` for an empty address or without Web Crypto.
+ */
+export declare function gravatarUrl(email: string, size: number): Promise<string | undefined>;

package/dist/lib/contacts/gravatar.js

@@ -0,0 +1,43 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** The `localStorage` key of the privacy preference: `"off"` stops contact avatars from asking Gravatar for a picture. */
+export const GRAVATAR_PREFERENCE_KEY = "rapidmx:gravatar";
+/**
+ * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). On unless the reader turned
+ * it off (`localStorage["rapidmx:gravatar"] = "off"`); a browser without storage keeps the default.
+ */
+export function gravatarEnabled() {
+    try {
+        return globalThis.localStorage?.getItem(GRAVATAR_PREFERENCE_KEY) !== "off";
+    }
+    catch {
+        return true;
+    }
+}
+const hashes = new Map();
+/** The lowercase-hex SHA-256 of a trimmed, lowercased `email`, or `undefined` where the browser has no Web Crypto (an insecure page). */
+function hashOf(email) {
+    const normalized = email.trim().toLowerCase();
+    let hash = hashes.get(normalized);
+    if (!hash) {
+        hash = (async () => {
+            const digest = await globalThis.crypto?.subtle?.digest("SHA-256", new TextEncoder().encode(normalized));
+            return digest && Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        })().catch(() => undefined);
+        hashes.set(normalized, hash);
+    }
+    return hash;
+}
+/**
+ * The Gravatar picture URL for `email`, `size` pixels square. It answers `404` (`d=404`) for a person with no Gravatar, so an `<img>` fails to load
+ * and the caller falls back to initials rather than showing Gravatar's placeholder. `undefined` for an empty address or without Web Crypto.
+ */
+export async function gravatarUrl(email, size) {
+    if (!email.trim()) {
+        return undefined;
+    }
+    const hash = await hashOf(email);
+    return hash && `https://gravatar.com/avatar/${hash}?s=${Math.max(1, Math.round(size))}&d=404`;
+}

package/dist/lib/mail/directoryApi.d.ts

@@ -1,12 +1,14 @@
 /**
  * Typed wrappers over `@rapidmx/restapi`'s `BaseDirectoryRoute` - recipient suggestions for compose. `GET
  * /mail/directory` searches the server's mailboxes (people, shared mailboxes, rooms and equipment) and distribution
- * lists; `GET /mail/directory/contacts` searches the caller's own contacts. Both match every word of the query against
- * the start of a name word or of an address, and return only a display name, an address and a kind.
+ * lists; `GET /mail/directory/contacts` searches the caller's own contacts; `GET /mail/directory/correspondents` searches
+ * everyone the caller's mailboxes have exchanged mail or shared an event with, address book or not. All match every word of
+ * the query against the start of a name word or of an address, and return only a display name, an address and a kind.
  */
 import { ApiClient } from "../util/api.js";
-/** What a suggestion names. `"contact"` comes from the caller's contacts, everything else from the server directory. */
-export type RecipientSuggestionKind = "user" | "shared" | "room" | "equipment" | "list" | "contact";
+/** What a suggestion names. `"contact"` comes from the caller's contacts, `"correspondent"` from the people they have written to, heard from or
+ * met with, everything else from the server directory. */
+export type RecipientSuggestionKind = "user" | "shared" | "room" | "equipment" | "list" | "contact" | "correspondent";
 export interface RecipientSuggestion {
     displayName: string;
     address: string;
@@ -38,12 +40,16 @@ export interface ContactSuggestionOptions extends RecipientSuggestionOptions {
 export declare function searchDirectory(query: string, options?: RecipientSuggestionOptions, client?: ApiClient): Promise<RecipientSuggestion[]>;
 /** Searches the caller's contacts (every address of a contact whose name matches, or the addresses that match). */
 export declare function searchContactSuggestions(query: string, options?: ContactSuggestionOptions, client?: ApiClient): Promise<RecipientSuggestion[]>;
-/** Contacts first, then directory entries, without repeating an address (compared case-insensitively; the first
- * occurrence wins), at most `limit`. */
-export declare function mergeRecipientSuggestions(contacts: RecipientSuggestion[], directory: RecipientSuggestion[], limit?: number): RecipientSuggestion[];
+/** Searches the people the caller's mailboxes have exchanged mail or shared an event with, whether or not they are in the address book. Rejects like
+ * `searchDirectory()`; a server that predates the endpoint answers 404, which `fetchRecipientSuggestions()` treats as "none". */
+export declare function searchCorrespondents(query: string, options?: ContactSuggestionOptions, client?: ApiClient): Promise<RecipientSuggestion[]>;
+/** Contacts first, then directory entries, then the people the caller has corresponded with, without repeating an address (compared
+ * case-insensitively; the first occurrence wins), at most `limit`. */
+export declare function mergeRecipientSuggestions(contacts: RecipientSuggestion[], directory: RecipientSuggestion[], limit?: number, correspondents?: RecipientSuggestion[]): RecipientSuggestion[];
 /**
- * Contacts and directory suggestions for `query`, merged by `mergeRecipientSuggestions()`. Either source failing (a 403
- * directory for a caller with no mailbox here, a 429, a network error) still returns the other's entries; only when
- * both fail does this reject, with the contacts error. An aborted `signal` always rejects with the `AbortError`.
+ * Contacts, directory and correspondent suggestions for `query`, merged by `mergeRecipientSuggestions()`. Any source failing (a 403
+ * directory for a caller with no mailbox here, a 429, a network error, a server without the correspondents endpoint) still returns
+ * the others' entries; only when the contacts and the directory both fail does this reject, with the contacts error - the
+ * correspondents are a bonus and never turn a working search into an error. An aborted `signal` always rejects with the `AbortError`.
  */
 export declare function fetchRecipientSuggestions(query: string, options?: ContactSuggestionOptions, client?: ApiClient): Promise<RecipientSuggestion[]>;

package/dist/lib/mail/directoryApi.js

@@ -5,8 +5,9 @@
 /**
  * Typed wrappers over `@rapidmx/restapi`'s `BaseDirectoryRoute` - recipient suggestions for compose. `GET
  * /mail/directory` searches the server's mailboxes (people, shared mailboxes, rooms and equipment) and distribution
- * lists; `GET /mail/directory/contacts` searches the caller's own contacts. Both match every word of the query against
- * the start of a name word or of an address, and return only a display name, an address and a kind.
+ * lists; `GET /mail/directory/contacts` searches the caller's own contacts; `GET /mail/directory/correspondents` searches
+ * everyone the caller's mailboxes have exchanged mail or shared an event with, address book or not. All match every word of
+ * the query against the start of a name word or of an address, and return only a display name, an address and a kind.
  */
 import { ApiRequestError, withClient } from "../util/api.js";
 /** The shortest trimmed query the server searches for - shorter ones resolve to `[]` without a request. */
@@ -58,12 +59,17 @@ export function searchDirectory(query, options = {}, client) {
 export function searchContactSuggestions(query, options = {}, client) {
     return fetchSuggestions("/mail/directory/contacts", query, { limit: options.limit?.toString(), mailboxUid: options.mailboxUid }, options.signal, client);
 }
-/** Contacts first, then directory entries, without repeating an address (compared case-insensitively; the first
- * occurrence wins), at most `limit`. */
-export function mergeRecipientSuggestions(contacts, directory, limit = RECIPIENT_SUGGESTION_DEFAULT_LIMIT) {
+/** Searches the people the caller's mailboxes have exchanged mail or shared an event with, whether or not they are in the address book. Rejects like
+ * `searchDirectory()`; a server that predates the endpoint answers 404, which `fetchRecipientSuggestions()` treats as "none". */
+export function searchCorrespondents(query, options = {}, client) {
+    return fetchSuggestions("/mail/directory/correspondents", query, { limit: options.limit?.toString(), mailboxUid: options.mailboxUid }, options.signal, client);
+}
+/** Contacts first, then directory entries, then the people the caller has corresponded with, without repeating an address (compared
+ * case-insensitively; the first occurrence wins), at most `limit`. */
+export function mergeRecipientSuggestions(contacts, directory, limit = RECIPIENT_SUGGESTION_DEFAULT_LIMIT, correspondents = []) {
     const seen = new Set();
     const result = [];
-    for (const entry of [...contacts, ...directory]) {
+    for (const entry of [...contacts, ...directory, ...correspondents]) {
         const key = entry.address.trim().toLowerCase();
         if (result.length >= limit) {
             break;
@@ -79,17 +85,19 @@ function isAbort(error) {
     return error?.name === "AbortError";
 }
 /**
- * Contacts and directory suggestions for `query`, merged by `mergeRecipientSuggestions()`. Either source failing (a 403
- * directory for a caller with no mailbox here, a 429, a network error) still returns the other's entries; only when
- * both fail does this reject, with the contacts error. An aborted `signal` always rejects with the `AbortError`.
+ * Contacts, directory and correspondent suggestions for `query`, merged by `mergeRecipientSuggestions()`. Any source failing (a 403
+ * directory for a caller with no mailbox here, a 429, a network error, a server without the correspondents endpoint) still returns
+ * the others' entries; only when the contacts and the directory both fail does this reject, with the contacts error - the
+ * correspondents are a bonus and never turn a working search into an error. An aborted `signal` always rejects with the `AbortError`.
  */
 export async function fetchRecipientSuggestions(query, options = {}, client) {
     const limit = options.limit ?? RECIPIENT_SUGGESTION_DEFAULT_LIMIT;
-    const [contacts, directory] = await Promise.allSettled([
+    const [contacts, directory, correspondents] = await Promise.allSettled([
         searchContactSuggestions(query, { ...options, limit }, client),
         searchDirectory(query, { limit, signal: options.signal }, client),
+        searchCorrespondents(query, { ...options, limit }, client),
     ]);
-    for (const outcome of [contacts, directory]) {
+    for (const outcome of [contacts, directory, correspondents]) {
         if (outcome.status === "rejected" && isAbort(outcome.reason)) {
             throw outcome.reason;
         }
@@ -97,5 +105,5 @@ export async function fetchRecipientSuggestions(query, options = {}, client) {
     if (contacts.status === "rejected" && directory.status === "rejected") {
         throw contacts.reason instanceof Error ? contacts.reason : new ApiRequestError("Suggestions couldn't be loaded.", 0);
     }
-    return mergeRecipientSuggestions(contacts.status === "fulfilled" ? contacts.value : [], directory.status === "fulfilled" ? directory.value : [], limit);
+    return mergeRecipientSuggestions(contacts.status === "fulfilled" ? contacts.value : [], directory.status === "fulfilled" ? directory.value : [], limit, correspondents.status === "fulfilled" ? correspondents.value : []);
 }

package/lib/components/avatar/ContactAvatar.tsx

@@ -2,16 +2,19 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import React from "react";
+import React, { useEffect, useState } from "react";
+import { gravatarEnabled, gravatarUrl } from "../../contacts/gravatar.js";
 
 export interface ContactAvatarProps {
     displayName: string;
     size?: number;
+    /** The contact's own picture (see `contactPhotoUrl()`); shown in preference to anything else. */
+    photoUrl?: string;
+    /** The contact's address: without a picture of their own, its Gravatar is shown when there is one (and the reader hasn't turned that off). */
+    email?: string;
 }
 
-/** A fixed palette of background colors, cycled by a hash of the contact's name — no photo upload feature
- * exists yet (`Contact.photoBlobKey` is modeled server-side but nothing in this app sets/reads it), so every
- * contact gets one of these deterministically rather than a plain generic gray circle for everyone. */
+/** A fixed palette of background colors, cycled by a hash of the contact's name, for the initials shown when there is no picture. */
 const PALETTE = ["#7c3aed", "#2563eb", "#0891b2", "#059669", "#d97706", "#dc2626", "#db2777", "#4f46e5"];
 
 function initialsOf(displayName: string): string {
@@ -32,9 +35,42 @@ function colorOf(displayName: string): string {
     return PALETTE[Math.abs(hash) % PALETTE.length];
 }
 
-/** A small circular initials avatar for a contact, matching Outlook People's list-row avatars — deterministic
- * per name (same contact always gets the same color/initials), no photo-upload dependency. */
-export default function ContactAvatar({ displayName, size = 32 }: ContactAvatarProps) {
+/**
+ * A small circular avatar for a contact, matching Outlook People's: the contact's own picture when they have one, else their Gravatar (when `email`
+ * is given), else initials on a color that is deterministic per name. A picture that fails to load falls through to the next.
+ */
+export default function ContactAvatar({ displayName, size = 32, photoUrl, email }: ContactAvatarProps) {
+    const [gravatar, setGravatar] = useState<string | undefined>();
+    const [failed, setFailed] = useState<string[]>([]);
+
+    useEffect(() => {
+        setGravatar(undefined);
+        if (!email || !gravatarEnabled()) {
+            return;
+        }
+        let cancelled = false;
+        void gravatarUrl(email, size * 2).then((url) => !cancelled && setGravatar(url));
+        return () => {
+            cancelled = true;
+        };
+    }, [email, size]);
+
+    const src = [photoUrl, gravatar].find((url) => url && !failed.includes(url));
+    if (src) {
+        return (
+            <img
+                src={src}
+                alt=""
+                aria-hidden="true"
+                width={size}
+                height={size}
+                referrerPolicy="no-referrer"
+                onError={() => setFailed((list) => [...list, src])}
+                className="inline-block rounded-full object-cover shrink-0"
+                style={{ width: size, height: size }}
+            />
+        );
+    }
     return (
         <span
             aria-hidden="true"

package/lib/components/buttons/CopyIconButton.tsx

@@ -0,0 +1,49 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import { HiCheck, HiOutlineClipboardDocument } from "react-icons/hi2";
+import useCopyToClipboard from "../../util/useCopyToClipboard.js";
+
+export interface CopyIconButtonProps {
+    /** The text put on the clipboard. */
+    value: string;
+    /** The button's accessible name and tooltip - say what is copied, e.g. "Copy address". */
+    label: string;
+    className?: string;
+}
+
+/**
+ * A small icon-only "copy" button to sit right after a value (an email address). The icon turns into a check mark for a moment once the value is on
+ * the clipboard, and a polite live region says "Copied" (or "Couldn't copy") for screen readers.
+ */
+export default function CopyIconButton({ value, label, className }: CopyIconButtonProps) {
+    const { status, copy } = useCopyToClipboard();
+
+    return (
+        <span className="inline-flex items-center align-middle">
+            <button
+                type="button"
+                aria-label={label}
+                title={label}
+                onClick={() => void copy(value)}
+                className={[
+                    "inline-flex items-center justify-center rounded-sm p-1 text-text-muted hover:text-text hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary",
+                    className,
+                ]
+                    .filter(Boolean)
+                    .join(" ")}
+            >
+                {status === "copied" ? (
+                    <HiCheck aria-hidden="true" className="size-4 text-success" />
+                ) : (
+                    <HiOutlineClipboardDocument aria-hidden="true" className="size-4" />
+                )}
+            </button>
+            <span role="status" aria-live="polite" className="sr-only">
+                {status === "copied" ? "Copied" : status === "failed" ? "Couldn’t copy" : ""}
+            </span>
+        </span>
+    );
+}

package/lib/contacts/contactsApi.ts

@@ -5,7 +5,7 @@
 /** Typed wrappers over `@rapidmx/restapi`'s `/mail/contacts` REST surface — see `mailApi.ts`'s own header
  * comment for the shared ACL/authorization model every wrapper file here follows. */
 
-import { ApiClient, withClient } from "../util/api.js";
+import { ApiClient, ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
 import { ListParams, buildQuery } from "../util/apiQuery.js";
 import {
     type EncryptionPreference,
@@ -109,7 +109,7 @@ export const PINNED_FINGERPRINT_MAX_PAGES = 20;
 
 /** Every contact in `folderUids`, paged (`PINNED_FINGERPRINT_PAGE_SIZE`, at most `PINNED_FINGERPRINT_MAX_PAGES` pages
  * per folder). A plain contacts read - never a Discovery lookup. */
-async function listContactsInFolders(folderUids: string[], client?: ApiClient): Promise<Contact[]> {
+export async function listContactsInFolders(folderUids: string[], client?: ApiClient): Promise<Contact[]> {
     const contacts: Contact[] = [];
     for (const folderUid of folderUids) {
         for (let page = 0; page < PINNED_FINGERPRINT_MAX_PAGES; page++) {
@@ -252,6 +252,39 @@ export function setContactFavorite(contact: Contact, favorite: boolean, client?:
     return updateContact({ uid: contact.uid, version: contact.version, favorite }, client);
 }
 
+/**
+ * The URL of a contact's own picture, or `undefined` when they have none. The version is part of it so a replaced picture is fetched again rather than
+ * served from the browser's cache.
+ */
+export function contactPhotoUrl(contact: Pick<Contact, "uid" | "version" | "photoBlobKey">): string | undefined {
+    return contact.photoBlobKey ? apiUrl(`/mail/contacts/${encodeURIComponent(contact.uid)}/photo?v=${contact.version}`) : undefined;
+}
+
+/** The picture types the server accepts for a contact, and the most bytes it takes. */
+export const CONTACT_PHOTO_TYPES = ["image/jpeg", "image/png", "image/gif", "image/webp"];
+export const CONTACT_PHOTO_MAX_BYTES = 1024 * 1024;
+
+/** Sets a contact's own picture from an image file (the file's own bytes go up, not JSON) and returns the updated contact. */
+export async function uploadContactPhoto(uid: string, version: number, file: Blob): Promise<Contact> {
+    const res = await fetch(apiUrl(`/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`), {
+        method: "PUT",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": file.type }, "PUT"),
+        body: file,
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+    if (!res.ok) {
+        throw new ApiRequestError((body && (body.message || body.error)) || res.statusText || "Upload failed.", res.status, body?.code);
+    }
+    return body as Contact;
+}
+
+/** Removes a contact's own picture and returns the updated contact. */
+export function deleteContactPhoto(uid: string, version: number, client?: ApiClient): Promise<Contact> {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`, { method: "DELETE" });
+}
+
 export function deleteContact(uid: string, version: number, client?: ApiClient): Promise<void> {
     return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
 }

package/lib/contacts/gravatar.ts

@@ -0,0 +1,47 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** The `localStorage` key of the privacy preference: `"off"` stops contact avatars from asking Gravatar for a picture. */
+export const GRAVATAR_PREFERENCE_KEY = "rapidmx:gravatar";
+
+/**
+ * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). On unless the reader turned
+ * it off (`localStorage["rapidmx:gravatar"] = "off"`); a browser without storage keeps the default.
+ */
+export function gravatarEnabled(): boolean {
+    try {
+        return globalThis.localStorage?.getItem(GRAVATAR_PREFERENCE_KEY) !== "off";
+    } catch {
+        return true;
+    }
+}
+
+const hashes = new Map<string, Promise<string | undefined>>();
+
+/** The lowercase-hex SHA-256 of a trimmed, lowercased `email`, or `undefined` where the browser has no Web Crypto (an insecure page). */
+function hashOf(email: string): Promise<string | undefined> {
+    const normalized = email.trim().toLowerCase();
+    let hash = hashes.get(normalized);
+    if (!hash) {
+        hash = (async () => {
+            const digest = await globalThis.crypto?.subtle?.digest("SHA-256", new TextEncoder().encode(normalized));
+            return digest && Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        })().catch(() => undefined);
+        hashes.set(normalized, hash);
+    }
+    return hash;
+}
+
+/**
+ * The Gravatar picture URL for `email`, `size` pixels square. It answers `404` (`d=404`) for a person with no Gravatar, so an `<img>` fails to load
+ * and the caller falls back to initials rather than showing Gravatar's placeholder. `undefined` for an empty address or without Web Crypto.
+ */
+export async function gravatarUrl(email: string, size: number): Promise<string | undefined> {
+    if (!email.trim()) {
+        return undefined;
+    }
+    const hash = await hashOf(email);
+    return hash && `https://gravatar.com/avatar/${hash}?s=${Math.max(1, Math.round(size))}&d=404`;
+}