more types and jmapq

bin/dune

···
  (package jmap-eio)
  (modules jmap)
  (libraries jmap-eio eio_main))
+
+(executable
+ (name jmapq)
+ (public_name jmapq)
+ (package jmap-eio)
+ (modules jmapq)
+ (libraries jmap-eio eio_main re jsont.bytesrw))

bin/jmap.ml

···
   |> List.filter_map (fun (k, v) -> if v then Some k else None)
   |> String.concat " "
 
+(* Helpers for optional Email fields *)
+let email_id (e : Jmap.Proto.Email.t) =
+  match e.id with Some id -> Jmap.Proto.Id.to_string id | None -> "?"
+
+let email_received_at (e : Jmap.Proto.Email.t) =
+  match e.received_at with Some t -> ptime_to_string t | None -> "?"
+
+let email_keywords (e : Jmap.Proto.Email.t) =
+  Option.value ~default:[] e.keywords
+
+let email_preview (e : Jmap.Proto.Email.t) =
+  Option.value ~default:"" e.preview
+
+let email_thread_id (e : Jmap.Proto.Email.t) =
+  match e.thread_id with Some id -> Jmap.Proto.Id.to_string id | None -> "?"
+
+let email_size (e : Jmap.Proto.Email.t) =
+  Option.value ~default:0L e.size
+
+let email_mailbox_ids (e : Jmap.Proto.Email.t) =
+  Option.value ~default:[] e.mailbox_ids
+
 (** {1 Session Command} *)
 
 let session_cmd =
···
               result.state;
             (* Sort by sort_order then name *)
             let sorted = List.sort (fun (a : Jmap.Proto.Mailbox.t) (b : Jmap.Proto.Mailbox.t) ->
-              let cmp = Int64.compare a.sort_order b.sort_order in
-              if cmp <> 0 then cmp else String.compare a.name b.name
+              let sort_a = Option.value ~default:0L a.sort_order in
+              let sort_b = Option.value ~default:0L b.sort_order in
+              let cmp = Int64.compare sort_a sort_b in
+              let name_a = Option.value ~default:"" a.name in
+              let name_b = Option.value ~default:"" b.name in
+              if cmp <> 0 then cmp else String.compare name_a name_b
             ) result.list in
             List.iter (fun (mbox : Jmap.Proto.Mailbox.t) ->
               let role_str = match mbox.role with
                 | Some role -> Printf.sprintf " [%s]" (Jmap.Proto.Mailbox.role_to_string role)
                 | None -> ""
               in
+              let id_str = match mbox.id with
+                | Some id -> Jmap.Proto.Id.to_string id
+                | None -> "?"
+              in
+              let name = Option.value ~default:"(unnamed)" mbox.name in
+              let total = Option.value ~default:0L mbox.total_emails in
+              let unread = Option.value ~default:0L mbox.unread_emails in
               Fmt.pr "  %a %s%a  (%Ld total, %Ld unread)@,"
-                Fmt.(styled `Cyan string) (Jmap.Proto.Id.to_string mbox.id)
-                mbox.name
+                Fmt.(styled `Cyan string) id_str
+                name
                 Fmt.(styled `Yellow string) role_str
-                mbox.total_emails mbox.unread_emails
+                total unread
             ) sorted;
             Fmt.pr "@]@."
   in
···
                           | None -> "(unknown)"
                         in
                         let subject = Option.value email.subject ~default:"(no subject)" in
-                        let flags = format_keywords email.keywords in
+                        let keywords = Option.value ~default:[] email.keywords in
+                        let flags = format_keywords keywords in
                         let flag_str = if flags = "" then "" else " [" ^ flags ^ "]" in
+                        let id_str = match email.id with
+                          | Some id -> Jmap.Proto.Id.to_string id
+                          | None -> "?"
+                        in
+                        let received = match email.received_at with
+                          | Some t -> ptime_to_string t
+                          | None -> "?"
+                        in
+                        let preview = Option.value ~default:"" email.preview in
                         Fmt.pr "  %a %s@,"
-                          Fmt.(styled `Cyan string) (Jmap.Proto.Id.to_string email.id)
-                          (ptime_to_string email.received_at);
+                          Fmt.(styled `Cyan string) id_str
+                          received;
                         Fmt.pr "    From: %s@," (truncate_string 60 from_str);
                         Fmt.pr "    Subject: %a%s@,"
                           Fmt.(styled `White string) (truncate_string 60 subject)
                           flag_str;
                         Fmt.pr "    Preview: %s@,@,"
-                          (truncate_string 70 email.preview);
+                          (truncate_string 70 preview);
                       ) get_result.list;
                       Fmt.pr "@]@."
             )
···
                           | None -> "(unknown)"
                         in
                         let subject = Option.value email.subject ~default:"(no subject)" in
+                        let id_str = match email.id with
+                          | Some id -> Jmap.Proto.Id.to_string id
+                          | None -> "?"
+                        in
+                        let received = match email.received_at with
+                          | Some t -> ptime_to_string t
+                          | None -> "?"
+                        in
+                        let preview = Option.value ~default:"" email.preview in
                         Fmt.pr "  %a %s@,"
-                          Fmt.(styled `Cyan string) (Jmap.Proto.Id.to_string email.id)
-                          (ptime_to_string email.received_at);
+                          Fmt.(styled `Cyan string) id_str
+                          received;
                         Fmt.pr "    From: %s@," (truncate_string 60 from_str);
                         Fmt.pr "    Subject: %a@,"
                           Fmt.(styled `White string) (truncate_string 60 subject);
                         Fmt.pr "    Preview: %s@,@,"
-                          (truncate_string 70 email.preview);
+                          (truncate_string 70 preview);
                       ) get_result.list;
                       Fmt.pr "@]@."
             )
···
                               | _ -> "?"
                             in
                             let subject = Option.value email.subject ~default:"(no subject)" in
-                            let flags = format_keywords email.keywords in
+                            let flags = format_keywords (email_keywords email) in
                             Printf.printf "%s\t%s\t%s\t%s\t%s\n"
-                              (Jmap.Proto.Id.to_string email.id)
-                              (ptime_to_string email.received_at)
+                              (email_id email)
+                              (email_received_at email)
                               (truncate_string 20 from_str)
                               (truncate_string 50 subject)
                               flags
···
                               | _ -> "?"
                             in
                             let subject = Option.value email.subject ~default:"(no subject)" in
-                            let flags = format_keywords email.keywords in
+                            let flags = format_keywords (email_keywords email) in
                             let id_short =
-                              let id = Jmap.Proto.Id.to_string email.id in
+                              let id = email_id email in
                               if String.length id > 12 then String.sub id 0 12 else id
                             in
                             Fmt.pr "%-12s  %s  %-20s  %-40s  %s@,"
                               id_short
-                              (ptime_to_string email.received_at)
+                              (email_received_at email)
                               (truncate_string 20 from_str)
                               (truncate_string 40 subject)
                               flags
···
                               | None -> ""
                             in
                             let subject = Option.value email.subject ~default:"(no subject)" in
-                            let flags = format_keywords email.keywords in
-                            let mailbox_count = List.length email.mailbox_ids in
+                            let flags = format_keywords (email_keywords email) in
+                            let mailbox_count = List.length (email_mailbox_ids email) in
 
                             Fmt.pr "@[<v 2>%a Email %d of %d@,"
                               Fmt.(styled `Bold string) "---"
                               (i + 1) (List.length get_result.list);
                             Fmt.pr "ID:       %a@,"
-                              Fmt.(styled `Cyan string) (Jmap.Proto.Id.to_string email.id);
-                            Fmt.pr "Thread:   %s@," (Jmap.Proto.Id.to_string email.thread_id);
-                            Fmt.pr "Date:     %s@," (ptime_to_string email.received_at);
+                              Fmt.(styled `Cyan string) (email_id email);
+                            Fmt.pr "Thread:   %s@," (email_thread_id email);
+                            Fmt.pr "Date:     %s@," (email_received_at email);
                             Fmt.pr "From:     %s@," from_str;
                             if to_str <> "" then Fmt.pr "To:       %s@," to_str;
                             if cc_str <> "" then Fmt.pr "Cc:       %s@," cc_str;
                             Fmt.pr "Subject:  %a@,"
                               Fmt.(styled `White string) subject;
-                            Fmt.pr "Size:     %Ld bytes@," email.size;
+                            Fmt.pr "Size:     %Ld bytes@," (email_size email);
                             Fmt.pr "Mailboxes: %d@," mailbox_count;
                             if flags <> "" then Fmt.pr "Flags:    %s@," flags;
-                            Fmt.pr "Preview:  %s@]@,@," email.preview;
+                            Fmt.pr "Preview:  %s@]@,@," (email_preview email);
                           ) get_result.list;
                           Fmt.pr "@]@."
             )
···
     let client = Jmap_eio.Cli.create_client ~sw env cfg in
     let account_id = Jmap_eio.Cli.get_account_id cfg client in
 
-    let email_id = Jmap.Proto.Id.of_string_exn email_id_str in
+    let target_email_id = Jmap.Proto.Id.of_string_exn email_id_str in
 
     (* First get the email to find its thread ID - include required properties *)
     let get_inv = Jmap_eio.Client.Build.email_get
       ~call_id:"e1"
       ~account_id
-      ~ids:[email_id]
+      ~ids:[target_email_id]
       ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "size"; "receivedAt"]
       ()
     in
···
                 Fmt.epr "Email not found: %s@." email_id_str;
                 exit 1
             | email :: _ ->
-                let thread_id = email.thread_id in
+                let thread_id = match email.thread_id with
+                  | Some id -> id
+                  | None ->
+                      Fmt.epr "Email has no thread ID@.";
+                      exit 1
+                in
                 Jmap_eio.Cli.debug cfg "Thread ID: %s" (Jmap.Proto.Id.to_string thread_id);
 
                 (* Get the thread *)
···
                             Fmt.epr "Thread not found@.";
                             exit 1
                         | thread :: _ ->
-                            let email_ids = thread.email_ids in
+                            let thread_id_str = match thread.id with
+                              | Some id -> Jmap.Proto.Id.to_string id
+                              | None -> "?"
+                            in
+                            let email_ids = Option.value ~default:[] thread.email_ids in
                             Fmt.pr "@[<v>%a %s (%d emails)@,@,"
                               Fmt.(styled `Bold string) "Thread"
-                              (Jmap.Proto.Id.to_string thread.id)
+                              thread_id_str
                               (List.length email_ids);
 
                             (* Fetch all emails in thread *)
···
                                       in
                                       let subject = Option.value email.subject ~default:"(no subject)" in
                                       Fmt.pr "  %a %s@,"
-                                        Fmt.(styled `Cyan string) (Jmap.Proto.Id.to_string email.id)
-                                        (ptime_to_string email.received_at);
+                                        Fmt.(styled `Cyan string) (email_id email)
+                                        (email_received_at email);
                                       Fmt.pr "    From: %s@," (truncate_string 60 from_str);
                                       Fmt.pr "    Subject: %a@,@,"
                                         Fmt.(styled `White string) (truncate_string 60 subject);
···
               Fmt.(styled `Bold string) "Identities"
               result.state;
             List.iter (fun (ident : Jmap.Proto.Identity.t) ->
+              let ident_id = match ident.id with Some id -> Jmap.Proto.Id.to_string id | None -> "?" in
+              let ident_name = Option.value ~default:"(unnamed)" ident.name in
+              let ident_email = Option.value ~default:"(no email)" ident.email in
+              let ident_sig = Option.value ~default:"" ident.text_signature in
+              let ident_may_delete = Option.value ~default:false ident.may_delete in
               Fmt.pr "  %a@,"
-                Fmt.(styled `Cyan string) (Jmap.Proto.Id.to_string ident.id);
-              Fmt.pr "    Name: %s@," ident.name;
+                Fmt.(styled `Cyan string) ident_id;
+              Fmt.pr "    Name: %s@," ident_name;
               Fmt.pr "    Email: %a@,"
-                Fmt.(styled `Green string) ident.email;
-              if ident.text_signature <> "" then
-                Fmt.pr "    Signature: %s@," (truncate_string 50 ident.text_signature);
-              Fmt.pr "    May delete: %b@,@," ident.may_delete
+                Fmt.(styled `Green string) ident_email;
+              if ident_sig <> "" then
+                Fmt.pr "    Signature: %s@," (truncate_string 50 ident_sig);
+              Fmt.pr "    May delete: %b@,@," ident_may_delete
             ) result.list;
             Fmt.pr "@]@."
   in
···
                 Fmt.epr "No inbox found@.";
                 exit 1
             | Some inbox ->
-                Jmap_eio.Cli.debug cfg "Found inbox: %s" (Jmap.Proto.Id.to_string inbox.id);
+                let inbox_id = match inbox.id with
+                  | Some id -> id
+                  | None ->
+                      Fmt.epr "Inbox has no ID@.";
+                      exit 1
+                in
+                Jmap_eio.Cli.debug cfg "Found inbox: %s" (Jmap.Proto.Id.to_string inbox_id);
 
                 (* Now use Chain API to query and get emails in one request *)
                 let open Jmap_eio.Chain in
                 let filter_cond : Jmap.Proto.Email.Filter_condition.t = {
-                  in_mailbox = Some inbox.id;
+                  in_mailbox = Some inbox_id;
                   in_mailbox_other_than = None;
                   before = None; after = None;
                   min_size = None; max_size = None;
···
                             | _ -> "?"
                           in
                           let subject = Option.value email.subject ~default:"(no subject)" in
-                          let flags = format_keywords email.keywords in
+                          let flags = format_keywords (email_keywords email) in
                           Fmt.pr "  %a %s@,"
-                            Fmt.(styled `Cyan string) (Jmap.Proto.Id.to_string email.id)
-                            (ptime_to_string email.received_at);
+                            Fmt.(styled `Cyan string) (email_id email)
+                            (email_received_at email);
                           Fmt.pr "    From: %s@," (truncate_string 40 from_str);
                           Fmt.pr "    Subject: %a%s@,"
                             Fmt.(styled `White string) (truncate_string 50 subject)
···
         (* Group emails by thread *)
         let threads_map = Hashtbl.create 16 in
         List.iter (fun (email : Jmap.Proto.Email.t) ->
-          let tid = Jmap.Proto.Id.to_string email.thread_id in
+          let tid = email_thread_id email in
           let existing = try Hashtbl.find threads_map tid with Not_found -> [] in
           Hashtbl.replace threads_map tid (email :: existing)
         ) emails_result.list;
···
         (* Print threads *)
         Hashtbl.iter (fun _tid emails ->
           let emails = List.sort (fun (a : Jmap.Proto.Email.t) (b : Jmap.Proto.Email.t) ->
-            Ptime.compare a.received_at b.received_at
+            let a_time = Option.value ~default:Ptime.epoch a.received_at in
+            let b_time = Option.value ~default:Ptime.epoch b.received_at in
+            Ptime.compare a_time b_time
           ) emails in
           let first_email = List.hd emails in
           let subject = Option.value first_email.subject ~default:"(no subject)" in
···
               | _ -> "?"
             in
             Fmt.pr "      %s  %s  %s@,"
-              (Jmap.Proto.Id.to_string email.id |> truncate_string 12)
-              (ptime_to_string email.received_at)
+              (email_id email |> truncate_string 12)
+              (email_received_at email)
               (truncate_string 30 from_str)
           ) emails;
           Fmt.pr "@,"
···
             in
             let subject = Option.value email.subject ~default:"(no subject)" in
             Fmt.pr "  + %s  %s  %s@,"
-              (Jmap.Proto.Id.to_string email.id |> truncate_string 12)
+              (email_id email |> truncate_string 12)
               (truncate_string 20 from_str)
               (truncate_string 40 subject)
           ) created_result.list;
···
             Fmt.(styled `Yellow string) "Updated emails"
             (List.length updated_result.list);
           List.iter (fun (email : Jmap.Proto.Email.t) ->
-            let flags = format_keywords email.keywords in
+            let flags = format_keywords (email_keywords email) in
             Fmt.pr "  ~ %s  [%s]@,"
-              (Jmap.Proto.Id.to_string email.id |> truncate_string 12)
+              (email_id email |> truncate_string 12)
               flags
           ) updated_result.list;
           Fmt.pr "@,"
···
   let info = Cmd.info "sync" ~doc in
   Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ state_term)
 
+(** Headers command - demonstrates RFC 8621 §4.1 header property queries *)
+let headers_cmd =
+  let email_id_term =
+    let doc = "Email ID to get headers for" in
+    Arg.(required & pos 0 (some string) None & info [] ~docv:"EMAIL_ID" ~doc)
+  in
+
+  (* Format a header value for display *)
+  let format_header_value = function
+    | Jmap.Proto.Email_header.String_single None -> "(null)"
+    | Jmap.Proto.Email_header.String_single (Some s) -> s
+    | Jmap.Proto.Email_header.String_all [] -> "(empty list)"
+    | Jmap.Proto.Email_header.String_all strs -> String.concat "; " strs
+    | Jmap.Proto.Email_header.Addresses_single None -> "(null)"
+    | Jmap.Proto.Email_header.Addresses_single (Some []) -> "(empty)"
+    | Jmap.Proto.Email_header.Addresses_single (Some addrs) ->
+        String.concat ", " (List.map (fun a ->
+          match a.Jmap.Proto.Email_address.name with
+          | Some n -> Printf.sprintf "%s <%s>" n a.email
+          | None -> a.email
+        ) addrs)
+    | Jmap.Proto.Email_header.Addresses_all [] -> "(empty list)"
+    | Jmap.Proto.Email_header.Addresses_all groups ->
+        String.concat " | " (List.map (fun addrs ->
+          String.concat ", " (List.map (fun a ->
+            match a.Jmap.Proto.Email_address.name with
+            | Some n -> Printf.sprintf "%s <%s>" n a.email
+            | None -> a.email
+          ) addrs)
+        ) groups)
+    | Jmap.Proto.Email_header.Grouped_single None -> "(null)"
+    | Jmap.Proto.Email_header.Grouped_single (Some groups) ->
+        String.concat "; " (List.map (fun g ->
+          let name = Option.value ~default:"(ungrouped)" g.Jmap.Proto.Email_address.Group.name in
+          let addrs = String.concat ", " (List.map (fun a ->
+            match a.Jmap.Proto.Email_address.name with
+            | Some n -> Printf.sprintf "%s <%s>" n a.email
+            | None -> a.email
+          ) g.addresses) in
+          Printf.sprintf "%s: %s" name addrs
+        ) groups)
+    | Jmap.Proto.Email_header.Grouped_all _ -> "(grouped addresses list)"
+    | Jmap.Proto.Email_header.Date_single None -> "(null)"
+    | Jmap.Proto.Email_header.Date_single (Some t) -> ptime_to_string t
+    | Jmap.Proto.Email_header.Date_all [] -> "(empty list)"
+    | Jmap.Proto.Email_header.Date_all dates ->
+        String.concat "; " (List.map (function
+          | None -> "(null)"
+          | Some t -> ptime_to_string t
+        ) dates)
+    | Jmap.Proto.Email_header.Strings_single None -> "(null)"
+    | Jmap.Proto.Email_header.Strings_single (Some []) -> "(empty)"
+    | Jmap.Proto.Email_header.Strings_single (Some strs) -> String.concat ", " strs
+    | Jmap.Proto.Email_header.Strings_all [] -> "(empty list)"
+    | Jmap.Proto.Email_header.Strings_all groups ->
+        String.concat " | " (List.map (function
+          | None -> "(null)"
+          | Some strs -> String.concat ", " strs
+        ) groups)
+  in
+
+  let run cfg email_id_str =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+    let target_email_id = Jmap.Proto.Id.of_string_exn email_id_str in
+
+    Jmap_eio.Cli.debug cfg "Fetching headers for email %s" email_id_str;
+
+    (* Demonstrate various header forms from RFC 8621 §4.1.2:
+       - header:name         - Raw value
+       - header:name:asText  - Text decoded
+       - header:name:asAddresses - Address list
+       - header:name:asGroupedAddresses - Address groups
+       - header:name:asMessageIds - Message-ID list
+       - header:name:asDate  - RFC 3339 date
+       - header:name:asURLs  - URL list
+       - header:name:all     - All values (not just first)
+    *)
+    let header_props = [
+      (* Raw and text forms *)
+      "header:Subject";
+      "header:Subject:asText";
+      (* Address headers *)
+      "header:From:asAddresses";
+      "header:To:asAddresses";
+      "header:Cc:asAddresses";
+      "header:Bcc:asAddresses";
+      "header:Reply-To:asAddresses";
+      "header:Sender:asAddresses";
+      (* Grouped addresses *)
+      "header:From:asGroupedAddresses";
+      (* Message ID headers *)
+      "header:Message-ID:asMessageIds";
+      "header:In-Reply-To:asMessageIds";
+      "header:References:asMessageIds";
+      (* Date header *)
+      "header:Date:asDate";
+      (* List headers as URLs *)
+      "header:List-Unsubscribe:asURLs";
+      "header:List-Post:asURLs";
+      "header:List-Archive:asURLs";
+      (* Custom headers *)
+      "header:X-Mailer:asText";
+      "header:X-Priority";
+      "header:X-Spam-Status:asText";
+      "header:Content-Type";
+      "header:MIME-Version";
+      (* Get all Received headers (typically multiple) *)
+      "header:Received:all";
+    ] in
+
+    let properties = "id" :: "threadId" :: "subject" :: header_props in
+
+    let get_inv = Jmap_eio.Client.Build.email_get
+      ~call_id:"h1"
+      ~account_id
+      ~ids:[target_email_id]
+      ~properties
+      ()
+    in
+    let req = Jmap_eio.Client.Build.(
+      make_request
+        ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+        [get_inv]
+    ) in
+
+    match Jmap_eio.Client.request client req with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok response ->
+        match Jmap_eio.Client.Parse.parse_email_get ~call_id:"h1" response with
+        | Error e ->
+            Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+            exit 1
+        | Ok email_result ->
+            match email_result.list with
+            | [] ->
+                Fmt.epr "Email not found: %s@." email_id_str;
+                exit 1
+            | email :: _ ->
+                Fmt.pr "@[<v>%a@," Fmt.(styled `Bold string) "Email Headers (RFC 8621 §4.1)";
+                Fmt.pr "ID: %s@," (email_id email);
+                Fmt.pr "Thread: %s@," (email_thread_id email);
+                (match email.subject with
+                 | Some s -> Fmt.pr "Subject (convenience): %s@," s
+                 | None -> ());
+                Fmt.pr "@,";
+
+                (* Print dynamic headers grouped by category *)
+                let raw_headers = Jmap.Proto.Email.dynamic_headers_raw email in
+                if raw_headers = [] then
+                  Fmt.pr "%a@," Fmt.(styled `Yellow string) "No dynamic headers returned"
+                else begin
+                  Fmt.pr "%a (%d properties)@,@,"
+                    Fmt.(styled `Bold string) "Dynamic Header Properties"
+                    (List.length raw_headers);
+
+                  List.iter (fun (name, json) ->
+                    match Jmap.Proto.Email.decode_header_value name json with
+                    | None ->
+                        Fmt.pr "  %a: (decode failed)@,"
+                          Fmt.(styled `Red string) name
+                    | Some value ->
+                        let formatted = format_header_value value in
+                        if String.length formatted > 80 then
+                          Fmt.pr "  %a:@,    %s@,"
+                            Fmt.(styled `Cyan string) name
+                            formatted
+                        else
+                          Fmt.pr "  %a: %s@,"
+                            Fmt.(styled `Cyan string) name
+                            formatted
+                  ) raw_headers
+                end;
+                Fmt.pr "@]@."
+  in
+  let doc = "Show email headers in various forms (demonstrates RFC 8621 §4.1)" in
+  let info = Cmd.info "headers" ~doc in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ email_id_term)
+
 (** {1 Main Command Group} *)
 
 let main_cmd =
···
     recent_cmd;
     threads_cmd;
     identities_cmd;
+    headers_cmd;
     (* Chain API examples *)
     inbox_cmd;
     thread_view_cmd;

bin/jmapq.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** JMAPQ - Specialist JMAP workflow commands *)
+
+open Cmdliner
+
+(** {1 Helpers} *)
+
+let ptime_to_string t =
+  let (y, m, d), ((hh, mm, ss), _tz) = Ptime.to_date_time t in
+  Printf.sprintf "%04d-%02d-%02d %02d:%02d:%02d" y m d hh mm ss
+
+let truncate_string max_len s =
+  if String.length s <= max_len then s
+  else String.sub s 0 (max_len - 3) ^ "..."
+
+(** {1 Zulip Types and Codec} *)
+
+(** Parsed information from a Zulip notification email subject.
+    Subject format: "#Channel > topic [Server Name]" *)
+module Zulip_message = struct
+  type t = {
+    id : string;
+    date : Ptime.t;
+    thread_id : string;
+    channel : string;
+    topic : string;
+    server : string;
+    is_read : bool;
+    labels : string list;
+  }
+
+  (** Parse a Zulip subject line of the form "#Channel > topic [Server Name]" *)
+  let parse_subject subject =
+    (* Pattern: #<channel> > <topic> [<server>] *)
+    let channel_re = Re.Pcre.regexp {|^#(.+?)\s*>\s*(.+?)\s*\[(.+?)\]$|} in
+    match Re.exec_opt channel_re subject with
+    | Some groups ->
+        let channel = Re.Group.get groups 1 in
+        let topic = Re.Group.get groups 2 in
+        let server = Re.Group.get groups 3 in
+        Some (channel, topic, server)
+    | None -> None
+
+  (** Check if an email has the $seen keyword *)
+  let is_seen keywords =
+    List.exists (fun (k, v) -> k = "$seen" && v) keywords
+
+  (** Extract label strings from keywords, excluding standard JMAP keywords *)
+  let extract_labels keywords =
+    keywords
+    |> List.filter_map (fun (k, v) ->
+        if v && not (String.length k > 0 && k.[0] = '$') then
+          Some k
+        else if v && k = "$flagged" then
+          Some "flagged"
+        else
+          None)
+
+  (** Create a Zulip_message from a JMAP Email *)
+  let of_email (email : Jmap.Proto.Email.t) : t option =
+    let id = match email.id with
+      | Some id -> Jmap.Proto.Id.to_string id
+      | None -> ""
+    in
+    let date = match email.received_at with
+      | Some t -> t
+      | None -> Ptime.epoch
+    in
+    let thread_id = match email.thread_id with
+      | Some id -> Jmap.Proto.Id.to_string id
+      | None -> ""
+    in
+    let subject = Option.value ~default:"" email.subject in
+    match parse_subject subject with
+    | None -> None
+    | Some (channel, topic, server) ->
+        let keywords = Option.value ~default:[] email.keywords in
+        let is_read = is_seen keywords in
+        let labels = extract_labels keywords in
+        Some { id; date; thread_id; channel; topic; server; is_read; labels }
+
+  (** Jsont codec for Ptime.t - reuse the library's UTC date codec *)
+  let ptime_jsont : Ptime.t Jsont.t = Jmap.Proto.Date.Utc.jsont
+
+  (** Jsont codec for a single Zulip message *)
+  let jsont : t Jsont.t =
+    let kind = "ZulipMessage" in
+    let make id date thread_id channel topic server is_read labels =
+      { id; date; thread_id; channel; topic; server; is_read; labels }
+    in
+    Jsont.Object.map ~kind make
+    |> Jsont.Object.mem "id" Jsont.string ~enc:(fun t -> t.id)
+    |> Jsont.Object.mem "date" ptime_jsont ~enc:(fun t -> t.date)
+    |> Jsont.Object.mem "thread_id" Jsont.string ~enc:(fun t -> t.thread_id)
+    |> Jsont.Object.mem "channel" Jsont.string ~enc:(fun t -> t.channel)
+    |> Jsont.Object.mem "topic" Jsont.string ~enc:(fun t -> t.topic)
+    |> Jsont.Object.mem "server" Jsont.string ~enc:(fun t -> t.server)
+    |> Jsont.Object.mem "is_read" Jsont.bool ~enc:(fun t -> t.is_read)
+    |> Jsont.Object.mem "labels" (Jsont.list Jsont.string) ~enc:(fun t -> t.labels)
+    |> Jsont.Object.finish
+
+  (** Jsont codec for a list of Zulip messages *)
+  let list_jsont : t list Jsont.t = Jsont.list jsont
+end
+
+(** {1 Zulip List Command} *)
+
+let zulip_list_cmd =
+  let json_term =
+    let doc = "Output as JSON" in
+    Arg.(value & flag & info ["json"] ~doc)
+  in
+  let limit_term =
+    let doc = "Maximum number of messages to fetch (default: all)" in
+    Arg.(value & opt (some int) None & info ["limit"; "n"] ~docv:"N" ~doc)
+  in
+  let run cfg json_output limit =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+
+    Jmap_eio.Cli.debug cfg "Searching for Zulip notification emails";
+
+    (* Build filter for emails from [e-mail] *)
+    let cond : Jmap.Proto.Email.Filter_condition.t = {
+      in_mailbox = None; in_mailbox_other_than = None;
+      before = None; after = None;
+      min_size = None; max_size = None;
+      all_in_thread_have_keyword = None;
+      some_in_thread_have_keyword = None;
+      none_in_thread_have_keyword = None;
+      has_keyword = None; not_keyword = None;
+      has_attachment = None;
+      text = None;
+      from = Some "[e-mail]";
+      to_ = None;
+      cc = None; bcc = None; subject = None;
+      body = None; header = None;
+    } in
+    let filter = Jmap.Proto.Filter.Condition cond in
+    let sort = [Jmap.Proto.Filter.comparator ~is_ascending:false "receivedAt"] in
+
+    (* Query for all Zulip emails *)
+    let query_limit = match limit with
+      | Some n -> Int64.of_int n
+      | None -> Int64.of_int 10000  (* Large default to get "all" *)
+    in
+    let query_inv = Jmap_eio.Client.Build.email_query
+      ~call_id:"q1"
+      ~account_id
+      ~filter
+      ~sort
+      ~limit:query_limit
+      ()
+    in
+
+    let req = Jmap_eio.Client.Build.(
+      make_request
+        ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+        [query_inv]
+    ) in
+
+    match Jmap_eio.Client.request client req with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok response ->
+        match Jmap_eio.Client.Parse.parse_email_query ~call_id:"q1" response with
+        | Error e ->
+            Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+            exit 1
+        | Ok query_result ->
+            let email_ids = query_result.ids in
+            Jmap_eio.Cli.debug cfg "Found %d Zulip email IDs" (List.length email_ids);
+
+            if List.length email_ids = 0 then (
+              if json_output then
+                Fmt.pr "[]@."
+              else
+                Fmt.pr "No Zulip notification emails found.@."
+            ) else (
+              (* Fetch email details *)
+              let get_inv = Jmap_eio.Client.Build.email_get
+                ~call_id:"g1"
+                ~account_id
+                ~ids:email_ids
+                ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "keywords";
+                             "size"; "receivedAt"; "subject"; "from"]
+                ()
+              in
+              let req2 = Jmap_eio.Client.Build.(
+                make_request
+                  ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+                  [get_inv]
+              ) in
+
+              match Jmap_eio.Client.request client req2 with
+              | Error e ->
+                  Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+                  exit 1
+              | Ok response2 ->
+                  match Jmap_eio.Client.Parse.parse_email_get ~call_id:"g1" response2 with
+                  | Error e ->
+                      Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+                      exit 1
+                  | Ok get_result ->
+                      (* Parse Zulip subjects and filter successful parses *)
+                      let zulip_messages =
+                        get_result.list
+                        |> List.filter_map Zulip_message.of_email
+                      in
+
+                      Jmap_eio.Cli.debug cfg "Parsed %d Zulip messages from %d emails"
+                        (List.length zulip_messages)
+                        (List.length get_result.list);
+
+                      if json_output then (
+                        (* Output as JSON *)
+                        match Jsont_bytesrw.encode_string' ~format:Jsont.Indent Zulip_message.list_jsont zulip_messages with
+                        | Ok json_str -> Fmt.pr "%s@." json_str
+                        | Error e -> Fmt.epr "JSON encoding error: %s@." (Jsont.Error.to_string e)
+                      ) else (
+                        (* Human-readable output *)
+                        Fmt.pr "@[<v>%a (%d messages)@,@,"
+                          Fmt.(styled `Bold string) "Zulip Notifications"
+                          (List.length zulip_messages);
+
+                        (* Group by server, then by channel *)
+                        let by_server = Hashtbl.create 8 in
+                        List.iter (fun (msg : Zulip_message.t) ->
+                          let existing = try Hashtbl.find by_server msg.server with Not_found -> [] in
+                          Hashtbl.replace by_server msg.server (msg :: existing)
+                        ) zulip_messages;
+
+                        Hashtbl.iter (fun server msgs ->
+                          Fmt.pr "%a [%s]@,"
+                            Fmt.(styled `Bold string) "Server:"
+                            server;
+
+                          (* Group by channel within server *)
+                          let by_channel = Hashtbl.create 8 in
+                          List.iter (fun (msg : Zulip_message.t) ->
+                            let existing = try Hashtbl.find by_channel msg.channel with Not_found -> [] in
+                            Hashtbl.replace by_channel msg.channel (msg :: existing)
+                          ) msgs;
+
+                          Hashtbl.iter (fun channel channel_msgs ->
+                            Fmt.pr "  %a #%s (%d)@,"
+                              Fmt.(styled `Cyan string) "Channel:"
+                              channel
+                              (List.length channel_msgs);
+
+                            (* Sort by date descending *)
+                            let sorted = List.sort (fun a b ->
+                              Ptime.compare b.Zulip_message.date a.Zulip_message.date
+                            ) channel_msgs in
+
+                            List.iter (fun (msg : Zulip_message.t) ->
+                              let read_marker = if msg.is_read then " " else "*" in
+                              let labels_str = match msg.labels with
+                                | [] -> ""
+                                | ls -> " [" ^ String.concat ", " ls ^ "]"
+                              in
+                              Fmt.pr "    %s %s  %a  %s%s@,"
+                                read_marker
+                                (ptime_to_string msg.date)
+                                Fmt.(styled `Yellow string) (truncate_string 40 msg.topic)
+                                (truncate_string 12 msg.id)
+                                labels_str
+                            ) sorted;
+                            Fmt.pr "@,"
+                          ) by_channel
+                        ) by_server;
+
+                        Fmt.pr "@]@."
+                      )
+            )
+  in
+  let doc = "List Zulip notification emails with parsed channel/topic info" in
+  let man = [
+    `S Manpage.s_description;
+    `P "Lists all emails from [e-mail] and parses the subject line to extract \
+        the Zulip channel, topic, and server name.";
+    `P "Subject format expected: \"#Channel > topic [Server Name]\"";
+    `S Manpage.s_examples;
+    `P "List all Zulip notifications:";
+    `Pre "  jmapq zulip-list";
+    `P "Output as JSON:";
+    `Pre "  jmapq zulip-list --json";
+    `P "Limit to 50 most recent:";
+    `Pre "  jmapq zulip-list -n 50";
+  ] in
+  let info = Cmd.info "zulip-list" ~doc ~man in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ json_term $ limit_term)
+
+(** {1 Zulip Timeout Command} *)
+
+(** The keyword used to mark Zulip notifications as processed *)
+let zulip_processed_keyword = "zulip-processed"
+
+let zulip_timeout_cmd =
+  let email_ids_term =
+    let doc = "Email IDs to mark as processed" in
+    Arg.(non_empty & pos_all string [] & info [] ~docv:"EMAIL_ID" ~doc)
+  in
+  let run cfg email_id_strs =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+    let email_ids = List.map Jmap.Proto.Id.of_string_exn email_id_strs in
+
+    Jmap_eio.Cli.debug cfg "Marking %d email(s) with '%s' keyword"
+      (List.length email_ids) zulip_processed_keyword;
+
+    (* Build patch to add the zulip-processed keyword *)
+    let patch =
+      let open Jmap_eio.Chain in
+      json_obj [("keywords/" ^ zulip_processed_keyword, json_bool true)]
+    in
+
+    (* Build updates list: each email ID gets the same patch *)
+    let updates = List.map (fun id -> (id, patch)) email_ids in
+
+    let open Jmap_eio.Chain in
+    let request, set_h = build
+      ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+    begin
+      email_set ~account_id
+        ~update:updates
+        ()
+    end in
+
+    match Jmap_eio.Client.request client request with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok response ->
+        (* Check for JMAP method-level errors first *)
+        let call_id = Jmap_eio.Chain.call_id set_h in
+        (match Jmap.Proto.Response.find_response call_id response with
+        | None ->
+            Fmt.epr "Error: No response found for call_id %s@." call_id;
+            exit 1
+        | Some inv when Jmap.Proto.Response.is_error inv ->
+            (match Jmap.Proto.Response.get_error inv with
+            | Some err ->
+                Fmt.epr "JMAP Error: %s%s@."
+                  (Jmap.Proto.Error.method_error_type_to_string err.type_)
+                  (match err.description with Some d -> " - " ^ d | None -> "");
+                exit 1
+            | None ->
+                Fmt.epr "JMAP Error: Unknown error@.";
+                exit 1)
+        | Some _ ->
+            match parse set_h response with
+            | Error e ->
+                Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+                exit 1
+            | Ok result ->
+            (* Report successes *)
+            let updated_ids =
+              result.updated
+              |> Option.value ~default:[]
+              |> List.map (fun (id, _) -> Jmap.Proto.Id.to_string id)
+            in
+            if List.length updated_ids > 0 then begin
+              Fmt.pr "@[<v>%a %d email(s) with '%s':@,"
+                Fmt.(styled `Green string) "Marked"
+                (List.length updated_ids)
+                zulip_processed_keyword;
+              List.iter (fun id -> Fmt.pr "  %s@," id) updated_ids;
+              Fmt.pr "@]@."
+            end;
+
+            (* Report failures *)
+            let not_updated = Option.value ~default:[] result.not_updated in
+            if not_updated <> [] then begin
+              Fmt.epr "@[<v>%a to mark %d email(s):@,"
+                Fmt.(styled `Red string) "Failed"
+                (List.length not_updated);
+              List.iter (fun (id, err) ->
+                let open Jmap.Proto.Error in
+                let err_type = set_error_type_to_string err.type_ in
+                let err_desc = Option.value ~default:"" err.description in
+                Fmt.epr "  %s: %s%s@,"
+                  (Jmap.Proto.Id.to_string id)
+                  err_type
+                  (if err_desc = "" then "" else " - " ^ err_desc)
+              ) not_updated;
+              Fmt.epr "@]@.";
+              exit 1
+            end)
+  in
+  let doc = "Mark Zulip notification emails as processed" in
+  let man = [
+    `S Manpage.s_description;
+    `P (Printf.sprintf "Adds the '%s' keyword to the specified email(s). \
+        This keyword can be used to filter processed Zulip notifications \
+        or set up server-side rules to auto-archive them."
+        zulip_processed_keyword);
+    `S Manpage.s_examples;
+    `P "Mark a single email as processed:";
+    `Pre "  jmapq zulip-timeout StrrDTS_WEa3";
+    `P "Mark multiple emails as processed:";
+    `Pre "  jmapq zulip-timeout StrrDTS_WEa3 StrsGZ7P8Dpc StrsGuCSXJ3Z";
+  ] in
+  let info = Cmd.info "zulip-timeout" ~doc ~man in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ email_ids_term)
+
+(** {1 Main Command Group} *)
+
+let main_cmd =
+  let doc = "JMAPQ - Specialist JMAP workflow commands" in
+  let man = [
+    `S Manpage.s_description;
+    `P "A collection of specialist workflow commands for JMAP email processing.";
+    `S Manpage.s_environment;
+    `P Jmap_eio.Cli.env_docs;
+  ] in
+  let info = Cmd.info "jmapq" ~version:"0.1.0" ~doc ~man in
+  Cmd.group info [
+    zulip_list_cmd;
+    zulip_timeout_cmd;
+  ]
+
+let () =
+  Fmt_tty.setup_std_outputs ();
+  exit (Cmd.eval main_cmd)

doc/dune

···
+(mdx
+ (files tutorial.mld)
+ (libraries jmap jmap_top jsont jsont.bytesrw))
+
+(documentation
+ (package jmap)
+ (mld_files index tutorial))

doc/index.mld

···
+{0 jmap}
+
+{!modules: Jmap Jmap_top}
+
+{1 Tutorial}
+
+See the {!page-tutorial} for a comprehensive guide to using JMAP with OCaml,
+including how types map to JSON and practical examples.
+
+{1 Browser Support}
+
+For browser-based applications, see the [jmap-brr] package which provides
+a JMAP client using the Brr library and js_of_ocaml.

doc/tutorial.mld

···
+{0 JMAP Tutorial}
+
+This tutorial introduces JMAP (JSON Meta Application Protocol) and
+demonstrates the [jmap] OCaml library through interactive examples. JMAP
+is defined in {{:https://www.rfc-editor.org/rfc/rfc8620}RFC 8620} (core)
+and {{:https://www.rfc-editor.org/rfc/rfc8621}RFC 8621} (mail).
+
+{1 What is JMAP?}
+
+JMAP is a modern, efficient protocol for synchronizing mail and other
+data. It's designed as a better alternative to IMAP, addressing many of
+IMAP's limitations:
+
+{ul
+{- {b Stateless over HTTP}: Unlike IMAP's persistent TCP connections, JMAP
+   uses standard HTTP POST requests with JSON payloads.}
+{- {b Efficient batching}: Multiple operations can be combined into a single
+   request, reducing round-trips.}
+{- {b Result references}: The output of one method call can be used as input
+   to another in the same request.}
+{- {b Push support}: Built-in mechanisms for real-time notifications.}
+{- {b Binary data handling}: Separate upload/download endpoints for large
+   attachments.}}
+
+The core protocol (RFC 8620) defines the general structure, while RFC 8621
+extends it specifically for email, mailboxes, threads, and related objects.
+
+{1 Setup}
+
+First, let's set up our environment. In the toplevel, load the library
+with [#require "jmap.top";;] which will automatically install pretty
+printers.
+
+{@ocaml[
+# Jmap_top.install ();;
+- : unit = ()
+# open Jmap;;
+]}
+
+For parsing and encoding JSON, we'll use some helper functions:
+
+{@ocaml[
+# let parse_json s =
+    match Jsont_bytesrw.decode_string Jsont.json s with
+    | Ok json -> json
+    | Error e -> failwith e;;
+val parse_json : string -> Jsont.json = <fun>
+# let json_to_string json =
+    match Jsont_bytesrw.encode_string ~format:Jsont.Indent Jsont.json json with
+    | Ok s -> s
+    | Error e -> failwith e;;
+val json_to_string : Jsont.json -> string = <fun>
+]}
+
+{1 JMAP Identifiers}
+
+From {{:https://www.rfc-editor.org/rfc/rfc8620#section-1.2}RFC 8620 Section 1.2}:
+
+{i An "Id" is a String of at least 1 and a maximum of 255 octets in size,
+and it MUST only contain characters from the "URL and Filename Safe"
+base64 alphabet.}
+
+The {!Jmap.Id} module provides type-safe identifiers:
+
+{@ocaml[
+# let id = Id.of_string_exn "abc123";;
+val id : Id.t = abc123
+# Id.to_string id;;
+- : string = "abc123"
+]}
+
+Invalid identifiers are rejected:
+
+{@ocaml[
+# Id.of_string "";;
+- : (Id.t, string) result = Error "Id cannot be empty"
+# Id.of_string (String.make 256 'x');;
+- : (Id.t, string) result = Error "Id cannot exceed 255 characters"
+]}
+
+{1 Keywords}
+
+Email keywords are string flags that indicate message state. RFC 8621
+defines standard keywords, and the library represents them as polymorphic
+variants for type safety.
+
+{2 Standard Keywords}
+
+From {{:https://www.rfc-editor.org/rfc/rfc8621#section-4.1.1}RFC 8621
+Section 4.1.1}:
+
+{@ocaml[
+# Keyword.of_string "$seen";;
+- : Keyword.t = $seen
+# Keyword.of_string "$flagged";;
+- : Keyword.t = $flagged
+# Keyword.of_string "$draft";;
+- : Keyword.t = $draft
+# Keyword.of_string "$answered";;
+- : Keyword.t = $answered
+]}
+
+The standard keywords are:
+
+{ul
+{- [`Seen] - The email has been read}
+{- [`Flagged] - The email has been flagged for attention}
+{- [`Draft] - The email is a draft being composed}
+{- [`Answered] - The email has been replied to}
+{- [`Forwarded] - The email has been forwarded}
+{- [`Phishing] - The email is likely phishing}
+{- [`Junk] - The email is spam}
+{- [`NotJunk] - The email is definitely not spam}}
+
+{2 Extended Keywords}
+
+The library also supports draft-ietf-mailmaint extended keywords:
+
+{@ocaml[
+# Keyword.of_string "$notify";;
+- : Keyword.t = $notify
+# Keyword.of_string "$muted";;
+- : Keyword.t = $muted
+# Keyword.of_string "$hasattachment";;
+- : Keyword.t = $hasattachment
+]}
+
+{2 Custom Keywords}
+
+Unknown keywords are preserved as [`Custom]:
+
+{@ocaml[
+# Keyword.of_string "$my_custom_flag";;
+- : Keyword.t = $my_custom_flag
+]}
+
+{2 Converting Back to Strings}
+
+{@ocaml[
+# Keyword.to_string `Seen;;
+- : string = "$seen"
+# Keyword.to_string `Flagged;;
+- : string = "$flagged"
+# Keyword.to_string (`Custom "$important");;
+- : string = "$important"
+]}
+
+{1 Mailbox Roles}
+
+Mailboxes can have special roles that indicate their purpose. From
+{{:https://www.rfc-editor.org/rfc/rfc8621#section-2}RFC 8621 Section 2}:
+
+{@ocaml[
+# Role.of_string "inbox";;
+- : Role.t = inbox
+# Role.of_string "sent";;
+- : Role.t = sent
+# Role.of_string "drafts";;
+- : Role.t = drafts
+# Role.of_string "trash";;
+- : Role.t = trash
+# Role.of_string "junk";;
+- : Role.t = junk
+# Role.of_string "archive";;
+- : Role.t = archive
+]}
+
+Custom roles are also supported:
+
+{@ocaml[
+# Role.of_string "receipts";;
+- : Role.t = receipts
+]}
+
+{1 Capabilities}
+
+JMAP uses capability URIs to indicate supported features. From
+{{:https://www.rfc-editor.org/rfc/rfc8620#section-2}RFC 8620 Section 2}:
+
+{@ocaml[
+# Capability.core_uri;;
+- : string = "urn:ietf:params:jmap:core"
+# Capability.mail_uri;;
+- : string = "urn:ietf:params:jmap:mail"
+# Capability.submission_uri;;
+- : string = "urn:ietf:params:jmap:submission"
+]}
+
+{@ocaml[
+# Capability.of_string Capability.core_uri;;
+- : Capability.t = urn:ietf:params:jmap:core
+# Capability.of_string Capability.mail_uri;;
+- : Capability.t = urn:ietf:params:jmap:mail
+# Capability.of_string "urn:example:custom";;
+- : Capability.t = urn:example:custom
+]}
+
+{1 Understanding JMAP JSON Structure}
+
+One of the key benefits of JMAP over IMAP is its use of JSON. Let's see
+how OCaml types map to the wire format.
+
+{2 Requests}
+
+A JMAP request contains:
+- [using]: List of capability URIs required
+- [methodCalls]: Array of method invocations
+
+Each method invocation is a triple: [methodName], [arguments], [callId].
+
+Here's how a simple request is structured:
+
+{x@ocaml[
+# let req = Jmap.Proto.Request.create
+    ~using:[Capability.core_uri; Capability.mail_uri]
+    ~method_calls:[
+      Jmap.Proto.Invocation.create
+        ~name:"Mailbox/get"
+        ~arguments:(parse_json {|{"accountId": "abc123"}|})
+        ~call_id:"c0"
+    ]
+    ();;
+Line 7, characters 18-22:
+Error: The function applied to this argument has type
+         method_call_id:string -> Proto.Invocation.t
+This argument cannot be applied with label ~call_id
+# Jmap_top.encode Jmap.Proto.Request.jsont req |> json_to_string |> print_endline;;
+Line 1, characters 42-45:
+Error: Unbound value req
+Hint:   Did you mean ref?
+]x}
+
+{2 Email Filter Conditions}
+
+Filters demonstrate how complex query conditions map to JSON. From
+{{:https://www.rfc-editor.org/rfc/rfc8621#section-4.4.1}RFC 8621
+Section 4.4.1}:
+
+{x@ocaml[
+# let filter_condition : Jmap.Proto.Email.Filter_condition.t = {
+    in_mailbox = Some (Id.of_string_exn "inbox123");
+    in_mailbox_other_than = None;
+    before = None;
+    after = None;
+    min_size = None;
+    max_size = None;
+    all_in_thread_have_keyword = None;
+    some_in_thread_have_keyword = None;
+    none_in_thread_have_keyword = None;
+    has_keyword = Some "$flagged";
+    not_keyword = None;
+    has_attachment = Some true;
+    text = None;
+    from = Some "alice@";
+    to_ = None;
+    cc = None;
+    bcc = None;
+    subject = Some "urgent";
+    body = None;
+    header = None;
+  };;
+Line 2, characters 23-52:
+Error: This expression has type Id.t but an expression was expected of type
+         Proto.Id.t
+# Jmap_top.encode Jmap.Proto.Email.Filter_condition.jsont filter_condition
+  |> json_to_string |> print_endline;;
+Line 1, characters 57-73:
+Error: Unbound value filter_condition
+]x}
+
+Notice how:
+- OCaml record fields use [snake_case], but JSON uses [camelCase]
+- [None] values are omitted from JSON (not sent as [null])
+- The filter only includes non-empty conditions
+
+{2 Filter Operators}
+
+Filters can be combined with AND, OR, and NOT operators:
+
+{x@ocaml[
+# let combined_filter = Jmap.Proto.Filter.Operator {
+    operator = `And;
+    conditions = [
+      Condition filter_condition;
+      Condition { filter_condition with has_keyword = Some "$seen" }
+    ]
+  };;
+Line 4, characters 17-33:
+Error: Unbound value filter_condition
+]x}
+
+{1 Method Chaining}
+
+One of JMAP's most powerful features is result references - using the
+output of one method as input to another. The {!Jmap.Chain} module
+provides a monadic interface for building such requests.
+
+From {{:https://www.rfc-editor.org/rfc/rfc8620#section-3.7}RFC 8620
+Section 3.7}:
+
+{i A method argument may use the result of a previous method invocation
+in the same request.}
+
+{2 Basic Example}
+
+Query for emails, then fetch their details:
+
+{[
+open Jmap.Chain
+
+let request, handle = build ~capabilities:[core; mail] begin
+  let* query = email_query ~account_id
+    ~filter:(Condition { in_mailbox = Some inbox_id; (* ... *) })
+    ~limit:50L ()
+  in
+  let* emails = email_get ~account_id
+    ~ids:(from_query query)  (* Reference query results! *)
+    ~properties:["subject"; "from"; "receivedAt"]
+    ()
+  in
+  return emails
+end
+][
+{err@mdx-error[
+Line 3, characters 46-50:
+Error: Unbound value core
+]err}]}
+
+The key insight is [from_query query] - this creates a reference to the
+[ids] array from the query response. The server processes both calls in
+sequence, substituting the reference with actual IDs.
+
+{2 Creation and Submission}
+
+Create a draft and send it in one request:
+
+{[
+let* set_h, draft_cid = email_set ~account_id
+  ~create:[("draft1", draft_email_json)]
+  ()
+in
+let* _ = email_submission_set ~account_id
+  ~create:[("sub1", submission_json
+    ~email_id:(created_id_of_string "draft1")  (* Reference creation! *)
+    ~identity_id)]
+  ()
+in
+return set_h
+][
+{err@mdx-error[
+Line 1, characters 1-5:
+Error: Unbound value ( let* )
+]err}]}
+
+{2 The RFC 8620 Example}
+
+The RFC provides a complex example: fetch from/date/subject for all
+emails in the first 10 threads in the inbox:
+
+{[
+let* q = email_query ~account_id
+  ~filter:(Condition { in_mailbox = Some inbox_id; (* ... *) })
+  ~sort:[comparator ~is_ascending:false "receivedAt"]
+  ~collapse_threads:true ~limit:10L ()
+in
+let* e1 = email_get ~account_id
+  ~ids:(from_query q)
+  ~properties:["threadId"]
+  ()
+in
+let* threads = thread_get ~account_id
+  ~ids:(from_get_field e1 "threadId")  (* Get threadIds from emails *)
+  ()
+in
+let* e2 = email_get ~account_id
+  ~ids:(from_get_field threads "emailIds")  (* Get all emailIds in threads *)
+  ~properties:["from"; "receivedAt"; "subject"]
+  ()
+in
+return e2
+][
+{err@mdx-error[
+Line 1, characters 1-5:
+Error: Unbound value ( let* )
+]err}]}
+
+This entire flow executes in a {e single HTTP request}!
+
+{1 Error Handling}
+
+JMAP has a structured error system with three levels:
+
+{2 Request-Level Errors}
+
+These are returned with HTTP error status codes and RFC 7807 Problem
+Details. From {{:https://www.rfc-editor.org/rfc/rfc8620#section-3.6.1}RFC
+8620 Section 3.6.1}:
+
+{@ocaml[
+# Error.to_string (`Request {
+    Error.type_ = "urn:ietf:params:jmap:error:unknownCapability";
+    status = Some 400;
+    title = Some "Unknown Capability";
+    detail = Some "The server does not support 'urn:example:unsupported'";
+    limit = None;
+  });;
+- : string =
+"Request error: urn:ietf:params:jmap:error:unknownCapability (status 400): The server does not support 'urn:example:unsupported'"
+]}
+
+{2 Method-Level Errors}
+
+Individual method calls can fail while others succeed:
+
+{@ocaml[
+# Error.to_string (`Method {
+    Error.type_ = "invalidArguments";
+    description = Some "The 'filter' argument is malformed";
+  });;
+- : string =
+"Method error: invalidArguments: The 'filter' argument is malformed"
+]}
+
+{2 SetError}
+
+Object-level errors in /set responses:
+
+{@ocaml[
+# Error.to_string (`Set ("draft1", {
+    Error.type_ = "invalidProperties";
+    description = Some "Unknown property: foobar";
+    properties = Some ["foobar"];
+  }));;
+- : string =
+"Set error for draft1: invalidProperties: Unknown property: foobar"
+]}
+
+{1 Using with FastMail}
+
+FastMail is a popular JMAP provider. Here's how to connect:
+
+{[
+(* Get a token from https://app.fastmail.com/settings/tokens *)
+let token = "your-api-token"
+
+(* The session URL for FastMail *)
+let session_url = "https://api.fastmail.com/jmap/session"
+
+(* For browser applications using jmap-brr: *)
+let main () =
+  let open Fut.Syntax in
+  let* conn = Jmap_brr.get_session
+    ~url:(Jstr.v session_url)
+    ~token:(Jstr.v token)
+  in
+  match conn with
+  | Error e -> Brr.Console.(error [str "Error:"; e]); Fut.return ()
+  | Ok conn ->
+      let session = Jmap_brr.session conn in
+      Brr.Console.(log [str "Connected as:";
+                        str (Jmap.Session.username session)]);
+      Fut.return ()
+][
+{err@mdx-error[
+Line 9, characters 14-17:
+Error: Unbound module Fut
+Hint:    Did you mean Fun?
+]err}]}
+
+{1 Summary}
+
+JMAP (RFC 8620/8621) provides a modern, efficient protocol for email:
+
+{ol
+{- {b Sessions}: Discover capabilities and account information via GET request}
+{- {b Batching}: Combine multiple method calls in one request}
+{- {b References}: Use results from one method as input to another}
+{- {b Type Safety}: The [jmap] library uses polymorphic variants for keywords and roles}
+{- {b JSON Mapping}: OCaml types map cleanly to JMAP JSON structure}
+{- {b Browser Support}: The [jmap-brr] package enables browser-based clients}}
+
+The [jmap] library provides:
+{ul
+{- {!Jmap} - High-level interface with abstract types}
+{- {!Jmap.Proto} - Low-level protocol types matching the RFCs}
+{- {!Jmap.Chain} - Monadic interface for request chaining}
+{- [Jmap_brr] - Browser support via Brr/js_of_ocaml (separate package)}}
+
+{2 Key RFC References}
+
+{ul
+{- {{:https://www.rfc-editor.org/rfc/rfc8620}RFC 8620}: JMAP Core}
+{- {{:https://www.rfc-editor.org/rfc/rfc8621}RFC 8621}: JMAP for Mail}
+{- {{:https://www.rfc-editor.org/rfc/rfc7807}RFC 7807}: Problem Details for HTTP APIs}}

dune-project

···
 (lang dune 3.20)
 
+(using mdx 0.4)
+
 (name jmap)
 
 (generate_opam_files true)
···
   (jsont (>= 0.2.0))
   eio
   requests))
+
+(package
+ (name jmap-brr)
+ (synopsis "JMAP client for browsers")
+ (description "JMAP client using Brr for browser-based email clients with js_of_ocaml.")
+ (depends
+  (ocaml (>= 5.4.0))
+  (jmap (= :version))
+  (jsont (>= 0.2.0))
+  (brr (>= 0.0.6))))

jmap-brr.opam

···
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "JMAP client for browsers"
+description:
+  "JMAP client using Brr for browser-based email clients with js_of_ocaml."
+maintainer: ["Anil Madhavapeddy <[e-mail]>"]
+authors: ["Anil Madhavapeddy <[e-mail]>"]
+license: "ISC"
+homepage: "https://github.com/avsm/ocaml-jmap"
+doc: "https://avsm.github.io/ocaml-jmap"
+bug-reports: "https://github.com/avsm/ocaml-jmap/issues"
+depends: [
+  "dune" {>= "3.20"}
+  "ocaml" {>= "5.4.0"}
+  "jmap" {= version}
+  "jsont" {>= "0.2.0"}
+  "brr" {>= "0.0.6"}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/avsm/ocaml-jmap.git"
+x-maintenance-intent: ["(latest)"]

lib/core/jmap.ml

···
 
   (** Get active keywords as polymorphic variants. *)
   let keywords e =
-    let kw_map = Proto.Email.keywords e in
-    List.filter_map (fun (k, v) ->
-      if v then Some (Keyword.of_string k) else None
-    ) kw_map
+    match Proto.Email.keywords e with
+    | None -> []
+    | Some kw_map ->
+      List.filter_map (fun (k, v) ->
+        if v then Some (Keyword.of_string k) else None
+      ) kw_map
 
   (** Check if email has a specific keyword. *)
   let has_keyword kw e =
     let kw_str = Keyword.to_string kw in
-    let kw_map = Proto.Email.keywords e in
-    List.exists (fun (k, v) -> k = kw_str && v) kw_map
+    match Proto.Email.keywords e with
+    | None -> false
+    | Some kw_map -> List.exists (fun (k, v) -> k = kw_str && v) kw_map
 
   let from e = Proto.Email.from e
   let to_ e = Proto.Email.to_ e

lib/core/jmap.mli

···
   val create : ?name:string -> string -> t
 end
 
-(** Email mailbox. *)
+(** Email mailbox.
+    All accessors return option types since responses only include requested properties. *)
 module Mailbox : sig
   type t
 
-  val id : t -> Id.t
-  val name : t -> string
+  val id : t -> Id.t option
+  val name : t -> string option
   val parent_id : t -> Id.t option
-  val sort_order : t -> int64
-  val total_emails : t -> int64
-  val unread_emails : t -> int64
-  val total_threads : t -> int64
-  val unread_threads : t -> int64
-  val is_subscribed : t -> bool
+  val sort_order : t -> int64 option
+  val total_emails : t -> int64 option
+  val unread_emails : t -> int64 option
+  val total_threads : t -> int64 option
+  val unread_threads : t -> int64 option
+  val is_subscribed : t -> bool option
   val role : t -> Role.t option
 
   (** Mailbox rights. *)
···
     val may_submit : t -> bool
   end
 
-  val my_rights : t -> Rights.t
+  val my_rights : t -> Rights.t option
 end
 
-(** Email thread. *)
+(** Email thread.
+    All accessors return option types since responses only include requested properties. *)
 module Thread : sig
   type t
 
-  val id : t -> Id.t
-  val email_ids : t -> Id.t list
+  val id : t -> Id.t option
+  val email_ids : t -> Id.t list option
 end
 
 (** Email message. *)
···
     val value_is_encoding_problem : value -> bool
   end
 
+  (** All accessors return option types since responses only include requested properties. *)
   type t
 
-  val id : t -> Id.t
-  val blob_id : t -> Id.t
-  val thread_id : t -> Id.t
-  val mailbox_ids : t -> (Id.t * bool) list
-  val size : t -> int64
-  val received_at : t -> Ptime.t
+  val id : t -> Id.t option
+  val blob_id : t -> Id.t option
+  val thread_id : t -> Id.t option
+  val mailbox_ids : t -> (Id.t * bool) list option
+  val size : t -> int64 option
+  val received_at : t -> Ptime.t option
   val message_id : t -> string list option
   val in_reply_to : t -> string list option
   val references : t -> string list option
   val subject : t -> string option
   val sent_at : t -> Ptime.t option
-  val has_attachment : t -> bool
-  val preview : t -> string
+  val has_attachment : t -> bool option
+  val preview : t -> string option
 
-  (** Get active keywords as polymorphic variants. *)
+  (** Get active keywords as polymorphic variants.
+      Returns empty list if keywords property was not requested. *)
   val keywords : t -> Keyword.t list
 
-  (** Check if email has a specific keyword. *)
+  (** Check if email has a specific keyword.
+      Returns false if keywords property was not requested. *)
   val has_keyword : Keyword.t -> t -> bool
 
   val from : t -> Email_address.t list option
···
   val body_values : t -> (string * Body.value) list option
 end
 
-(** Email identity for sending. *)
+(** Email identity for sending.
+    All accessors return option types since responses only include requested properties. *)
 module Identity : sig
   type t
 
-  val id : t -> Id.t
-  val name : t -> string
-  val email : t -> string
+  val id : t -> Id.t option
+  val name : t -> string option
+  val email : t -> string option
   val reply_to : t -> Email_address.t list option
   val bcc : t -> Email_address.t list option
-  val text_signature : t -> string
-  val html_signature : t -> string
-  val may_delete : t -> bool
+  val text_signature : t -> string option
+  val html_signature : t -> string option
+  val may_delete : t -> bool option
 end
 
-(** Email submission for outgoing mail. *)
+(** Email submission for outgoing mail.
+    All accessors return option types since responses only include requested properties. *)
 module Submission : sig
   type t
 
-  val id : t -> Id.t
-  val identity_id : t -> Id.t
-  val email_id : t -> Id.t
-  val thread_id : t -> Id.t
-  val send_at : t -> Ptime.t
-  val undo_status : t -> Proto.Submission.undo_status
+  val id : t -> Id.t option
+  val identity_id : t -> Id.t option
+  val email_id : t -> Id.t option
+  val thread_id : t -> Id.t option
+  val send_at : t -> Ptime.t option
+  val undo_status : t -> Proto.Submission.undo_status option
   val delivery_status : t -> (string * Proto.Submission.Delivery_status.t) list option
-  val dsn_blob_ids : t -> Id.t list
-  val mdn_blob_ids : t -> Id.t list
+  val dsn_blob_ids : t -> Id.t list option
+  val mdn_blob_ids : t -> Id.t list option
 end
 
 (** Vacation auto-response. *)

lib/js/dune

···
+(include_subdirs no)
+
+(library
+ (name jmap_brr)
+ (public_name jmap-brr)
+ (libraries jmap brr jsont.brr)
+ (modes byte))

lib/js/jmap_brr.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+open Brr
+open Fut.Syntax
+
+type connection = {
+  session : Jmap.Proto.Session.t;
+  api_url : Jstr.t;
+  token : Jstr.t;
+}
+
+let session conn = conn.session
+let api_url conn = conn.api_url
+
+(* JSON logging callbacks *)
+let on_request : (string -> string -> unit) option ref = ref None
+let on_response : (string -> string -> unit) option ref = ref None
+
+let set_request_logger f = on_request := Some f
+let set_response_logger f = on_response := Some f
+
+let log_request label json =
+  match !on_request with
+  | Some f -> f label json
+  | None -> ()
+
+let log_response label json =
+  match !on_response with
+  | Some f -> f label json
+  | None -> ()
+
+(* JSON encoding/decoding using jsont.brr *)
+
+let encode_request req =
+  Jsont_brr.encode Jmap.Proto.Request.jsont req
+
+let encode_response resp =
+  Jsont_brr.encode Jmap.Proto.Response.jsont resp
+
+let encode_session session =
+  Jsont_brr.encode Jmap.Proto.Session.jsont session
+
+let decode_json s =
+  match Brr.Json.decode s with
+  | Ok jv -> Ok (Obj.magic jv : Jsont.json) (* Jv.t and Jsont.json are compatible *)
+  | Error e -> Error e
+
+let encode_json json =
+  Ok (Brr.Json.encode (Obj.magic json : Jv.t))
+
+let pp_json ppf json =
+  match encode_json json with
+  | Ok s -> Format.pp_print_string ppf (Jstr.to_string s)
+  | Error _ -> Format.pp_print_string ppf "<json encoding error>"
+
+(* HTTP helpers *)
+
+let make_headers token =
+  Brr_io.Fetch.Headers.of_assoc [
+    Jstr.v "Authorization", Jstr.(v "Bearer " + token);
+    Jstr.v "Content-Type", Jstr.v "application/json";
+    Jstr.v "Accept", Jstr.v "application/json";
+  ]
+
+let fetch_json ~url ~meth ~headers ?body () =
+  Console.(log [str ">>> Request:"; str (Jstr.to_string meth); str (Jstr.to_string url)]);
+  (match body with
+   | Some b -> Console.(log [str ">>> Body:"; b])
+   | None -> Console.(log [str ">>> No body"]));
+  let init = Brr_io.Fetch.Request.init
+    ~method':meth
+    ~headers
+    ?body
+    ()
+  in
+  let req = Brr_io.Fetch.Request.v ~init url in
+  let* response = Brr_io.Fetch.request req in
+  match response with
+  | Error e ->
+      Console.(error [str "<<< Fetch error:"; e]);
+      Fut.return (Error e)
+  | Ok resp ->
+      let status = Brr_io.Fetch.Response.status resp in
+      Console.(log [str "<<< Response status:"; str (Jstr.of_int status)]);
+      if not (Brr_io.Fetch.Response.ok resp) then begin
+        let msg = Jstr.(v "HTTP error: " + of_int status) in
+        (* Try to get response body for error details *)
+        let body = Brr_io.Fetch.Response.as_body resp in
+        let* text = Brr_io.Fetch.Body.text body in
+        (match text with
+         | Ok t -> Console.(error [str "<<< Error body:"; str (Jstr.to_string t)])
+         | Error _ -> ());
+        Fut.return (Error (Jv.Error.v msg))
+      end else begin
+        let body = Brr_io.Fetch.Response.as_body resp in
+        let* text = Brr_io.Fetch.Body.text body in
+        match text with
+        | Error e ->
+            Console.(error [str "<<< Body read error:"; e]);
+            Fut.return (Error e)
+        | Ok text ->
+            Console.(log [str "<<< Response body:"; str (Jstr.to_string text)]);
+            Fut.return (Ok text)
+      end
+
+(* Session establishment *)
+
+let get_session ~url ~token =
+  Console.(log [str "get_session: token length ="; str (Jstr.of_int (Jstr.length token))]);
+  log_request "GET Session" (Printf.sprintf "{\"url\": \"%s\"}" (Jstr.to_string url));
+  let headers = make_headers token in
+  let* result = fetch_json ~url ~meth:(Jstr.v "GET") ~headers () in
+  match result with
+  | Error e -> Fut.return (Error e)
+  | Ok text ->
+      log_response "Session" (Jstr.to_string text);
+      match Jsont_brr.decode Jmap.Proto.Session.jsont text with
+      | Error e -> Fut.return (Error e)
+      | Ok session ->
+          let api_url = Jstr.v (Jmap.Proto.Session.api_url session) in
+          Fut.return (Ok { session; api_url; token })
+
+(* Making requests *)
+
+let request conn req =
+  let headers = make_headers conn.token in
+  match Jsont_brr.encode Jmap.Proto.Request.jsont req with
+  | Error e -> Fut.return (Error e)
+  | Ok body_str ->
+      log_request "JMAP Request" (Jstr.to_string body_str);
+      let body = Brr_io.Fetch.Body.of_jstr body_str in
+      let* result = fetch_json
+        ~url:conn.api_url
+        ~meth:(Jstr.v "POST")
+        ~headers
+        ~body
+        ()
+      in
+      match result with
+      | Error e -> Fut.return (Error e)
+      | Ok text ->
+          log_response "JMAP Response" (Jstr.to_string text);
+          match Jsont_brr.decode Jmap.Proto.Response.jsont text with
+          | Error e -> Fut.return (Error e)
+          | Ok response -> Fut.return (Ok response)
+
+let request_json conn json =
+  let headers = make_headers conn.token in
+  match encode_json json with
+  | Error e -> Fut.return (Error e)
+  | Ok body_str ->
+      let body = Brr_io.Fetch.Body.of_jstr body_str in
+      let* result = fetch_json
+        ~url:conn.api_url
+        ~meth:(Jstr.v "POST")
+        ~headers
+        ~body
+        ()
+      in
+      match result with
+      | Error e -> Fut.return (Error e)
+      | Ok text ->
+          match decode_json text with
+          | Error e -> Fut.return (Error e)
+          | Ok json -> Fut.return (Ok json)
+
+(* Toplevel support *)
+
+let install_printers () =
+  (* In browser context, printers are registered via the OCaml console *)
+  Console.(log [str "JMAP printers installed"])

lib/js/jmap_brr.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** JMAP client for browsers using Brr.
+
+    This module provides a JMAP client that runs in web browsers using
+    the Fetch API. It can be used with js_of_ocaml to build browser-based
+    email clients.
+
+    {2 Example}
+
+    {[
+      open Fut.Syntax
+
+      let main () =
+        let* session = Jmap_brr.get_session
+          ~url:(Jstr.v "https://api.fastmail.com/jmap/session")
+          ~token:(Jstr.v "your-api-token")
+        in
+        match session with
+        | Error e -> Brr.Console.(error [str "Session error:"; e]); Fut.return ()
+        | Ok session ->
+            Brr.Console.(log [str "Connected as:"; str (Jmap.Session.username session)]);
+            Fut.return ()
+
+      let () = ignore (main ())
+    ]} *)
+
+(** {1 Connection} *)
+
+type connection
+(** A JMAP connection to a server. *)
+
+val session : connection -> Jmap.Proto.Session.t
+(** [session conn] returns the session information. *)
+
+val api_url : connection -> Jstr.t
+(** [api_url conn] returns the API URL for requests. *)
+
+(** {1 Session Establishment} *)
+
+val get_session :
+  url:Jstr.t ->
+  token:Jstr.t ->
+  (connection, Jv.Error.t) result Fut.t
+(** [get_session ~url ~token] establishes a JMAP session.
+
+    [url] is the session URL (e.g., ["https://api.fastmail.com/jmap/session"]).
+    [token] is the Bearer authentication token. *)
+
+(** {1 Making Requests} *)
+
+val request :
+  connection ->
+  Jmap.Proto.Request.t ->
+  (Jmap.Proto.Response.t, Jv.Error.t) result Fut.t
+(** [request conn req] sends a JMAP request and returns the response. *)
+
+val request_json :
+  connection ->
+  Jsont.json ->
+  (Jsont.json, Jv.Error.t) result Fut.t
+(** [request_json conn json] sends a raw JSON request and returns the
+    JSON response. Useful for debugging or custom requests. *)
+
+(** {1 JSON Encoding Utilities}
+
+    These functions help visualize how OCaml types map to JMAP JSON,
+    useful for the tutorial and debugging. *)
+
+val encode_request : Jmap.Proto.Request.t -> (Jstr.t, Jv.Error.t) result
+(** [encode_request req] encodes a request to JSON string. *)
+
+val encode_response : Jmap.Proto.Response.t -> (Jstr.t, Jv.Error.t) result
+(** [encode_response resp] encodes a response to JSON string. *)
+
+val encode_session : Jmap.Proto.Session.t -> (Jstr.t, Jv.Error.t) result
+(** [encode_session session] encodes a session to JSON string. *)
+
+val decode_json : Jstr.t -> (Jsont.json, Jv.Error.t) result
+(** [decode_json s] parses a JSON string to a Jsont.json value. *)
+
+val encode_json : Jsont.json -> (Jstr.t, Jv.Error.t) result
+(** [encode_json json] encodes a Jsont.json value to a string. *)
+
+val pp_json : Format.formatter -> Jsont.json -> unit
+(** [pp_json ppf json] pretty-prints JSON. For toplevel use. *)
+
+(** {1 Protocol Logging} *)
+
+val set_request_logger : (string -> string -> unit) -> unit
+(** [set_request_logger f] registers a callback [f label json] that will be
+    called with each outgoing JMAP request. Useful for debugging and
+    educational displays. *)
+
+val set_response_logger : (string -> string -> unit) -> unit
+(** [set_response_logger f] registers a callback [f label json] that will be
+    called with each incoming JMAP response. Useful for debugging and
+    educational displays. *)
+
+(** {1 Toplevel Support} *)
+
+val install_printers : unit -> unit
+(** [install_printers ()] installs toplevel pretty printers for JMAP types.
+    This is useful when using the OCaml console in the browser. *)

lib/mail/mail_email.ml

···
     | `Gray
   ]
 
-  (* Flag color bitmask:
-     - 000 = red, 100 = orange, 010 = yellow, 111 = green
-     - 001 = blue, 101 = purple, 011 = gray *)
   let flag_color_to_keywords = function
-    | `Red -> []  (* 000 - no bits set *)
-    | `Orange -> [mail_flag_bit0]  (* 100 *)
-    | `Yellow -> [mail_flag_bit1]  (* 010 *)
-    | `Green -> [mail_flag_bit0; mail_flag_bit1; mail_flag_bit2]  (* 111 *)
-    | `Blue -> [mail_flag_bit2]  (* 001 *)
-    | `Purple -> [mail_flag_bit0; mail_flag_bit2]  (* 101 *)
-    | `Gray -> [mail_flag_bit1; mail_flag_bit2]  (* 011 *)
+    | `Red -> []
+    | `Orange -> [mail_flag_bit0]
+    | `Yellow -> [mail_flag_bit1]
+    | `Green -> [mail_flag_bit0; mail_flag_bit1; mail_flag_bit2]
+    | `Blue -> [mail_flag_bit2]
+    | `Purple -> [mail_flag_bit0; mail_flag_bit2]
+    | `Gray -> [mail_flag_bit1; mail_flag_bit2]
 
   let flag_color_of_keywords keywords =
     let has k = List.mem k keywords in
···
     | (false, false, true) -> Some `Blue
     | (true, false, true) -> Some `Purple
     | (false, true, true) -> Some `Gray
-    | (true, true, false) -> None  (* Invalid combination *)
+    | (true, true, false) -> None
 end
 
+(* Email property types *)
+
+type metadata_property = [
+  | `Id
+  | `Blob_id
+  | `Thread_id
+  | `Mailbox_ids
+  | `Keywords
+  | `Size
+  | `Received_at
+]
+
+type header_convenience_property = [
+  | `Message_id
+  | `In_reply_to
+  | `References
+  | `Sender
+  | `From
+  | `To
+  | `Cc
+  | `Bcc
+  | `Reply_to
+  | `Subject
+  | `Sent_at
+  | `Headers
+]
+
+type body_property = [
+  | `Body_structure
+  | `Body_values
+  | `Text_body
+  | `Html_body
+  | `Attachments
+  | `Has_attachment
+  | `Preview
+]
+
+type standard_property = [
+  | metadata_property
+  | header_convenience_property
+  | body_property
+]
+
+type header_property = [ `Header of Mail_header.header_property ]
+
+type property = [ standard_property | header_property ]
+
+let standard_property_to_string : [< standard_property ] -> string = function
+  | `Id -> "id"
+  | `Blob_id -> "blobId"
+  | `Thread_id -> "threadId"
+  | `Mailbox_ids -> "mailboxIds"
+  | `Keywords -> "keywords"
+  | `Size -> "size"
+  | `Received_at -> "receivedAt"
+  | `Message_id -> "messageId"
+  | `In_reply_to -> "inReplyTo"
+  | `References -> "references"
+  | `Sender -> "sender"
+  | `From -> "from"
+  | `To -> "to"
+  | `Cc -> "cc"
+  | `Bcc -> "bcc"
+  | `Reply_to -> "replyTo"
+  | `Subject -> "subject"
+  | `Sent_at -> "sentAt"
+  | `Headers -> "headers"
+  | `Body_structure -> "bodyStructure"
+  | `Body_values -> "bodyValues"
+  | `Text_body -> "textBody"
+  | `Html_body -> "htmlBody"
+  | `Attachments -> "attachments"
+  | `Has_attachment -> "hasAttachment"
+  | `Preview -> "preview"
+
+let property_to_string : [< property ] -> string = function
+  | `Header hp -> Mail_header.header_property_to_string hp
+  | #standard_property as p -> standard_property_to_string p
+
+let standard_property_of_string s : standard_property option =
+  match s with
+  | "id" -> Some `Id
+  | "blobId" -> Some `Blob_id
+  | "threadId" -> Some `Thread_id
+  | "mailboxIds" -> Some `Mailbox_ids
+  | "keywords" -> Some `Keywords
+  | "size" -> Some `Size
+  | "receivedAt" -> Some `Received_at
+  | "messageId" -> Some `Message_id
+  | "inReplyTo" -> Some `In_reply_to
+  | "references" -> Some `References
+  | "sender" -> Some `Sender
+  | "from" -> Some `From
+  | "to" -> Some `To
+  | "cc" -> Some `Cc
+  | "bcc" -> Some `Bcc
+  | "replyTo" -> Some `Reply_to
+  | "subject" -> Some `Subject
+  | "sentAt" -> Some `Sent_at
+  | "headers" -> Some `Headers
+  | "bodyStructure" -> Some `Body_structure
+  | "bodyValues" -> Some `Body_values
+  | "textBody" -> Some `Text_body
+  | "htmlBody" -> Some `Html_body
+  | "attachments" -> Some `Attachments
+  | "hasAttachment" -> Some `Has_attachment
+  | "preview" -> Some `Preview
+  | _ -> None
+
+let property_of_string s : property option =
+  match standard_property_of_string s with
+  | Some p -> Some (p :> property)
+  | None ->
+    match Mail_header.header_property_of_string s with
+    | Some hp -> Some (`Header hp)
+    | None -> None
+
+(* Body part properties *)
+
+type body_part_property = [
+  | `Part_id
+  | `Blob_id
+  | `Size
+  | `Part_headers
+  | `Name
+  | `Type
+  | `Charset
+  | `Disposition
+  | `Cid
+  | `Language
+  | `Location
+  | `Sub_parts
+]
+
+let body_part_property_to_string : [< body_part_property ] -> string = function
+  | `Part_id -> "partId"
+  | `Blob_id -> "blobId"
+  | `Size -> "size"
+  | `Part_headers -> "headers"
+  | `Name -> "name"
+  | `Type -> "type"
+  | `Charset -> "charset"
+  | `Disposition -> "disposition"
+  | `Cid -> "cid"
+  | `Language -> "language"
+  | `Location -> "location"
+  | `Sub_parts -> "subParts"
+
+let body_part_property_of_string s : body_part_property option =
+  match s with
+  | "partId" -> Some `Part_id
+  | "blobId" -> Some `Blob_id
+  | "size" -> Some `Size
+  | "headers" -> Some `Part_headers
+  | "name" -> Some `Name
+  | "type" -> Some `Type
+  | "charset" -> Some `Charset
+  | "disposition" -> Some `Disposition
+  | "cid" -> Some `Cid
+  | "language" -> Some `Language
+  | "location" -> Some `Location
+  | "subParts" -> Some `Sub_parts
+  | _ -> None
+
+(* Email type with optional fields *)
+
 type t = {
-  id : Proto_id.t;
-  blob_id : Proto_id.t;
-  thread_id : Proto_id.t;
-  size : int64;
-  received_at : Ptime.t;
-  mailbox_ids : (Proto_id.t * bool) list;
-  keywords : (string * bool) list;
+  id : Proto_id.t option;
+  blob_id : Proto_id.t option;
+  thread_id : Proto_id.t option;
+  size : int64 option;
+  received_at : Ptime.t option;
+  mailbox_ids : (Proto_id.t * bool) list option;
+  keywords : (string * bool) list option;
   message_id : string list option;
   in_reply_to : string list option;
   references : string list option;
···
   text_body : Mail_body.Part.t list option;
   html_body : Mail_body.Part.t list option;
   attachments : Mail_body.Part.t list option;
-  has_attachment : bool;
-  preview : string;
+  has_attachment : bool option;
+  preview : string option;
+  dynamic_headers : (string * Jsont.json) list;
 }
 
 let id t = t.id
···
 let attachments t = t.attachments
 let has_attachment t = t.has_attachment
 let preview t = t.preview
+let dynamic_headers_raw t = t.dynamic_headers
+
+(* Parse header property name to determine form and :all flag *)
+let parse_header_prop name =
+  if not (String.length name > 7 && String.sub name 0 7 = "header:") then
+    None
+  else
+    let rest = String.sub name 7 (String.length name - 7) in
+    let parts = String.split_on_char ':' rest in
+    match parts with
+    | [] -> None
+    | [_name] -> Some (`Raw, false)
+    | [_name; second] ->
+        if second = "all" then Some (`Raw, true)
+        else (
+          match Mail_header.form_of_string second with
+          | Some form -> Some (form, false)
+          | None -> None
+        )
+    | [_name; form_str; "all"] ->
+        (match Mail_header.form_of_string form_str with
+        | Some form -> Some (form, true)
+        | None -> None)
+    | _ -> None
+
+(* Decode a raw JSON header value into typed header_value *)
+let decode_header_value prop_name json =
+  match parse_header_prop prop_name with
+  | None -> None
+  | Some (form, all) ->
+      let jsont = Mail_header.header_value_jsont ~form ~all in
+      match Jsont.Json.decode' jsont json with
+      | Ok v -> Some v
+      | Error _ -> None
+
+let get_header t key =
+  match List.assoc_opt key t.dynamic_headers with
+  | None -> None
+  | Some json -> decode_header_value key json
+
+let get_header_string t key =
+  match get_header t key with
+  | Some (Mail_header.String_single s) -> s
+  | _ -> None
+
+let get_header_addresses t key =
+  match get_header t key with
+  | Some (Mail_header.Addresses_single addrs) -> addrs
+  | _ -> None
 
 let make id blob_id thread_id size received_at mailbox_ids keywords
     message_id in_reply_to references sender from to_ cc bcc reply_to
     subject sent_at headers body_structure body_values text_body html_body
-    attachments has_attachment preview =
+    attachments has_attachment preview dynamic_headers =
   { id; blob_id; thread_id; size; received_at; mailbox_ids; keywords;
     message_id; in_reply_to; references; sender; from; to_; cc; bcc;
     reply_to; subject; sent_at; headers; body_structure; body_values;
-    text_body; html_body; attachments; has_attachment; preview }
+    text_body; html_body; attachments; has_attachment; preview; dynamic_headers }
+
+(* Helper: null-safe list decoder - treats null as empty list.
+   This allows fields that may be null or array to decode successfully. *)
+let null_safe_list inner_jsont =
+  Jsont.map
+    ~dec:(function None -> [] | Some l -> l)
+    ~enc:(fun l -> Some l)
+    (Jsont.option (Jsont.list inner_jsont))
+
+module String_map = Map.Make(String)
+
+(* Filter unknown members to only keep header:* properties *)
+let filter_header_props (unknown : Jsont.json String_map.t) : (string * Jsont.json) list =
+  String_map.to_seq unknown
+  |> Seq.filter (fun (k, _) -> String.length k > 7 && String.sub k 0 7 = "header:")
+  |> List.of_seq
 
 let jsont =
   let kind = "Email" in
   let body_values_jsont = Proto_json_map.of_string Mail_body.Value.jsont in
-  (* subject can be null per RFC 8621 Section 4.1.1 *)
-  let nullable_string = Jsont.(option string) in
-  Jsont.Object.map ~kind make
-  |> Jsont.Object.mem "id" Proto_id.jsont ~enc:id
-  |> Jsont.Object.mem "blobId" Proto_id.jsont ~enc:blob_id
-  |> Jsont.Object.mem "threadId" Proto_id.jsont ~enc:thread_id
-  |> Jsont.Object.mem "size" Proto_int53.Unsigned.jsont ~enc:size
-  |> Jsont.Object.mem "receivedAt" Proto_date.Utc.jsont ~enc:received_at
-  |> Jsont.Object.mem "mailboxIds" Proto_json_map.id_to_bool ~enc:mailbox_ids
-  |> Jsont.Object.mem "keywords" Proto_json_map.string_to_bool ~dec_absent:[] ~enc:keywords
-  (* Header fields can be absent or null per RFC 8621 *)
-  |> Jsont.Object.mem "messageId" Jsont.(option (list string))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:message_id
-  |> Jsont.Object.mem "inReplyTo" Jsont.(option (list string))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:in_reply_to
-  |> Jsont.Object.mem "references" Jsont.(option (list string))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:references
-  |> Jsont.Object.mem "sender" Jsont.(option (list Mail_address.jsont))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:sender
-  |> Jsont.Object.mem "from" Jsont.(option (list Mail_address.jsont))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:from
-  |> Jsont.Object.mem "to" Jsont.(option (list Mail_address.jsont))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:to_
-  |> Jsont.Object.mem "cc" Jsont.(option (list Mail_address.jsont))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:cc
-  |> Jsont.Object.mem "bcc" Jsont.(option (list Mail_address.jsont))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:bcc
-  |> Jsont.Object.mem "replyTo" Jsont.(option (list Mail_address.jsont))
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:reply_to
-  |> Jsont.Object.mem "subject" nullable_string
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:subject
+  (* Use null_safe_list for address fields that can be null *)
+  let addr_list = null_safe_list Mail_address.jsont in
+  let str_list = null_safe_list Jsont.string in
+  let part_list = null_safe_list Mail_body.Part.jsont in
+  let hdr_list = null_safe_list Mail_header.jsont in
+  Jsont.Object.map ~kind (fun id blob_id thread_id size received_at mailbox_ids keywords
+      message_id in_reply_to references sender from to_ cc bcc reply_to
+      subject sent_at headers body_structure body_values text_body html_body
+      attachments has_attachment preview unknown ->
+    let dynamic_headers = filter_header_props unknown in
+    make id blob_id thread_id size received_at mailbox_ids keywords
+      message_id in_reply_to references sender from to_ cc bcc reply_to
+      subject sent_at headers body_structure body_values text_body html_body
+      attachments has_attachment preview dynamic_headers)
+  |> Jsont.Object.opt_mem "id" Proto_id.jsont ~enc:id
+  |> Jsont.Object.opt_mem "blobId" Proto_id.jsont ~enc:blob_id
+  |> Jsont.Object.opt_mem "threadId" Proto_id.jsont ~enc:thread_id
+  |> Jsont.Object.opt_mem "size" Proto_int53.Unsigned.jsont ~enc:size
+  |> Jsont.Object.opt_mem "receivedAt" Proto_date.Utc.jsont ~enc:received_at
+  |> Jsont.Object.opt_mem "mailboxIds" Proto_json_map.id_to_bool ~enc:mailbox_ids
+  |> Jsont.Object.opt_mem "keywords" Proto_json_map.string_to_bool ~enc:keywords
+  |> Jsont.Object.opt_mem "messageId" str_list ~enc:message_id
+  |> Jsont.Object.opt_mem "inReplyTo" str_list ~enc:in_reply_to
+  |> Jsont.Object.opt_mem "references" str_list ~enc:references
+  |> Jsont.Object.opt_mem "sender" addr_list ~enc:sender
+  |> Jsont.Object.opt_mem "from" addr_list ~enc:from
+  |> Jsont.Object.opt_mem "to" addr_list ~enc:to_
+  |> Jsont.Object.opt_mem "cc" addr_list ~enc:cc
+  |> Jsont.Object.opt_mem "bcc" addr_list ~enc:bcc
+  |> Jsont.Object.opt_mem "replyTo" addr_list ~enc:reply_to
+  |> Jsont.Object.opt_mem "subject" Jsont.string ~enc:subject
   |> Jsont.Object.opt_mem "sentAt" Proto_date.Rfc3339.jsont ~enc:sent_at
-  |> Jsont.Object.opt_mem "headers" (Jsont.list Mail_header.jsont) ~enc:headers
+  |> Jsont.Object.opt_mem "headers" hdr_list ~enc:headers
   |> Jsont.Object.opt_mem "bodyStructure" Mail_body.Part.jsont ~enc:body_structure
   |> Jsont.Object.opt_mem "bodyValues" body_values_jsont ~enc:body_values
-  |> Jsont.Object.opt_mem "textBody" (Jsont.list Mail_body.Part.jsont) ~enc:text_body
-  |> Jsont.Object.opt_mem "htmlBody" (Jsont.list Mail_body.Part.jsont) ~enc:html_body
-  |> Jsont.Object.opt_mem "attachments" (Jsont.list Mail_body.Part.jsont) ~enc:attachments
-  |> Jsont.Object.mem "hasAttachment" Jsont.bool ~dec_absent:false ~enc:has_attachment
-  |> Jsont.Object.mem "preview" Jsont.string ~dec_absent:"" ~enc:preview
+  |> Jsont.Object.opt_mem "textBody" part_list ~enc:text_body
+  |> Jsont.Object.opt_mem "htmlBody" part_list ~enc:html_body
+  |> Jsont.Object.opt_mem "attachments" part_list ~enc:attachments
+  |> Jsont.Object.opt_mem "hasAttachment" Jsont.bool ~enc:has_attachment
+  |> Jsont.Object.opt_mem "preview" Jsont.string ~enc:preview
+  |> Jsont.Object.keep_unknown
+       (Jsont.Object.Mems.string_map Jsont.json)
+       ~enc:(fun t -> String_map.of_list t.dynamic_headers)
   |> Jsont.Object.finish
 
 module Filter_condition = struct
···
       none_in_thread_have_keyword; has_keyword; not_keyword; has_attachment;
       text; from; to_; cc; bcc; subject; body; header }
 
-  (* Header filter is encoded as [name] or [name, value] array *)
   let header_jsont =
     let kind = "HeaderFilter" in
     let dec json =
···
 end
 
 type get_args_extra = {
-  body_properties : string list option;
+  body_properties : body_part_property list option;
   fetch_text_body_values : bool;
   fetch_html_body_values : bool;
   fetch_all_body_values : bool;
   max_body_value_bytes : int64 option;
 }
 
-let get_args_extra_make body_properties fetch_text_body_values
-    fetch_html_body_values fetch_all_body_values max_body_value_bytes =
+let get_args_extra ?body_properties ?(fetch_text_body_values=false)
+    ?(fetch_html_body_values=false) ?(fetch_all_body_values=false)
+    ?max_body_value_bytes () =
   { body_properties; fetch_text_body_values; fetch_html_body_values;
     fetch_all_body_values; max_body_value_bytes }
+
+let body_part_property_list_jsont =
+  Jsont.list (Jsont.map ~kind:"body_part_property"
+    ~dec:(fun s -> match body_part_property_of_string s with
+      | Some p -> p
+      | None -> Jsont.Error.msgf Jsont.Meta.none "Unknown body property: %s" s)
+    ~enc:body_part_property_to_string
+    Jsont.string)
 
 let get_args_extra_jsont =
   let kind = "Email/get extra args" in
-  Jsont.Object.map ~kind get_args_extra_make
-  |> Jsont.Object.opt_mem "bodyProperties" (Jsont.list Jsont.string) ~enc:(fun a -> a.body_properties)
+  Jsont.Object.map ~kind (fun body_properties fetch_text_body_values
+      fetch_html_body_values fetch_all_body_values max_body_value_bytes ->
+    { body_properties; fetch_text_body_values; fetch_html_body_values;
+      fetch_all_body_values; max_body_value_bytes })
+  |> Jsont.Object.opt_mem "bodyProperties" body_part_property_list_jsont
+       ~enc:(fun a -> a.body_properties)
   |> Jsont.Object.mem "fetchTextBodyValues" Jsont.bool ~dec_absent:false
        ~enc:(fun a -> a.fetch_text_body_values) ~enc_omit:(fun b -> not b)
   |> Jsont.Object.mem "fetchHTMLBodyValues" Jsont.bool ~dec_absent:false
        ~enc:(fun a -> a.fetch_html_body_values) ~enc_omit:(fun b -> not b)
   |> Jsont.Object.mem "fetchAllBodyValues" Jsont.bool ~dec_absent:false
        ~enc:(fun a -> a.fetch_all_body_values) ~enc_omit:(fun b -> not b)
-  |> Jsont.Object.opt_mem "maxBodyValueBytes" Proto_int53.Unsigned.jsont ~enc:(fun a -> a.max_body_value_bytes)
+  |> Jsont.Object.opt_mem "maxBodyValueBytes" Proto_int53.Unsigned.jsont
+       ~enc:(fun a -> a.max_body_value_bytes)
   |> Jsont.Object.finish

lib/mail/mail_email.mli

···
       if no color bits are set (defaults to red when $flagged is set). *)
 end
 
+(** {1 Email Properties}
+
+    Polymorphic variants for type-safe property selection in Email/get requests.
+    These correspond to the properties defined in RFC 8621 Section 4.1. *)
+
+(** Metadata properties (RFC 8621 Section 4.1.1).
+    These represent data about the message in the mail store. *)
+type metadata_property = [
+  | `Id
+  | `Blob_id
+  | `Thread_id
+  | `Mailbox_ids
+  | `Keywords
+  | `Size
+  | `Received_at
+]
+
+(** Convenience header properties (RFC 8621 Section 4.1.3).
+    These are shortcuts for specific header:*:form properties. *)
+type header_convenience_property = [
+  | `Message_id     (** = header:Message-ID:asMessageIds *)
+  | `In_reply_to    (** = header:In-Reply-To:asMessageIds *)
+  | `References     (** = header:References:asMessageIds *)
+  | `Sender         (** = header:Sender:asAddresses *)
+  | `From           (** = header:From:asAddresses *)
+  | `To             (** = header:To:asAddresses *)
+  | `Cc             (** = header:Cc:asAddresses *)
+  | `Bcc            (** = header:Bcc:asAddresses *)
+  | `Reply_to       (** = header:Reply-To:asAddresses *)
+  | `Subject        (** = header:Subject:asText *)
+  | `Sent_at        (** = header:Date:asDate *)
+  | `Headers        (** All headers in raw form *)
+]
+
+(** Body properties (RFC 8621 Section 4.1.4).
+    These represent the message body structure and content. *)
+type body_property = [
+  | `Body_structure
+  | `Body_values
+  | `Text_body
+  | `Html_body
+  | `Attachments
+  | `Has_attachment
+  | `Preview
+]
+
+(** All standard Email properties. *)
+type standard_property = [
+  | metadata_property
+  | header_convenience_property
+  | body_property
+]
+
+(** A dynamic header property request.
+    Use {!Mail_header.header_property} for type-safe construction. *)
+type header_property = [ `Header of Mail_header.header_property ]
+
+(** Any Email property - standard or dynamic header. *)
+type property = [ standard_property | header_property ]
+
+val property_to_string : [< property ] -> string
+(** Convert a property to its wire name (e.g., [`From] -> "from"). *)
+
+val property_of_string : string -> property option
+(** Parse a property name. Returns [None] for unrecognized properties.
+    Handles both standard properties and header:* properties. *)
+
+val standard_property_of_string : string -> standard_property option
+(** Parse only standard property names (not header:* properties). *)
+
+(** {1 Body Part Properties}
+
+    Properties that can be requested for EmailBodyPart objects
+    via the [bodyProperties] argument. *)
+
+type body_part_property = [
+  | `Part_id
+  | `Blob_id
+  | `Size
+  | `Part_headers  (** Named [headers] in the wire format *)
+  | `Name
+  | `Type
+  | `Charset
+  | `Disposition
+  | `Cid
+  | `Language
+  | `Location
+  | `Sub_parts
+]
+
+val body_part_property_to_string : [< body_part_property ] -> string
+(** Convert a body part property to its wire name. *)
+
+val body_part_property_of_string : string -> body_part_property option
+(** Parse a body part property name. *)
+
 (** {1 Email Object} *)
 
 type t = {
   (* Metadata - server-set, immutable *)
-  id : Proto_id.t;
-  blob_id : Proto_id.t;
-  thread_id : Proto_id.t;
-  size : int64;
-  received_at : Ptime.t;
+  id : Proto_id.t option;
+  blob_id : Proto_id.t option;
+  thread_id : Proto_id.t option;
+  size : int64 option;
+  received_at : Ptime.t option;
 
   (* Metadata - mutable *)
-  mailbox_ids : (Proto_id.t * bool) list;
-  keywords : (string * bool) list;
+  mailbox_ids : (Proto_id.t * bool) list option;
+  keywords : (string * bool) list option;
 
   (* Parsed headers *)
   message_id : string list option;
···
   text_body : Mail_body.Part.t list option;
   html_body : Mail_body.Part.t list option;
   attachments : Mail_body.Part.t list option;
-  has_attachment : bool;
-  preview : string;
+  has_attachment : bool option;
+  preview : string option;
+
+  (* Dynamic header properties - stored as raw JSON for lazy decoding *)
+  dynamic_headers : (string * Jsont.json) list;
+  (** Raw header values from [header:*] property requests.
+      The key is the full property name (e.g., "header:X-Custom:asText").
+      Use {!decode_header_value} to parse into typed values. *)
 }
 
-val id : t -> Proto_id.t
-val blob_id : t -> Proto_id.t
-val thread_id : t -> Proto_id.t
-val size : t -> int64
-val received_at : t -> Ptime.t
-val mailbox_ids : t -> (Proto_id.t * bool) list
-val keywords : t -> (string * bool) list
+(** {2 Accessors}
+
+    All accessors return [option] types since the response only includes
+    properties that were requested. *)
+
+val id : t -> Proto_id.t option
+val blob_id : t -> Proto_id.t option
+val thread_id : t -> Proto_id.t option
+val size : t -> int64 option
+val received_at : t -> Ptime.t option
+val mailbox_ids : t -> (Proto_id.t * bool) list option
+val keywords : t -> (string * bool) list option
 val message_id : t -> string list option
 val in_reply_to : t -> string list option
 val references : t -> string list option
···
 val text_body : t -> Mail_body.Part.t list option
 val html_body : t -> Mail_body.Part.t list option
 val attachments : t -> Mail_body.Part.t list option
-val has_attachment : t -> bool
-val preview : t -> string
+val has_attachment : t -> bool option
+val preview : t -> string option
+val dynamic_headers_raw : t -> (string * Jsont.json) list
+(** Get raw dynamic headers. Use {!decode_header_value} to parse them. *)
+
+(** {2 Dynamic Header Decoding} *)
+
+val decode_header_value : string -> Jsont.json -> Mail_header.header_value option
+(** [decode_header_value prop_name json] decodes a raw JSON value into a typed
+    header value based on the property name. The property name determines the form:
+    - [header:Name] or [header:Name:all] -> Raw/Text (String_single/String_all)
+    - [header:Name:asText] -> Text (String_single)
+    - [header:Name:asAddresses] -> Addresses (Addresses_single)
+    - [header:Name:asGroupedAddresses] -> Grouped (Grouped_single)
+    - [header:Name:asMessageIds] -> MessageIds (Strings_single)
+    - [header:Name:asDate] -> Date (Date_single)
+    - [header:Name:asURLs] -> URLs (Strings_single)
+    Returns [None] if the property name is invalid or decoding fails. *)
+
+val get_header : t -> string -> Mail_header.header_value option
+(** [get_header email key] looks up and decodes a dynamic header by its full
+    property name. E.g., [get_header email "header:X-Custom:asText"]. *)
+
+val get_header_string : t -> string -> string option
+(** [get_header_string email key] looks up a string header value.
+    Returns [None] if not found or if the value is not a string type. *)
+
+val get_header_addresses : t -> string -> Mail_address.t list option
+(** [get_header_addresses email key] looks up an addresses header value.
+    Returns [None] if not found or if the value is not an addresses type. *)
 
 val jsont : t Jsont.t
+(** Permissive JSON codec that handles any subset of properties.
+    Unknown [header:*] properties are decoded into {!dynamic_headers}. *)
 
 (** {1 Email Filter Conditions} *)
 
···
 
 (** {1 Email/get Arguments} *)
 
-(** Extra arguments for Email/get beyond standard /get. *)
+(** Extra arguments for Email/get beyond standard /get.
+
+    Note: The standard [properties] argument from {!Proto_method.get_args}
+    should use {!property} variants converted via {!property_to_string}. *)
 type get_args_extra = {
-  body_properties : string list option;
+  body_properties : body_part_property list option;
+  (** Properties to fetch for each EmailBodyPart.
+      If omitted, defaults to all properties. *)
   fetch_text_body_values : bool;
+  (** If [true], fetch body values for text/* parts in textBody. *)
   fetch_html_body_values : bool;
+  (** If [true], fetch body values for text/* parts in htmlBody. *)
   fetch_all_body_values : bool;
+  (** If [true], fetch body values for all text/* parts. *)
   max_body_value_bytes : int64 option;
+  (** Maximum size of body values to return. Larger values are truncated. *)
 }
+
+val get_args_extra :
+  ?body_properties:body_part_property list ->
+  ?fetch_text_body_values:bool ->
+  ?fetch_html_body_values:bool ->
+  ?fetch_all_body_values:bool ->
+  ?max_body_value_bytes:int64 ->
+  unit ->
+  get_args_extra
+(** Convenience constructor with sensible defaults. *)
 
 val get_args_extra_jsont : get_args_extra Jsont.t

lib/mail/mail_header.ml

···
   |> Jsont.Object.mem "value" Jsont.string ~enc:value
   |> Jsont.Object.finish
 
-(* Header parsed forms - these are used with header:Name:form properties *)
+(* Header categories *)
+
+type address_header = [
+  | `From
+  | `Sender
+  | `Reply_to
+  | `To
+  | `Cc
+  | `Bcc
+  | `Resent_from
+  | `Resent_sender
+  | `Resent_reply_to
+  | `Resent_to
+  | `Resent_cc
+  | `Resent_bcc
+]
+
+type message_id_header = [
+  | `Message_id
+  | `In_reply_to
+  | `References
+  | `Resent_message_id
+]
+
+type date_header = [
+  | `Date
+  | `Resent_date
+]
+
+type url_header = [
+  | `List_help
+  | `List_unsubscribe
+  | `List_subscribe
+  | `List_post
+  | `List_owner
+  | `List_archive
+]
+
+type text_header = [
+  | `Subject
+  | `Comments
+  | `Keywords
+  | `List_id
+]
+
+type standard_header = [
+  | address_header
+  | message_id_header
+  | date_header
+  | url_header
+  | text_header
+]
+
+type custom_header = [ `Custom of string ]
+
+type any_header = [ standard_header | custom_header ]
+
+let standard_header_to_string : [< standard_header ] -> string = function
+  | `From -> "From"
+  | `Sender -> "Sender"
+  | `Reply_to -> "Reply-To"
+  | `To -> "To"
+  | `Cc -> "Cc"
+  | `Bcc -> "Bcc"
+  | `Resent_from -> "Resent-From"
+  | `Resent_sender -> "Resent-Sender"
+  | `Resent_reply_to -> "Resent-Reply-To"
+  | `Resent_to -> "Resent-To"
+  | `Resent_cc -> "Resent-Cc"
+  | `Resent_bcc -> "Resent-Bcc"
+  | `Message_id -> "Message-ID"
+  | `In_reply_to -> "In-Reply-To"
+  | `References -> "References"
+  | `Resent_message_id -> "Resent-Message-ID"
+  | `Date -> "Date"
+  | `Resent_date -> "Resent-Date"
+  | `List_help -> "List-Help"
+  | `List_unsubscribe -> "List-Unsubscribe"
+  | `List_subscribe -> "List-Subscribe"
+  | `List_post -> "List-Post"
+  | `List_owner -> "List-Owner"
+  | `List_archive -> "List-Archive"
+  | `Subject -> "Subject"
+  | `Comments -> "Comments"
+  | `Keywords -> "Keywords"
+  | `List_id -> "List-Id"
+
+let standard_header_of_string s : standard_header option =
+  match String.lowercase_ascii s with
+  | "from" -> Some `From
+  | "sender" -> Some `Sender
+  | "reply-to" -> Some `Reply_to
+  | "to" -> Some `To
+  | "cc" -> Some `Cc
+  | "bcc" -> Some `Bcc
+  | "resent-from" -> Some `Resent_from
+  | "resent-sender" -> Some `Resent_sender
+  | "resent-reply-to" -> Some `Resent_reply_to
+  | "resent-to" -> Some `Resent_to
+  | "resent-cc" -> Some `Resent_cc
+  | "resent-bcc" -> Some `Resent_bcc
+  | "message-id" -> Some `Message_id
+  | "in-reply-to" -> Some `In_reply_to
+  | "references" -> Some `References
+  | "resent-message-id" -> Some `Resent_message_id
+  | "date" -> Some `Date
+  | "resent-date" -> Some `Resent_date
+  | "list-help" -> Some `List_help
+  | "list-unsubscribe" -> Some `List_unsubscribe
+  | "list-subscribe" -> Some `List_subscribe
+  | "list-post" -> Some `List_post
+  | "list-owner" -> Some `List_owner
+  | "list-archive" -> Some `List_archive
+  | "subject" -> Some `Subject
+  | "comments" -> Some `Comments
+  | "keywords" -> Some `Keywords
+  | "list-id" -> Some `List_id
+  | _ -> None
+
+let any_header_to_string : [< any_header ] -> string = function
+  | `Custom s -> s
+  | #standard_header as h -> standard_header_to_string h
+
+(* Header parsed forms *)
+
+type form = [
+  | `Raw
+  | `Text
+  | `Addresses
+  | `Grouped_addresses
+  | `Message_ids
+  | `Date
+  | `Urls
+]
+
+let form_to_string : [< form ] -> string = function
+  | `Raw -> ""
+  | `Text -> "asText"
+  | `Addresses -> "asAddresses"
+  | `Grouped_addresses -> "asGroupedAddresses"
+  | `Message_ids -> "asMessageIds"
+  | `Date -> "asDate"
+  | `Urls -> "asURLs"
+
+let form_of_string s : form option =
+  match s with
+  | "" -> Some `Raw
+  | "asText" -> Some `Text
+  | "asAddresses" -> Some `Addresses
+  | "asGroupedAddresses" -> Some `Grouped_addresses
+  | "asMessageIds" -> Some `Message_ids
+  | "asDate" -> Some `Date
+  | "asURLs" -> Some `Urls
+  | _ -> None
+
+(* Header property requests *)
+
+type header_property =
+  | Raw of { name : string; all : bool }
+  | Text of { header : [ text_header | custom_header ]; all : bool }
+  | Addresses of { header : [ address_header | custom_header ]; all : bool }
+  | Grouped_addresses of { header : [ address_header | custom_header ]; all : bool }
+  | Message_ids of { header : [ message_id_header | custom_header ]; all : bool }
+  | Date of { header : [ date_header | custom_header ]; all : bool }
+  | Urls of { header : [ url_header | custom_header ]; all : bool }
+
+let header_name_of_property : header_property -> string = function
+  | Raw { name; _ } -> name
+  | Text { header; _ } -> any_header_to_string (header :> any_header)
+  | Addresses { header; _ } -> any_header_to_string (header :> any_header)
+  | Grouped_addresses { header; _ } -> any_header_to_string (header :> any_header)
+  | Message_ids { header; _ } -> any_header_to_string (header :> any_header)
+  | Date { header; _ } -> any_header_to_string (header :> any_header)
+  | Urls { header; _ } -> any_header_to_string (header :> any_header)
+
+let header_property_all : header_property -> bool = function
+  | Raw { all; _ } -> all
+  | Text { all; _ } -> all
+  | Addresses { all; _ } -> all
+  | Grouped_addresses { all; _ } -> all
+  | Message_ids { all; _ } -> all
+  | Date { all; _ } -> all
+  | Urls { all; _ } -> all
+
+let header_property_form : header_property -> form = function
+  | Raw _ -> `Raw
+  | Text _ -> `Text
+  | Addresses _ -> `Addresses
+  | Grouped_addresses _ -> `Grouped_addresses
+  | Message_ids _ -> `Message_ids
+  | Date _ -> `Date
+  | Urls _ -> `Urls
+
+let header_property_to_string prop =
+  let name = header_name_of_property prop in
+  let form = form_to_string (header_property_form prop) in
+  let all_suffix = if header_property_all prop then ":all" else "" in
+  let form_suffix = if form = "" then "" else ":" ^ form in
+  "header:" ^ name ^ form_suffix ^ all_suffix
+
+let header_property_of_string s : header_property option =
+  if not (String.length s > 7 && String.sub s 0 7 = "header:") then
+    None
+  else
+    let rest = String.sub s 7 (String.length s - 7) in
+    (* Parse the parts: name[:form][:all] *)
+    let parts = String.split_on_char ':' rest in
+    match parts with
+    | [] -> None
+    | [name] ->
+      Some (Raw { name; all = false })
+    | [name; second] ->
+      if second = "all" then
+        Some (Raw { name; all = true })
+      else begin
+        match form_of_string second with
+        | None -> None
+        | Some `Raw -> Some (Raw { name; all = false })
+        | Some `Text -> Some (Text { header = `Custom name; all = false })
+        | Some `Addresses -> Some (Addresses { header = `Custom name; all = false })
+        | Some `Grouped_addresses -> Some (Grouped_addresses { header = `Custom name; all = false })
+        | Some `Message_ids -> Some (Message_ids { header = `Custom name; all = false })
+        | Some `Date -> Some (Date { header = `Custom name; all = false })
+        | Some `Urls -> Some (Urls { header = `Custom name; all = false })
+      end
+    | [name; form_str; "all"] ->
+      begin match form_of_string form_str with
+      | None -> None
+      | Some `Raw -> Some (Raw { name; all = true })
+      | Some `Text -> Some (Text { header = `Custom name; all = true })
+      | Some `Addresses -> Some (Addresses { header = `Custom name; all = true })
+      | Some `Grouped_addresses -> Some (Grouped_addresses { header = `Custom name; all = true })
+      | Some `Message_ids -> Some (Message_ids { header = `Custom name; all = true })
+      | Some `Date -> Some (Date { header = `Custom name; all = true })
+      | Some `Urls -> Some (Urls { header = `Custom name; all = true })
+      end
+    | _ -> None
+
+(* Convenience constructors *)
+
+let raw ?(all=false) name = Raw { name; all }
+
+let text ?(all=false) header = Text { header; all }
+
+let addresses ?(all=false) header = Addresses { header; all }
+
+let grouped_addresses ?(all=false) header = Grouped_addresses { header; all }
+
+let message_ids ?(all=false) header = Message_ids { header; all }
+
+let date ?(all=false) header = Date { header; all }
+
+let urls ?(all=false) header = Urls { header; all }
+
+(* Header values in responses *)
+
+type header_value =
+  | String_single of string option
+  | String_all of string list
+  | Addresses_single of Mail_address.t list option
+  | Addresses_all of Mail_address.t list list
+  | Grouped_single of Mail_address.Group.t list option
+  | Grouped_all of Mail_address.Group.t list list
+  | Date_single of Ptime.t option
+  | Date_all of Ptime.t option list
+  | Strings_single of string list option
+  | Strings_all of string list option list
+
+let header_value_jsont ~form ~all : header_value Jsont.t =
+  match form, all with
+  | (`Raw | `Text), false ->
+    Jsont.map
+      ~dec:(fun s -> String_single s)
+      ~enc:(function String_single s -> s | _ -> None)
+      (Jsont.option Jsont.string)
+  | (`Raw | `Text), true ->
+    Jsont.map
+      ~dec:(fun l -> String_all l)
+      ~enc:(function String_all l -> l | _ -> [])
+      (Jsont.list Jsont.string)
+  | `Addresses, false ->
+    Jsont.map
+      ~dec:(fun l -> Addresses_single l)
+      ~enc:(function Addresses_single l -> l | _ -> None)
+      (Jsont.option (Jsont.list Mail_address.jsont))
+  | `Addresses, true ->
+    Jsont.map
+      ~dec:(fun l -> Addresses_all l)
+      ~enc:(function Addresses_all l -> l | _ -> [])
+      (Jsont.list (Jsont.list Mail_address.jsont))
+  | `Grouped_addresses, false ->
+    Jsont.map
+      ~dec:(fun l -> Grouped_single l)
+      ~enc:(function Grouped_single l -> l | _ -> None)
+      (Jsont.option (Jsont.list Mail_address.Group.jsont))
+  | `Grouped_addresses, true ->
+    Jsont.map
+      ~dec:(fun l -> Grouped_all l)
+      ~enc:(function Grouped_all l -> l | _ -> [])
+      (Jsont.list (Jsont.list Mail_address.Group.jsont))
+  | `Message_ids, false ->
+    Jsont.map
+      ~dec:(fun l -> Strings_single l)
+      ~enc:(function Strings_single l -> l | _ -> None)
+      (Jsont.option (Jsont.list Jsont.string))
+  | `Message_ids, true ->
+    Jsont.map
+      ~dec:(fun l -> Strings_all l)
+      ~enc:(function Strings_all l -> l | _ -> [])
+      (Jsont.list (Jsont.option (Jsont.list Jsont.string)))
+  | `Date, false ->
+    Jsont.map
+      ~dec:(fun t -> Date_single t)
+      ~enc:(function Date_single t -> t | _ -> None)
+      (Jsont.option Proto_date.Rfc3339.jsont)
+  | `Date, true ->
+    Jsont.map
+      ~dec:(fun l -> Date_all l)
+      ~enc:(function Date_all l -> l | _ -> [])
+      (Jsont.list (Jsont.option Proto_date.Rfc3339.jsont))
+  | `Urls, false ->
+    Jsont.map
+      ~dec:(fun l -> Strings_single l)
+      ~enc:(function Strings_single l -> l | _ -> None)
+      (Jsont.option (Jsont.list Jsont.string))
+  | `Urls, true ->
+    Jsont.map
+      ~dec:(fun l -> Strings_all l)
+      ~enc:(function Strings_all l -> l | _ -> [])
+      (Jsont.list (Jsont.option (Jsont.list Jsont.string)))
+
+(* Low-level JSON codecs *)
 
 let raw_jsont = Jsont.string
 

lib/mail/mail_header.mli

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
-(** Email header types as defined in RFC 8621 Section 4.1.2 
+(** Email header types as defined in RFC 8621 Section 4.1.2
 
     @canonical Jmap.Proto.Email_header *)
 
···
 
 val jsont : t Jsont.t
 
+(** {1 Header Categories}
+
+    RFC 8621 Section 4.1.2 restricts which parsed forms can be used with
+    which headers. These polymorphic variant types encode those restrictions
+    at the type level.
+
+    Each category corresponds to headers that share the same allowed forms:
+    - Address headers: can use [Addresses] and [Grouped_addresses] forms
+    - Message-ID headers: can use [Message_ids] form
+    - Date headers: can use [Date] form
+    - URL headers: can use [Urls] form
+    - Text headers: can use [Text] form
+    - All headers can use [Raw] form
+    - Custom headers (not in RFC 5322/2369) can use any form *)
+
+(** Headers that allow the [Addresses] and [Grouped_addresses] forms.
+    These are address-list headers per RFC 5322. *)
+type address_header = [
+  | `From
+  | `Sender
+  | `Reply_to
+  | `To
+  | `Cc
+  | `Bcc
+  | `Resent_from
+  | `Resent_sender
+  | `Resent_reply_to
+  | `Resent_to
+  | `Resent_cc
+  | `Resent_bcc
+]
+
+(** Headers that allow the [Message_ids] form.
+    These contain msg-id values per RFC 5322. *)
+type message_id_header = [
+  | `Message_id
+  | `In_reply_to
+  | `References
+  | `Resent_message_id
+]
+
+(** Headers that allow the [Date] form.
+    These contain date-time values per RFC 5322. *)
+type date_header = [
+  | `Date
+  | `Resent_date
+]
+
+(** Headers that allow the [Urls] form.
+    These are list-* headers per RFC 2369. *)
+type url_header = [
+  | `List_help
+  | `List_unsubscribe
+  | `List_subscribe
+  | `List_post
+  | `List_owner
+  | `List_archive
+]
+
+(** Headers that allow the [Text] form.
+    These contain unstructured or phrase content. *)
+type text_header = [
+  | `Subject
+  | `Comments
+  | `Keywords
+  | `List_id
+]
+
+(** All standard headers defined in RFC 5322 and RFC 2369. *)
+type standard_header = [
+  | address_header
+  | message_id_header
+  | date_header
+  | url_header
+  | text_header
+]
+
+(** A custom header not defined in RFC 5322 or RFC 2369.
+    Custom headers can use any parsed form. *)
+type custom_header = [ `Custom of string ]
+
+(** Any header - standard or custom. *)
+type any_header = [ standard_header | custom_header ]
+
+(** {2 Header Name Conversion} *)
+
+val standard_header_to_string : [< standard_header ] -> string
+(** Convert a standard header variant to its wire name (e.g., [`From] -> "From"). *)
+
+val standard_header_of_string : string -> standard_header option
+(** Parse a header name to a standard header variant, case-insensitive.
+    Returns [None] for non-standard headers. *)
+
+val any_header_to_string : [< any_header ] -> string
+(** Convert any header variant to its wire name. *)
+
 (** {1 Header Parsed Forms}
 
     RFC 8621 defines several parsed forms for headers.
-    These can be requested via the header:Name:form properties. *)
+    These can be requested via the [header:Name:form] properties. *)
+
+(** The parsed form to request for a header value. *)
+type form = [
+  | `Raw               (** Raw octets, available for all headers *)
+  | `Text              (** Decoded text, for text headers or custom *)
+  | `Addresses         (** Flat address list, for address headers or custom *)
+  | `Grouped_addresses (** Address list with groups, for address headers or custom *)
+  | `Message_ids       (** List of message-id strings, for message-id headers or custom *)
+  | `Date              (** Parsed date, for date headers or custom *)
+  | `Urls              (** List of URLs, for url headers or custom *)
+]
+
+val form_to_string : [< form ] -> string
+(** Convert form to wire suffix (e.g., [`Addresses] -> "asAddresses").
+    [`Raw] returns the empty string (raw is the default). *)
+
+val form_of_string : string -> form option
+(** Parse a form suffix (e.g., "asAddresses" -> [`Addresses]).
+    Empty string returns [`Raw]. *)
+
+(** {1 Header Property Requests}
+
+    Type-safe construction of [header:Name:form:all] property strings.
+    The GADT ensures that only valid form/header combinations are allowed. *)
+
+(** A header property request with type-safe form selection.
+
+    The type parameter encodes what forms are allowed:
+    - Address headers allow [Addresses] and [Grouped_addresses]
+    - Message-ID headers allow [Message_ids]
+    - Date headers allow [Date]
+    - URL headers allow [Urls]
+    - Text headers allow [Text]
+    - All headers allow [Raw]
+    - Custom headers allow any form *)
+type header_property =
+  | Raw of { name : string; all : bool }
+  (** Raw form, available for any header. *)
+
+  | Text of { header : [ text_header | custom_header ]; all : bool }
+  (** Text form, for text headers or custom. *)
+
+  | Addresses of { header : [ address_header | custom_header ]; all : bool }
+  (** Addresses form, for address headers or custom. *)
+
+  | Grouped_addresses of { header : [ address_header | custom_header ]; all : bool }
+  (** GroupedAddresses form, for address headers or custom. *)
+
+  | Message_ids of { header : [ message_id_header | custom_header ]; all : bool }
+  (** MessageIds form, for message-id headers or custom. *)
+
+  | Date of { header : [ date_header | custom_header ]; all : bool }
+  (** Date form, for date headers or custom. *)
+
+  | Urls of { header : [ url_header | custom_header ]; all : bool }
+  (** URLs form, for URL headers or custom. *)
+
+val header_property_to_string : header_property -> string
+(** Convert a header property request to wire format.
+    E.g., [Addresses { header = `From; all = true }] -> "header:From:asAddresses:all" *)
+
+val header_property_of_string : string -> header_property option
+(** Parse a header property string.
+    Returns [None] if the string doesn't match [header:*] format. *)
+
+(** {2 Convenience Constructors} *)
+
+val raw : ?all:bool -> string -> header_property
+(** [raw ?all name] creates a raw header property request. *)
+
+val text : ?all:bool -> [ text_header | custom_header ] -> header_property
+(** [text ?all header] creates a text header property request. *)
+
+val addresses : ?all:bool -> [ address_header | custom_header ] -> header_property
+(** [addresses ?all header] creates an addresses header property request. *)
+
+val grouped_addresses : ?all:bool -> [ address_header | custom_header ] -> header_property
+(** [grouped_addresses ?all header] creates a grouped addresses header property request. *)
+
+val message_ids : ?all:bool -> [ message_id_header | custom_header ] -> header_property
+(** [message_ids ?all header] creates a message-ids header property request. *)
+
+val date : ?all:bool -> [ date_header | custom_header ] -> header_property
+(** [date ?all header] creates a date header property request. *)
+
+val urls : ?all:bool -> [ url_header | custom_header ] -> header_property
+(** [urls ?all header] creates a URLs header property request. *)
+
+(** {1 Header Values in Responses}
+
+    When fetching dynamic headers, the response value type depends on the
+    requested form. This type captures all possible response shapes. *)
+
+(** A header value from the response.
+
+    The variant encodes both the form and whether [:all] was requested:
+    - [*_single] variants: value of the last header instance, or [None] if absent
+    - [*_all] variants: list of values for all instances, empty if absent *)
+type header_value =
+  | String_single of string option
+  (** Raw or Text form, single instance. *)
+
+  | String_all of string list
+  (** Raw or Text form, all instances. *)
+
+  | Addresses_single of Mail_address.t list option
+  (** Addresses form, single instance. *)
+
+  | Addresses_all of Mail_address.t list list
+  (** Addresses form, all instances. *)
+
+  | Grouped_single of Mail_address.Group.t list option
+  (** GroupedAddresses form, single instance. *)
+
+  | Grouped_all of Mail_address.Group.t list list
+  (** GroupedAddresses form, all instances. *)
+
+  | Date_single of Ptime.t option
+  (** Date form, single instance. *)
+
+  | Date_all of Ptime.t option list
+  (** Date form, all instances. *)
+
+  | Strings_single of string list option
+  (** MessageIds or URLs form, single instance. *)
+
+  | Strings_all of string list option list
+  (** MessageIds or URLs form, all instances. *)
+
+val header_value_jsont : form:form -> all:bool -> header_value Jsont.t
+(** [header_value_jsont ~form ~all] returns a JSON codec for header values
+    with the given form and multiplicity. *)
+
+(** {1 Low-level JSON Codecs}
+
+    These codecs are used internally and for custom header processing. *)
 
 (** The raw form - header value as-is. *)
 val raw_jsont : string Jsont.t

lib/mail/mail_identity.ml

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
+(* Identity properties *)
+
+type property = [
+  | `Id
+  | `Name
+  | `Email
+  | `Reply_to
+  | `Bcc
+  | `Text_signature
+  | `Html_signature
+  | `May_delete
+]
+
+let property_to_string : [< property ] -> string = function
+  | `Id -> "id"
+  | `Name -> "name"
+  | `Email -> "email"
+  | `Reply_to -> "replyTo"
+  | `Bcc -> "bcc"
+  | `Text_signature -> "textSignature"
+  | `Html_signature -> "htmlSignature"
+  | `May_delete -> "mayDelete"
+
+let property_of_string s : property option =
+  match s with
+  | "id" -> Some `Id
+  | "name" -> Some `Name
+  | "email" -> Some `Email
+  | "replyTo" -> Some `Reply_to
+  | "bcc" -> Some `Bcc
+  | "textSignature" -> Some `Text_signature
+  | "htmlSignature" -> Some `Html_signature
+  | "mayDelete" -> Some `May_delete
+  | _ -> None
+
+(* Identity type *)
+
 type t = {
-  id : Proto_id.t;
-  name : string;
-  email : string;
+  id : Proto_id.t option;
+  name : string option;
+  email : string option;
   reply_to : Mail_address.t list option;
   bcc : Mail_address.t list option;
-  text_signature : string;
-  html_signature : string;
-  may_delete : bool;
+  text_signature : string option;
+  html_signature : string option;
+  may_delete : bool option;
 }
 
 let id t = t.id
···
 let jsont =
   let kind = "Identity" in
   Jsont.Object.map ~kind make
-  |> Jsont.Object.mem "id" Proto_id.jsont ~enc:id
-  |> Jsont.Object.mem "name" Jsont.string ~dec_absent:"" ~enc:name
-  |> Jsont.Object.mem "email" Jsont.string ~enc:email
+  |> Jsont.Object.opt_mem "id" Proto_id.jsont ~enc:id
+  |> Jsont.Object.opt_mem "name" Jsont.string ~enc:name
+  |> Jsont.Object.opt_mem "email" Jsont.string ~enc:email
   |> Jsont.Object.opt_mem "replyTo" (Jsont.list Mail_address.jsont) ~enc:reply_to
   |> Jsont.Object.opt_mem "bcc" (Jsont.list Mail_address.jsont) ~enc:bcc
-  |> Jsont.Object.mem "textSignature" Jsont.string ~dec_absent:"" ~enc:text_signature
-  |> Jsont.Object.mem "htmlSignature" Jsont.string ~dec_absent:"" ~enc:html_signature
-  |> Jsont.Object.mem "mayDelete" Jsont.bool ~enc:may_delete
+  |> Jsont.Object.opt_mem "textSignature" Jsont.string ~enc:text_signature
+  |> Jsont.Object.opt_mem "htmlSignature" Jsont.string ~enc:html_signature
+  |> Jsont.Object.opt_mem "mayDelete" Jsont.bool ~enc:may_delete
   |> Jsont.Object.finish

lib/mail/mail_identity.mli

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
-(** Identity type as defined in RFC 8621 Section 6 
+(** Identity type as defined in RFC 8621 Section 6
 
     @canonical Jmap.Proto.Identity *)
 
+(** {1 Identity Properties}
+
+    Polymorphic variants for type-safe property selection in Identity/get requests.
+    These correspond to the properties defined in RFC 8621 Section 6. *)
+
+(** All Identity properties that can be requested. *)
+type property = [
+  | `Id
+  | `Name
+  | `Email
+  | `Reply_to
+  | `Bcc
+  | `Text_signature
+  | `Html_signature
+  | `May_delete
+]
+
+val property_to_string : [< property ] -> string
+(** Convert a property to its wire name (e.g., [`Text_signature] -> "textSignature"). *)
+
+val property_of_string : string -> property option
+(** Parse a property name, case-sensitive. *)
+
+(** {1 Identity Object} *)
+
 type t = {
-  id : Proto_id.t;
+  id : Proto_id.t option;
   (** Server-assigned identity id. *)
-  name : string;
+  name : string option;
   (** Display name for sent emails. *)
-  email : string;
+  email : string option;
   (** The email address to use. *)
   reply_to : Mail_address.t list option;
   (** Default Reply-To addresses. *)
   bcc : Mail_address.t list option;
   (** Default BCC addresses. *)
-  text_signature : string;
+  text_signature : string option;
   (** Plain text signature. *)
-  html_signature : string;
+  html_signature : string option;
   (** HTML signature. *)
-  may_delete : bool;
+  may_delete : bool option;
   (** Whether the user may delete this identity. *)
 }
 
-val id : t -> Proto_id.t
-val name : t -> string
-val email : t -> string
+val id : t -> Proto_id.t option
+val name : t -> string option
+val email : t -> string option
 val reply_to : t -> Mail_address.t list option
 val bcc : t -> Mail_address.t list option
-val text_signature : t -> string
-val html_signature : t -> string
-val may_delete : t -> bool
+val text_signature : t -> string option
+val html_signature : t -> string option
+val may_delete : t -> bool option
 
 val jsont : t Jsont.t

lib/mail/mail_mailbox.ml

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
+(* Mailbox properties *)
+
+type property = [
+  | `Id
+  | `Name
+  | `Parent_id
+  | `Role
+  | `Sort_order
+  | `Total_emails
+  | `Unread_emails
+  | `Total_threads
+  | `Unread_threads
+  | `My_rights
+  | `Is_subscribed
+]
+
+let property_to_string : [< property ] -> string = function
+  | `Id -> "id"
+  | `Name -> "name"
+  | `Parent_id -> "parentId"
+  | `Role -> "role"
+  | `Sort_order -> "sortOrder"
+  | `Total_emails -> "totalEmails"
+  | `Unread_emails -> "unreadEmails"
+  | `Total_threads -> "totalThreads"
+  | `Unread_threads -> "unreadThreads"
+  | `My_rights -> "myRights"
+  | `Is_subscribed -> "isSubscribed"
+
+let property_of_string s : property option =
+  match s with
+  | "id" -> Some `Id
+  | "name" -> Some `Name
+  | "parentId" -> Some `Parent_id
+  | "role" -> Some `Role
+  | "sortOrder" -> Some `Sort_order
+  | "totalEmails" -> Some `Total_emails
+  | "unreadEmails" -> Some `Unread_emails
+  | "totalThreads" -> Some `Total_threads
+  | "unreadThreads" -> Some `Unread_threads
+  | "myRights" -> Some `My_rights
+  | "isSubscribed" -> Some `Is_subscribed
+  | _ -> None
+
 module Rights = struct
   type t = {
     may_read_items : bool;
···
     Jsont.string
 
 type t = {
-  id : Proto_id.t;
-  name : string;
+  id : Proto_id.t option;
+  name : string option;
   parent_id : Proto_id.t option;
   role : role option;
-  sort_order : int64;
-  total_emails : int64;
-  unread_emails : int64;
-  total_threads : int64;
-  unread_threads : int64;
-  my_rights : Rights.t;
-  is_subscribed : bool;
+  sort_order : int64 option;
+  total_emails : int64 option;
+  unread_emails : int64 option;
+  total_threads : int64 option;
+  unread_threads : int64 option;
+  my_rights : Rights.t option;
+  is_subscribed : bool option;
 }
 
 let id t = t.id
···
 
 let jsont =
   let kind = "Mailbox" in
-  (* parentId and role can be null - RFC 8621 Section 2 *)
-  let nullable_id = Jsont.(option Proto_id.jsont) in
-  let nullable_role = Jsont.(option role_jsont) in
   Jsont.Object.map ~kind make
-  |> Jsont.Object.mem "id" Proto_id.jsont ~enc:id
-  |> Jsont.Object.mem "name" Jsont.string ~enc:name
-  |> Jsont.Object.mem "parentId" nullable_id
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:parent_id
-  |> Jsont.Object.mem "role" nullable_role
-       ~dec_absent:None ~enc_omit:Option.is_none ~enc:role
-  |> Jsont.Object.mem "sortOrder" Proto_int53.Unsigned.jsont ~dec_absent:0L ~enc:sort_order
-  |> Jsont.Object.mem "totalEmails" Proto_int53.Unsigned.jsont ~enc:total_emails
-  |> Jsont.Object.mem "unreadEmails" Proto_int53.Unsigned.jsont ~enc:unread_emails
-  |> Jsont.Object.mem "totalThreads" Proto_int53.Unsigned.jsont ~enc:total_threads
-  |> Jsont.Object.mem "unreadThreads" Proto_int53.Unsigned.jsont ~enc:unread_threads
-  |> Jsont.Object.mem "myRights" Rights.jsont ~enc:my_rights
-  |> Jsont.Object.mem "isSubscribed" Jsont.bool ~enc:is_subscribed
+  |> Jsont.Object.opt_mem "id" Proto_id.jsont ~enc:id
+  |> Jsont.Object.opt_mem "name" Jsont.string ~enc:name
+  (* parentId can be null meaning top-level, or absent if not requested *)
+  |> Jsont.Object.opt_mem "parentId" Proto_id.jsont ~enc:parent_id
+  (* role can be null meaning no role, or absent if not requested *)
+  |> Jsont.Object.opt_mem "role" role_jsont ~enc:role
+  |> Jsont.Object.opt_mem "sortOrder" Proto_int53.Unsigned.jsont ~enc:sort_order
+  |> Jsont.Object.opt_mem "totalEmails" Proto_int53.Unsigned.jsont ~enc:total_emails
+  |> Jsont.Object.opt_mem "unreadEmails" Proto_int53.Unsigned.jsont ~enc:unread_emails
+  |> Jsont.Object.opt_mem "totalThreads" Proto_int53.Unsigned.jsont ~enc:total_threads
+  |> Jsont.Object.opt_mem "unreadThreads" Proto_int53.Unsigned.jsont ~enc:unread_threads
+  |> Jsont.Object.opt_mem "myRights" Rights.jsont ~enc:my_rights
+  |> Jsont.Object.opt_mem "isSubscribed" Jsont.bool ~enc:is_subscribed
   |> Jsont.Object.finish
 
 module Filter_condition = struct

lib/mail/mail_mailbox.mli

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
-(** Mailbox type as defined in RFC 8621 Section 2 
+(** Mailbox type as defined in RFC 8621 Section 2
 
     @canonical Jmap.Proto.Mailbox *)
+
+(** {1 Mailbox Properties}
+
+    Polymorphic variants for type-safe property selection in Mailbox/get requests.
+    These correspond to the properties defined in RFC 8621 Section 2. *)
+
+(** All Mailbox properties that can be requested. *)
+type property = [
+  | `Id
+  | `Name
+  | `Parent_id
+  | `Role
+  | `Sort_order
+  | `Total_emails
+  | `Unread_emails
+  | `Total_threads
+  | `Unread_threads
+  | `My_rights
+  | `Is_subscribed
+]
+
+val property_to_string : [< property ] -> string
+(** Convert a property to its wire name (e.g., [`Parent_id] -> "parentId"). *)
+
+val property_of_string : string -> property option
+(** Parse a property name, case-sensitive. *)
 
 (** {1 Mailbox Rights} *)
 
···
 (** {1 Mailbox} *)
 
 type t = {
-  id : Proto_id.t;
+  id : Proto_id.t option;
   (** Server-assigned mailbox id. *)
-  name : string;
+  name : string option;
   (** User-visible name (UTF-8). *)
   parent_id : Proto_id.t option;
-  (** Id of parent mailbox, or [None] for root. *)
+  (** Id of parent mailbox, or [None] for root. Note: [None] can mean
+      either "not requested" or "top-level mailbox". *)
   role : role option;
-  (** Standard role, if any. *)
-  sort_order : int64;
+  (** Standard role, if any. Note: [None] can mean either "not requested"
+      or "no role assigned". *)
+  sort_order : int64 option;
   (** Sort order hint (lower = displayed first). *)
-  total_emails : int64;
+  total_emails : int64 option;
   (** Total number of emails in mailbox. *)
-  unread_emails : int64;
+  unread_emails : int64 option;
   (** Number of unread emails. *)
-  total_threads : int64;
+  total_threads : int64 option;
   (** Total number of threads. *)
-  unread_threads : int64;
+  unread_threads : int64 option;
   (** Number of threads with unread emails. *)
-  my_rights : Rights.t;
+  my_rights : Rights.t option;
   (** User's rights on this mailbox. *)
-  is_subscribed : bool;
+  is_subscribed : bool option;
   (** Whether user is subscribed to this mailbox. *)
 }
 
-val id : t -> Proto_id.t
-val name : t -> string
+val id : t -> Proto_id.t option
+val name : t -> string option
 val parent_id : t -> Proto_id.t option
 val role : t -> role option
-val sort_order : t -> int64
-val total_emails : t -> int64
-val unread_emails : t -> int64
-val total_threads : t -> int64
-val unread_threads : t -> int64
-val my_rights : t -> Rights.t
-val is_subscribed : t -> bool
+val sort_order : t -> int64 option
+val total_emails : t -> int64 option
+val unread_emails : t -> int64 option
+val total_threads : t -> int64 option
+val unread_threads : t -> int64 option
+val my_rights : t -> Rights.t option
+val is_subscribed : t -> bool option
 
 val jsont : t Jsont.t
 

lib/mail/mail_submission.ml

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
+(* EmailSubmission properties *)
+
+type property = [
+  | `Id
+  | `Identity_id
+  | `Email_id
+  | `Thread_id
+  | `Envelope
+  | `Send_at
+  | `Undo_status
+  | `Delivery_status
+  | `Dsn_blob_ids
+  | `Mdn_blob_ids
+]
+
+let property_to_string : [< property ] -> string = function
+  | `Id -> "id"
+  | `Identity_id -> "identityId"
+  | `Email_id -> "emailId"
+  | `Thread_id -> "threadId"
+  | `Envelope -> "envelope"
+  | `Send_at -> "sendAt"
+  | `Undo_status -> "undoStatus"
+  | `Delivery_status -> "deliveryStatus"
+  | `Dsn_blob_ids -> "dsnBlobIds"
+  | `Mdn_blob_ids -> "mdnBlobIds"
+
+let property_of_string s : property option =
+  match s with
+  | "id" -> Some `Id
+  | "identityId" -> Some `Identity_id
+  | "emailId" -> Some `Email_id
+  | "threadId" -> Some `Thread_id
+  | "envelope" -> Some `Envelope
+  | "sendAt" -> Some `Send_at
+  | "undoStatus" -> Some `Undo_status
+  | "deliveryStatus" -> Some `Delivery_status
+  | "dsnBlobIds" -> Some `Dsn_blob_ids
+  | "mdnBlobIds" -> Some `Mdn_blob_ids
+  | _ -> None
+
 module Address = struct
   type t = {
     email : string;
···
     ~dec:undo_status_of_string ~enc:undo_status_to_string Jsont.string
 
 type t = {
-  id : Proto_id.t;
-  identity_id : Proto_id.t;
-  email_id : Proto_id.t;
-  thread_id : Proto_id.t;
+  id : Proto_id.t option;
+  identity_id : Proto_id.t option;
+  email_id : Proto_id.t option;
+  thread_id : Proto_id.t option;
   envelope : Envelope.t option;
-  send_at : Ptime.t;
-  undo_status : undo_status;
+  send_at : Ptime.t option;
+  undo_status : undo_status option;
   delivery_status : (string * Delivery_status.t) list option;
-  dsn_blob_ids : Proto_id.t list;
-  mdn_blob_ids : Proto_id.t list;
+  dsn_blob_ids : Proto_id.t list option;
+  mdn_blob_ids : Proto_id.t list option;
 }
 
 let id t = t.id
···
 let jsont =
   let kind = "EmailSubmission" in
   Jsont.Object.map ~kind make
-  |> Jsont.Object.mem "id" Proto_id.jsont ~enc:id
-  |> Jsont.Object.mem "identityId" Proto_id.jsont ~enc:identity_id
-  |> Jsont.Object.mem "emailId" Proto_id.jsont ~enc:email_id
-  |> Jsont.Object.mem "threadId" Proto_id.jsont ~enc:thread_id
+  |> Jsont.Object.opt_mem "id" Proto_id.jsont ~enc:id
+  |> Jsont.Object.opt_mem "identityId" Proto_id.jsont ~enc:identity_id
+  |> Jsont.Object.opt_mem "emailId" Proto_id.jsont ~enc:email_id
+  |> Jsont.Object.opt_mem "threadId" Proto_id.jsont ~enc:thread_id
   |> Jsont.Object.opt_mem "envelope" Envelope.jsont ~enc:envelope
-  |> Jsont.Object.mem "sendAt" Proto_date.Utc.jsont ~enc:send_at
-  |> Jsont.Object.mem "undoStatus" undo_status_jsont ~enc:undo_status
+  |> Jsont.Object.opt_mem "sendAt" Proto_date.Utc.jsont ~enc:send_at
+  |> Jsont.Object.opt_mem "undoStatus" undo_status_jsont ~enc:undo_status
   |> Jsont.Object.opt_mem "deliveryStatus" (Proto_json_map.of_string Delivery_status.jsont) ~enc:delivery_status
-  |> Jsont.Object.mem "dsnBlobIds" (Jsont.list Proto_id.jsont) ~dec_absent:[] ~enc:dsn_blob_ids
-  |> Jsont.Object.mem "mdnBlobIds" (Jsont.list Proto_id.jsont) ~dec_absent:[] ~enc:mdn_blob_ids
+  |> Jsont.Object.opt_mem "dsnBlobIds" (Jsont.list Proto_id.jsont) ~enc:dsn_blob_ids
+  |> Jsont.Object.opt_mem "mdnBlobIds" (Jsont.list Proto_id.jsont) ~enc:mdn_blob_ids
   |> Jsont.Object.finish
 
 module Filter_condition = struct

lib/mail/mail_submission.mli

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
-(** EmailSubmission type as defined in RFC 8621 Section 7 
+(** EmailSubmission type as defined in RFC 8621 Section 7
 
     @canonical Jmap.Proto.Submission *)
+
+(** {1 EmailSubmission Properties}
+
+    Polymorphic variants for type-safe property selection in EmailSubmission/get requests.
+    These correspond to the properties defined in RFC 8621 Section 7. *)
+
+(** All EmailSubmission properties that can be requested. *)
+type property = [
+  | `Id
+  | `Identity_id
+  | `Email_id
+  | `Thread_id
+  | `Envelope
+  | `Send_at
+  | `Undo_status
+  | `Delivery_status
+  | `Dsn_blob_ids
+  | `Mdn_blob_ids
+]
+
+val property_to_string : [< property ] -> string
+(** Convert a property to its wire name (e.g., [`Identity_id] -> "identityId"). *)
+
+val property_of_string : string -> property option
+(** Parse a property name, case-sensitive. *)
 
 (** {1 Address} *)
 
···
 (** {1 EmailSubmission} *)
 
 type t = {
-  id : Proto_id.t;
+  id : Proto_id.t option;
   (** Server-assigned submission id. *)
-  identity_id : Proto_id.t;
+  identity_id : Proto_id.t option;
   (** The identity used to send. *)
-  email_id : Proto_id.t;
+  email_id : Proto_id.t option;
   (** The email that was submitted. *)
-  thread_id : Proto_id.t;
+  thread_id : Proto_id.t option;
   (** The thread of the submitted email. *)
   envelope : Envelope.t option;
   (** The envelope used, if different from email headers. *)
-  send_at : Ptime.t;
+  send_at : Ptime.t option;
   (** When the email was/will be sent. *)
-  undo_status : undo_status;
+  undo_status : undo_status option;
   (** Whether sending can be undone. *)
   delivery_status : (string * Delivery_status.t) list option;
   (** Delivery status per recipient. *)
-  dsn_blob_ids : Proto_id.t list;
+  dsn_blob_ids : Proto_id.t list option;
   (** Blob ids of received DSN messages. *)
-  mdn_blob_ids : Proto_id.t list;
+  mdn_blob_ids : Proto_id.t list option;
   (** Blob ids of received MDN messages. *)
 }
 
-val id : t -> Proto_id.t
-val identity_id : t -> Proto_id.t
-val email_id : t -> Proto_id.t
-val thread_id : t -> Proto_id.t
+val id : t -> Proto_id.t option
+val identity_id : t -> Proto_id.t option
+val email_id : t -> Proto_id.t option
+val thread_id : t -> Proto_id.t option
 val envelope : t -> Envelope.t option
-val send_at : t -> Ptime.t
-val undo_status : t -> undo_status
+val send_at : t -> Ptime.t option
+val undo_status : t -> undo_status option
 val delivery_status : t -> (string * Delivery_status.t) list option
-val dsn_blob_ids : t -> Proto_id.t list
-val mdn_blob_ids : t -> Proto_id.t list
+val dsn_blob_ids : t -> Proto_id.t list option
+val mdn_blob_ids : t -> Proto_id.t list option
 
 val jsont : t Jsont.t
 

lib/mail/mail_thread.ml

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
+(* Thread properties *)
+
+type property = [
+  | `Id
+  | `Email_ids
+]
+
+let property_to_string : [< property ] -> string = function
+  | `Id -> "id"
+  | `Email_ids -> "emailIds"
+
+let property_of_string s : property option =
+  match s with
+  | "id" -> Some `Id
+  | "emailIds" -> Some `Email_ids
+  | _ -> None
+
+(* Thread type *)
+
 type t = {
-  id : Proto_id.t;
-  email_ids : Proto_id.t list;
+  id : Proto_id.t option;
+  email_ids : Proto_id.t list option;
 }
 
 let id t = t.id
···
 let jsont =
   let kind = "Thread" in
   Jsont.Object.map ~kind make
-  |> Jsont.Object.mem "id" Proto_id.jsont ~enc:id
-  |> Jsont.Object.mem "emailIds" (Jsont.list Proto_id.jsont) ~enc:email_ids
+  |> Jsont.Object.opt_mem "id" Proto_id.jsont ~enc:id
+  |> Jsont.Object.opt_mem "emailIds" (Jsont.list Proto_id.jsont) ~enc:email_ids
   |> Jsont.Object.finish

lib/mail/mail_thread.mli

···
    SPDX-License-Identifier: ISC
   ---------------------------------------------------------------------------*)
 
-(** Thread type as defined in RFC 8621 Section 3 
+(** Thread type as defined in RFC 8621 Section 3
 
     @canonical Jmap.Proto.Thread *)
 
+(** {1 Thread Properties}
+
+    Polymorphic variants for type-safe property selection in Thread/get requests.
+    Threads have only two properties per RFC 8621 Section 3. *)
+
+(** All Thread properties that can be requested. *)
+type property = [
+  | `Id
+  | `Email_ids
+]
+
+val property_to_string : [< property ] -> string
+(** Convert a property to its wire name (e.g., [`Email_ids] -> "emailIds"). *)
+
+val property_of_string : string -> property option
+(** Parse a property name, case-sensitive. *)
+
+(** {1 Thread Object} *)
+
 type t = {
-  id : Proto_id.t;
+  id : Proto_id.t option;
   (** Server-assigned thread id. *)
-  email_ids : Proto_id.t list;
+  email_ids : Proto_id.t list option;
   (** Ids of emails in this thread, in date order. *)
 }
 
-val id : t -> Proto_id.t
-val email_ids : t -> Proto_id.t list
+val id : t -> Proto_id.t option
+val email_ids : t -> Proto_id.t list option
 
 val jsont : t Jsont.t

lib/top/dune

···
+(include_subdirs no)
+
+(library
+ (name jmap_top)
+ (public_name jmap.top)
+ (libraries jmap jsont.bytesrw compiler-libs.toplevel))

lib/top/jmap_top.ml

···
+(* Toplevel printers for JMAP types
+
+   Usage in toplevel:
+     #require "jmap.top";;
+
+   Printers are automatically installed when the library is loaded.
+*)
+
+(* JSON printers *)
+
+let json_printer ppf (json : Jsont.json) =
+  match Jsont_bytesrw.encode_string Jsont.json json with
+  | Ok s -> Format.pp_print_string ppf s
+  | Error e -> Format.fprintf ppf "<json encoding error: %s>" e
+
+let jsont_error_printer ppf (e : Jsont.Error.t) =
+  Format.pp_print_string ppf (Jsont.Error.to_string e)
+
+(* JSON encoding helpers *)
+
+let encode (type a) (codec : a Jsont.t) (value : a) : Jsont.json =
+  match Jsont.Json.encode codec value with
+  | Ok json -> json
+  | Error e -> invalid_arg e
+
+let encode_string (type a) (codec : a Jsont.t) (value : a) : string =
+  match Jsont_bytesrw.encode_string codec value with
+  | Ok s -> s
+  | Error e -> invalid_arg e
+
+let pp_as_json (type a) (codec : a Jsont.t) ppf (value : a) =
+  json_printer ppf (encode codec value)
+
+(* Automatic printer installation *)
+
+let printers =
+  [ "Jmap.Id.pp";
+    "Jmap.Keyword.pp";
+    "Jmap.Role.pp";
+    "Jmap.Capability.pp";
+    "Jmap.Error.pp";
+    "Jmap_top.json_printer";
+    "Jmap_top.jsont_error_printer" ]
+
+(* Suppress stderr during printer installation to avoid noise in MDX tests *)
+let null_formatter = Format.make_formatter (fun _ _ _ -> ()) (fun () -> ())
+
+let eval_string_quiet str =
+  try
+    let lexbuf = Lexing.from_string str in
+    let phrase = !Toploop.parse_toplevel_phrase lexbuf in
+    Toploop.execute_phrase false null_formatter phrase
+  with _ -> false
+
+let rec do_install_printers = function
+  | [] -> true
+  | printer :: rest ->
+      let cmd = Printf.sprintf "#install_printer %s;;" printer in
+      eval_string_quiet cmd && do_install_printers rest
+
+let install () =
+  (* Silently ignore failures - this handles non-toplevel contexts like MDX *)
+  ignore (do_install_printers printers)
+
+(* Only auto-install when OCAML_TOPLEVEL_NAME is set, indicating a real toplevel *)
+let () =
+  if Sys.getenv_opt "OCAML_TOPLEVEL_NAME" <> None then
+    install ()

lib/top/jmap_top.mli

···
+(** Toplevel printers for JMAP types.
+
+    Printers are automatically installed when the library is loaded:
+    {[
+      #require "jmap.top";;
+    ]}
+
+    After loading, JMAP types will display nicely:
+    {[
+      # Jmap.Id.of_string_exn "abc123";;
+      - : Jmap.Id.t = <id:abc123>
+
+      # Jmap.Keyword.of_string "$seen";;
+      - : Jmap.Keyword.t = `Seen
+
+      # Jmap.Role.of_string "inbox";;
+      - : Jmap.Role.t = `Inbox
+    ]}
+
+    JSON values display as formatted strings, making it easy to see
+    how OCaml types map to JMAP JSON. *)
+
+(** {1 JSON Printers} *)
+
+val json_printer : Format.formatter -> Jsont.json -> unit
+(** Formats a JSON value as a compact JSON string. *)
+
+val jsont_error_printer : Format.formatter -> Jsont.Error.t -> unit
+(** Formats a Jsont parsing error. *)
+
+(** {1 JSON Encoding Helpers}
+
+    These functions encode OCaml types to JSON, useful for understanding
+    how the library maps to JMAP wire format. *)
+
+val encode : 'a Jsont.t -> 'a -> Jsont.json
+(** [encode codec value] encodes a value to JSON using the given codec.
+    Raises [Invalid_argument] on encoding failure. *)
+
+val encode_string : 'a Jsont.t -> 'a -> string
+(** [encode_string codec value] encodes a value to a JSON string. *)
+
+val pp_as_json : 'a Jsont.t -> Format.formatter -> 'a -> unit
+(** [pp_as_json codec ppf value] pretty-prints a value as JSON. *)
+
+(** {1 Installation} *)
+
+val install : unit -> unit
+(** [install ()] installs all printers. This is called automatically when
+    the library is loaded, but can be called again if needed. *)

test/proto/test_proto.ml

···
               Alcotest.failf "%s: re-decode failed: %s" name (Jsont.Error.to_string e)
           | Ok _ -> ()
 
+(* Helpers for extracting values from optional fields in tests *)
+let get_id opt = match opt with Some id -> Jmap.Proto.Id.to_string id | None -> Alcotest.fail "expected id"
+let get_string opt = match opt with Some s -> s | None -> Alcotest.fail "expected string"
+let get_int64 opt = match opt with Some n -> n | None -> Alcotest.fail "expected int64"
+let get_bool opt = match opt with Some b -> b | None -> Alcotest.fail "expected bool"
+
 (* ID tests *)
 module Id_tests = struct
   open Jmap.Proto
···
     match decode Mailbox.jsont json with
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok mb ->
-        Alcotest.(check string) "id" "mb1" (Jmap.Proto.Id.to_string (Mailbox.id mb));
-        Alcotest.(check string) "name" "Inbox" (Mailbox.name mb);
+        Alcotest.(check string) "id" "mb1" (get_id (Mailbox.id mb));
+        Alcotest.(check string) "name" "Inbox" (get_string (Mailbox.name mb));
         Alcotest.(check (option role_testable)) "role" (Some `Inbox) (Mailbox.role mb);
-        Alcotest.(check int64) "totalEmails" 150L (Mailbox.total_emails mb);
-        Alcotest.(check int64) "unreadEmails" 5L (Mailbox.unread_emails mb)
+        Alcotest.(check int64) "totalEmails" 150L (get_int64 (Mailbox.total_emails mb));
+        Alcotest.(check int64) "unreadEmails" 5L (get_int64 (Mailbox.unread_emails mb))
 
   let test_roundtrip () =
     test_roundtrip "simple roundtrip" Mailbox.jsont "mail/mailbox/valid/simple.json" ()
···
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok mb ->
         Alcotest.(check (option role_testable)) "role" (Some `Archive) (Mailbox.role mb);
-        Alcotest.(check int64) "totalEmails" 1000L (Mailbox.total_emails mb)
+        Alcotest.(check int64) "totalEmails" 1000L (get_int64 (Mailbox.total_emails mb))
 
   let tests = [
     "valid: simple", `Quick, test_simple;
···
     match decode Email.jsont json with
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok email ->
-        Alcotest.(check string) "id" "e1" (Jmap.Proto.Id.to_string (Email.id email));
-        Alcotest.(check string) "blobId" "blob1" (Jmap.Proto.Id.to_string (Email.blob_id email));
-        Alcotest.(check int64) "size" 1024L (Email.size email)
+        Alcotest.(check string) "id" "e1" (get_id (Email.id email));
+        Alcotest.(check string) "blobId" "blob1" (get_id (Email.blob_id email));
+        Alcotest.(check int64) "size" 1024L (get_int64 (Email.size email))
 
   let test_full_values () =
     let json = read_file "mail/email/valid/full.json" in
···
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok email ->
         Alcotest.(check (option string)) "subject" (Some "Re: Important meeting") (Email.subject email);
-        Alcotest.(check bool) "hasAttachment" true (Email.has_attachment email);
+        Alcotest.(check bool) "hasAttachment" true (get_bool (Email.has_attachment email));
         (* Check from address *)
         match Email.from email with
         | None -> Alcotest.fail "expected from address"
···
     match decode Email.jsont json with
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok email ->
-        let keywords = Email.keywords email in
+        let keywords = Option.value ~default:[] (Email.keywords email) in
         Alcotest.(check int) "keywords count" 3 (List.length keywords);
         Alcotest.(check bool) "$seen present" true (List.mem_assoc "$seen" keywords);
         Alcotest.(check bool) "$flagged present" true (List.mem_assoc "$flagged" keywords)
···
     match decode Email.jsont json with
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok email ->
-        let mailbox_ids = Email.mailbox_ids email in
+        let mailbox_ids = Option.value ~default:[] (Email.mailbox_ids email) in
         Alcotest.(check int) "mailboxIds count" 3 (List.length mailbox_ids)
 
   let tests = [
···
     match decode Thread.jsont json with
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok thread ->
-        Alcotest.(check string) "id" "t2" (Jmap.Proto.Id.to_string (Thread.id thread));
-        Alcotest.(check int) "emailIds count" 5 (List.length (Thread.email_ids thread))
+        Alcotest.(check string) "id" "t2" (get_id (Thread.id thread));
+        Alcotest.(check int) "emailIds count" 5 (List.length (Option.value ~default:[] (Thread.email_ids thread)))
 
   let tests = [
     "valid: simple", `Quick, test_simple;
···
     match decode Identity.jsont json with
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok ident ->
-        Alcotest.(check string) "name" "Work Identity" (Identity.name ident);
-        Alcotest.(check string) "email" "[e-mail]" (Identity.email ident);
-        Alcotest.(check bool) "mayDelete" true (Identity.may_delete ident)
+        Alcotest.(check string) "name" "Work Identity" (get_string (Identity.name ident));
+        Alcotest.(check string) "email" "[e-mail]" (get_string (Identity.email ident));
+        Alcotest.(check bool) "mayDelete" true (get_bool (Identity.may_delete ident))
 
   let tests = [
     "valid: simple", `Quick, test_simple;
···
     match decode Submission.jsont json with
     | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)
     | Ok sub ->
-        Alcotest.(check string) "id" "sub1" (Jmap.Proto.Id.to_string (Submission.id sub));
+        Alcotest.(check string) "id" "sub1" (get_id (Submission.id sub));
         (* Check undoStatus is Pending *)
         match Submission.undo_status sub with
-        | `Pending -> ()
+        | Some `Pending -> ()
         | _ -> Alcotest.fail "expected undoStatus to be pending"
 
   let tests = [

web/brr.html

···
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>JMAP Email Client</title>
+  <style>
+    :root {
+      --bg-color: #1a1a2e;
+      --card-bg: #16213e;
+      --accent: #0f3460;
+      --highlight: #e94560;
+      --text: #eee;
+      --text-muted: #888;
+      --success: #4ade80;
+      --error: #f87171;
+      --warning: #fbbf24;
+    }
+
+    * {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+      background: var(--bg-color);
+      color: var(--text);
+      min-height: 100vh;
+      padding: 20px;
+    }
+
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+    }
+
+    header {
+      text-align: center;
+      margin-bottom: 30px;
+    }
+
+    h1 {
+      font-size: 2rem;
+      margin-bottom: 10px;
+    }
+
+    h1 span {
+      color: var(--highlight);
+    }
+
+    .subtitle {
+      color: var(--text-muted);
+      font-size: 0.9rem;
+    }
+
+    /* Top Section - Two Column Layout */
+    .top-section {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 20px;
+      margin-bottom: 20px;
+    }
+
+    @media (max-width: 800px) {
+      .top-section {
+        grid-template-columns: 1fr;
+      }
+    }
+
+    /* Login Form */
+    .login-card {
+      background: var(--card-bg);
+      border-radius: 12px;
+      padding: 16px;
+      box-shadow: 0 4px 20px rgba(0,0,0,0.3);
+    }
+
+    .login-card h3 {
+      margin-bottom: 12px;
+      font-size: 0.9rem;
+      color: var(--text-muted);
+      text-transform: uppercase;
+      letter-spacing: 1px;
+    }
+
+    .form-row {
+      display: flex;
+      gap: 12px;
+      margin-bottom: 12px;
+    }
+
+    .form-group {
+      flex: 1;
+      margin-bottom: 12px;
+    }
+
+    .form-group:last-child {
+      margin-bottom: 0;
+    }
+
+    .form-group.small {
+      flex: 0.4;
+    }
+
+    label {
+      display: block;
+      margin-bottom: 4px;
+      font-weight: 500;
+      font-size: 0.75rem;
+      color: var(--text-muted);
+    }
+
+    input[type="text"],
+    input[type="password"] {
+      width: 100%;
+      padding: 8px 12px;
+      border: 2px solid var(--accent);
+      border-radius: 6px;
+      background: var(--bg-color);
+      color: var(--text);
+      font-size: 0.85rem;
+      transition: border-color 0.2s;
+    }
+
+    input:focus {
+      outline: none;
+      border-color: var(--highlight);
+    }
+
+    .btn-row {
+      display: flex;
+      gap: 8px;
+    }
+
+    .btn {
+      flex: 1;
+      padding: 10px;
+      border: none;
+      border-radius: 6px;
+      font-size: 0.85rem;
+      font-weight: 600;
+      cursor: pointer;
+      transition: transform 0.1s, opacity 0.2s;
+    }
+
+    .btn:hover {
+      transform: translateY(-1px);
+    }
+
+    .btn:active {
+      transform: translateY(0);
+    }
+
+    .btn:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+      transform: none;
+    }
+
+    .btn-primary {
+      background: var(--highlight);
+      color: white;
+    }
+
+    .btn-secondary {
+      background: var(--accent);
+      color: var(--text);
+    }
+
+    /* Status/Log Panel */
+    .log-panel {
+      background: var(--card-bg);
+      border-radius: 12px;
+      padding: 20px;
+      margin-bottom: 30px;
+      max-height: 500px;
+      overflow-y: auto;
+    }
+
+    .log-panel h3 {
+      margin-bottom: 15px;
+      font-size: 0.9rem;
+      color: var(--text-muted);
+      text-transform: uppercase;
+      letter-spacing: 1px;
+    }
+
+    .log-entry {
+      font-family: 'SF Mono', Monaco, 'Courier New', monospace;
+      font-size: 0.85rem;
+      padding: 8px 0;
+      border-bottom: 1px solid var(--accent);
+    }
+
+    .log-entry:last-child {
+      border-bottom: none;
+    }
+
+    .log-entry-header {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .log-info .log-entry-header { color: var(--text); }
+    .log-success .log-entry-header { color: var(--success); }
+    .log-error .log-entry-header { color: var(--error); }
+    .log-warning .log-entry-header { color: var(--warning); }
+
+    .log-time {
+      color: var(--text-muted);
+      font-size: 0.8rem;
+      flex-shrink: 0;
+    }
+
+    .log-message {
+      flex: 1;
+    }
+
+    .log-expand-btn {
+      background: var(--accent);
+      border: none;
+      color: var(--text-muted);
+      padding: 2px 8px;
+      border-radius: 4px;
+      font-size: 0.7rem;
+      cursor: pointer;
+      font-family: inherit;
+      transition: background 0.2s, color 0.2s;
+      flex-shrink: 0;
+    }
+
+    .log-expand-btn:hover {
+      background: var(--highlight);
+      color: white;
+    }
+
+    .log-expand-btn.expanded {
+      background: var(--highlight);
+      color: white;
+    }
+
+    /* JSON content within log entry */
+    .log-json {
+      display: none;
+      margin-top: 8px;
+      border-radius: 8px;
+      overflow: hidden;
+    }
+
+    .log-json.visible {
+      display: block;
+    }
+
+    .log-json-header {
+      padding: 6px 12px;
+      font-size: 0.75rem;
+      font-weight: 600;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+
+    .log-json.request .log-json-header {
+      background: var(--accent);
+      color: var(--highlight);
+    }
+
+    .log-json.response .log-json-header {
+      background: #1a3a2e;
+      color: var(--success);
+    }
+
+    .log-json-body {
+      background: var(--bg-color);
+      padding: 12px;
+      font-size: 0.75rem;
+      line-height: 1.4;
+      white-space: pre-wrap;
+      word-break: break-all;
+      max-height: 300px;
+      overflow-y: auto;
+      color: var(--text-muted);
+    }
+
+    .log-json-body.collapsed {
+      max-height: 100px;
+    }
+
+    .json-toggle-size {
+      background: none;
+      border: none;
+      color: inherit;
+      cursor: pointer;
+      font-size: 0.7rem;
+      opacity: 0.7;
+    }
+
+    .json-toggle-size:hover {
+      opacity: 1;
+    }
+
+    /* Session Info */
+    .session-info {
+      background: var(--card-bg);
+      border-radius: 12px;
+      padding: 16px;
+      display: none;
+      box-shadow: 0 4px 20px rgba(0,0,0,0.3);
+    }
+
+    .session-info.visible {
+      display: block;
+    }
+
+    .session-info h3 {
+      margin-bottom: 12px;
+      font-size: 0.9rem;
+      color: var(--success);
+      text-transform: uppercase;
+      letter-spacing: 1px;
+    }
+
+    .session-detail {
+      display: flex;
+      margin-bottom: 6px;
+      font-size: 0.85rem;
+    }
+
+    .session-detail .label {
+      width: 100px;
+      color: var(--text-muted);
+      flex-shrink: 0;
+    }
+
+    .session-detail .value {
+      color: var(--text);
+      word-break: break-all;
+      font-family: 'SF Mono', Monaco, 'Courier New', monospace;
+      font-size: 0.8rem;
+    }
+
+    .search-box {
+      margin-top: 12px;
+      padding-top: 12px;
+      border-top: 1px solid var(--accent);
+      display: flex;
+      gap: 8px;
+    }
+
+    .search-box input {
+      flex: 1;
+      padding: 8px 12px;
+      border: 2px solid var(--accent);
+      border-radius: 6px;
+      background: var(--bg-color);
+      color: var(--text);
+      font-size: 0.85rem;
+    }
+
+    .search-box input:focus {
+      outline: none;
+      border-color: var(--highlight);
+    }
+
+    .btn-small {
+      flex: 0;
+      padding: 8px 16px;
+      white-space: nowrap;
+    }
+
+    /* Email List */
+    .email-list {
+      display: none;
+    }
+
+    .email-list.visible {
+      display: block;
+    }
+
+    .email-list h2 {
+      margin-bottom: 20px;
+    }
+
+    .email-item {
+      background: var(--card-bg);
+      border-radius: 8px;
+      padding: 16px 20px;
+      margin-bottom: 12px;
+      cursor: pointer;
+      transition: background 0.2s, transform 0.1s;
+      border-left: 4px solid transparent;
+    }
+
+    .email-item:hover {
+      background: var(--accent);
+      transform: translateX(4px);
+    }
+
+    .email-item.unread {
+      border-left-color: var(--highlight);
+    }
+
+    .email-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      margin-bottom: 8px;
+    }
+
+    .email-from {
+      font-weight: 600;
+      font-size: 1rem;
+    }
+
+    .email-date {
+      color: var(--text-muted);
+      font-size: 0.85rem;
+    }
+
+    .email-subject {
+      font-size: 0.95rem;
+      color: var(--text);
+      margin-bottom: 6px;
+    }
+
+    .email-preview {
+      color: var(--text-muted);
+      font-size: 0.85rem;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .email-keywords {
+      margin-top: 8px;
+    }
+
+    .keyword-tag {
+      display: inline-block;
+      background: var(--accent);
+      color: var(--text-muted);
+      padding: 2px 8px;
+      border-radius: 4px;
+      font-size: 0.75rem;
+      margin-right: 6px;
+    }
+
+    .keyword-tag.flagged {
+      background: var(--warning);
+      color: var(--bg-color);
+    }
+
+    /* Loading spinner */
+    .spinner {
+      display: inline-block;
+      width: 20px;
+      height: 20px;
+      border: 2px solid var(--text-muted);
+      border-top-color: var(--highlight);
+      border-radius: 50%;
+      animation: spin 0.8s linear infinite;
+      margin-right: 10px;
+      vertical-align: middle;
+    }
+
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    /* Responsive */
+    @media (max-width: 600px) {
+      body {
+        padding: 10px;
+      }
+
+      .login-card {
+        padding: 20px;
+      }
+
+      h1 {
+        font-size: 1.5rem;
+      }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>JMAP <span>Email Client</span></h1>
+      <p class="subtitle">Built with OCaml and Brr</p>
+    </header>
+
+    <!-- Top Section: Login + Session Info -->
+    <div class="top-section">
+      <!-- Login Form -->
+      <div class="login-card" id="login-card">
+        <h3>Connection</h3>
+        <div class="form-group">
+          <label for="session-url">Session URL</label>
+          <input type="text" id="session-url"
+                 value="https://api.fastmail.com/jmap/session"
+                 placeholder="https://api.fastmail.com/jmap/session">
+        </div>
+        <div class="form-row">
+          <div class="form-group">
+            <label for="api-token">API Token</label>
+            <input type="password" id="api-token"
+                   placeholder="Enter your JMAP API token">
+          </div>
+        </div>
+        <div class="btn-row">
+          <button class="btn btn-primary" id="connect-btn">Connect</button>
+          <button class="btn btn-secondary" id="disconnect-btn" style="display: none;">Disconnect</button>
+        </div>
+      </div>
+
+      <!-- Session Info -->
+      <div class="session-info" id="session-info">
+        <h3>Connected</h3>
+        <div class="session-detail">
+          <span class="label">Username:</span>
+          <span class="value" id="session-username">-</span>
+        </div>
+        <div class="session-detail">
+          <span class="label">API URL:</span>
+          <span class="value" id="session-api-url">-</span>
+        </div>
+        <div class="session-detail">
+          <span class="label">Account ID:</span>
+          <span class="value" id="session-account-id">-</span>
+        </div>
+        <div class="search-box">
+          <input type="text" id="email-search" placeholder="Search emails...">
+          <button class="btn btn-primary btn-small" id="search-btn">Search</button>
+        </div>
+      </div>
+    </div>
+
+    <!-- Log Panel with expandable JSON -->
+    <div class="log-panel" id="log-panel">
+      <h3>Activity Log</h3>
+      <div id="log-entries"></div>
+    </div>
+
+    <!-- Email List -->
+    <div class="email-list" id="email-list">
+      <h2>Recent Emails</h2>
+      <div id="emails"></div>
+    </div>
+  </div>
+
+  <script type="text/javascript" defer src="brr.js"></script>
+  <noscript>
+    <p style="text-align: center; padding: 50px; color: #888;">
+      Please enable JavaScript to use this application.
+    </p>
+  </noscript>
+</body>
+</html>

web/brr_app.ml

···
+(*---------------------------------------------------------------------------
+   JMAP Email Client - Browser Application
+   Built with OCaml, Brr, and jmap-brr
+  ---------------------------------------------------------------------------*)
+
+open Brr
+open Fut.Syntax
+
+(* ---- Shared timestamp utilities ---- *)
+
+let get_time_str () =
+  let date = Jv.new' (Jv.get Jv.global "Date") [||] in
+  let h = Jv.to_int (Jv.call date "getHours" [||]) in
+  let m = Jv.to_int (Jv.call date "getMinutes" [||]) in
+  let s = Jv.to_int (Jv.call date "getSeconds" [||]) in
+  Printf.sprintf "%02d:%02d:%02d" h m s
+
+(* ---- JSON Masking ---- *)
+
+module JsonMask = struct
+  let sensitive_keys = [
+    "accountId"; "blobId"; "threadId"; "emailId"; "id";
+    "username"; "apiUrl"; "downloadUrl"; "uploadUrl"; "eventSourceUrl";
+    "state"; "oldState"; "newState"
+  ]
+
+  let is_sensitive key =
+    List.exists (fun k -> String.lowercase_ascii k = String.lowercase_ascii key) sensitive_keys
+
+  let mask_value s =
+    let len = String.length s in
+    if len <= 4 then String.make len '*'
+    else
+      let visible = min 4 (len / 4) in
+      (String.sub s 0 visible) ^ String.make (len - visible) '*'
+
+  let rec mask_json (json : Jv.t) : Jv.t =
+    if Jv.is_null json || Jv.is_undefined json then json
+    else if Jv.is_array json then
+      let arr = Jv.to_list Fun.id json in
+      let masked = List.map mask_json arr in
+      Jv.of_list Fun.id masked
+    else if Jstr.equal (Jv.typeof json) (Jstr.v "object") && not (Jv.is_array json) then
+      let obj = Jv.obj [||] in
+      let keys = Jv.call (Jv.get Jv.global "Object") "keys" [|json|] in
+      let key_list = Jv.to_list Jv.to_string keys in
+      List.iter (fun key ->
+        let value = Jv.get json key in
+        let masked_value =
+          if is_sensitive key && Jstr.equal (Jv.typeof value) (Jstr.v "string") then
+            Jv.of_string (mask_value (Jv.to_string value))
+          else
+            mask_json value
+        in
+        Jv.set obj key masked_value
+      ) key_list;
+      obj
+    else
+      json
+
+  let format_json json =
+    let json_obj = Jv.get Jv.global "JSON" in
+    Jv.to_string (Jv.call json_obj "stringify" [|json; Jv.null; Jv.of_int 2|])
+
+  let mask_and_format json_str =
+    try
+      let json_obj = Jv.get Jv.global "JSON" in
+      let parsed = Jv.call json_obj "parse" [|Jv.of_string json_str|] in
+      let masked = mask_json parsed in
+      format_json masked
+    with _ -> json_str
+end
+
+(* ---- Logging with expandable JSON ---- *)
+
+module Log = struct
+  type level = Info | Success | Error | Warning
+
+  let log_entries_el () =
+    Document.find_el_by_id G.document (Jstr.v "log-entries")
+
+  (* Reference to the last created entry for attaching JSON *)
+  let last_entry : El.t option ref = ref None
+
+  let add level msg =
+    match log_entries_el () with
+    | None -> Console.(log [str msg])
+    | Some container ->
+        let time_str = get_time_str () in
+        let class_name = match level with
+          | Info -> "log-info"
+          | Success -> "log-success"
+          | Error -> "log-error"
+          | Warning -> "log-warning"
+        in
+        let header = El.div ~at:At.[class' (Jstr.v "log-entry-header")] [
+          El.span ~at:At.[class' (Jstr.v "log-time")] [El.txt' time_str];
+          El.span ~at:At.[class' (Jstr.v "log-message")] [El.txt' msg];
+        ] in
+        let entry = El.div ~at:At.[class' (Jstr.v ("log-entry " ^ class_name))] [header] in
+        last_entry := Some entry;
+        El.append_children container [entry];
+        (* Scroll to bottom *)
+        let scroll_height = Jv.get (El.to_jv container) "scrollHeight" in
+        Jv.set (El.to_jv container) "scrollTop" scroll_height
+
+  let attach_json direction label json_str =
+    match !last_entry with
+    | None -> ()
+    | Some entry ->
+        let formatted = JsonMask.mask_and_format json_str in
+        let class_name = match direction with
+          | `Request -> "log-json request"
+          | `Response -> "log-json response"
+        in
+        let arrow = match direction with
+          | `Request -> ">>> "
+          | `Response -> "<<< "
+        in
+        (* Create the JSON container (hidden by default) *)
+        let json_body = El.pre ~at:At.[class' (Jstr.v "log-json-body collapsed")] [El.txt' formatted] in
+        let expand_size_btn = El.button ~at:At.[class' (Jstr.v "json-toggle-size")] [El.txt' "[expand]"] in
+        let json_div = El.div ~at:At.[class' (Jstr.v class_name)] [
+          El.div ~at:At.[class' (Jstr.v "log-json-header")] [
+            El.span [El.txt' (arrow ^ label)];
+            expand_size_btn;
+          ];
+          json_body;
+        ] in
+        (* Add expand button to header if not already there *)
+        let header = El.children entry |> List.hd in
+        let existing_btns = El.children header |> List.filter (fun el ->
+          match El.at (Jstr.v "class") el with
+          | Some cls -> Option.is_some (Jstr.find_sub ~sub:(Jstr.v "log-expand-btn") cls)
+          | None -> false
+        ) in
+        if List.length existing_btns = 0 then begin
+          let expand_btn = El.button ~at:At.[class' (Jstr.v "log-expand-btn")] [El.txt' "JSON"] in
+          El.append_children header [expand_btn];
+          (* Toggle visibility on click *)
+          ignore @@ Ev.listen Ev.click (fun _ev ->
+            let json_els = El.children entry |> List.filter (fun el ->
+              match El.at (Jstr.v "class") el with
+              | Some cls -> Option.is_some (Jstr.find_sub ~sub:(Jstr.v "log-json") cls)
+              | None -> false
+            ) in
+            let is_visible = List.exists (fun el ->
+              El.class' (Jstr.v "visible") el
+            ) json_els in
+            List.iter (fun el ->
+              El.set_class (Jstr.v "visible") (not is_visible) el
+            ) json_els;
+            El.set_class (Jstr.v "expanded") (not is_visible) expand_btn
+          ) (El.as_target expand_btn)
+        end;
+        (* Toggle body size *)
+        ignore @@ Ev.listen Ev.click (fun _ev ->
+          let is_collapsed = El.class' (Jstr.v "collapsed") json_body in
+          El.set_class (Jstr.v "collapsed") (not is_collapsed) json_body;
+          El.set_children expand_size_btn [El.txt' (if is_collapsed then "[collapse]" else "[expand]")]
+        ) (El.as_target expand_size_btn);
+        El.append_children entry [json_div];
+        (* Scroll to bottom *)
+        match log_entries_el () with
+        | Some container ->
+            let scroll_height = Jv.get (El.to_jv container) "scrollHeight" in
+            Jv.set (El.to_jv container) "scrollTop" scroll_height
+        | None -> ()
+
+  let info msg = add Info msg
+  let success msg = add Success msg
+  let error msg = add Error msg
+  let warning msg = add Warning msg
+end
+
+(* ---- JSON Protocol Logging (bridges to Log.attach_json) ---- *)
+
+module JsonLog = struct
+  let request label json = Log.attach_json `Request label json
+  let response label json = Log.attach_json `Response label json
+  let clear () = ()  (* No longer needed *)
+end
+
+(* ---- DOM Helpers ---- *)
+
+let get_el id =
+  match Document.find_el_by_id G.document (Jstr.v id) with
+  | Some el -> el
+  | None -> failwith (Printf.sprintf "Element not found: %s" id)
+
+let get_input_value id =
+  let el = get_el id in
+  Jstr.to_string (El.prop El.Prop.value el)
+
+let set_text id text =
+  let el = get_el id in
+  El.set_children el [El.txt' text]
+
+let show_el id =
+  let el = get_el id in
+  El.set_class (Jstr.v "visible") true el
+
+let hide_el id =
+  let el = get_el id in
+  El.set_class (Jstr.v "visible") false el
+
+let set_button_loading id loading =
+  let el = get_el id in
+  El.set_at At.Name.disabled (if loading then Some (Jstr.v "") else None) el;
+  if loading then
+    El.set_children el [
+      El.span ~at:At.[class' (Jstr.v "spinner")] [];
+      El.txt' "Connecting..."
+    ]
+  else
+    El.set_children el [El.txt' "Connect"]
+
+(* ---- Email Display ---- *)
+
+let format_date ptime =
+  let date, time = Ptime.to_date_time ptime in
+  let y, m, d = date in
+  let (h, min, _), _ = time in
+  Printf.sprintf "%04d-%02d-%02d %02d:%02d" y m d h min
+
+let format_address (addr : Jmap.Proto.Email_address.t) =
+  match addr.name with
+  | Some name -> Printf.sprintf "%s <%s>" name addr.email
+  | None -> addr.email
+
+let format_addresses = function
+  | None -> "Unknown"
+  | Some [] -> "Unknown"
+  | Some (addr :: _) -> format_address addr
+
+let render_email (email : Jmap.Proto.Email.t) =
+  let keywords = Option.value ~default:[] email.keywords in
+  let is_unread = not (List.exists (fun (k, v) -> k = "$seen" && v) keywords) in
+  let is_flagged = List.exists (fun (k, v) -> k = "$flagged" && v) keywords in
+
+  let from_str = format_addresses email.from in
+  let subject = Option.value ~default:"(No Subject)" email.subject in
+  let date_str = match email.received_at with Some t -> format_date t | None -> "?" in
+  let preview = Option.value ~default:"" email.preview in
+
+  let keyword_tags =
+    if is_flagged then
+      [El.span ~at:At.[class' (Jstr.v "keyword-tag flagged")] [El.txt' "Flagged"]]
+    else
+      []
+  in
+
+  let classes = "email-item" ^ (if is_unread then " unread" else "") in
+
+  El.div ~at:At.[class' (Jstr.v classes)] [
+    El.div ~at:At.[class' (Jstr.v "email-header")] [
+      El.span ~at:At.[class' (Jstr.v "email-from")] [El.txt' from_str];
+      El.span ~at:At.[class' (Jstr.v "email-date")] [El.txt' date_str];
+    ];
+    El.div ~at:At.[class' (Jstr.v "email-subject")] [El.txt' subject];
+    El.div ~at:At.[class' (Jstr.v "email-preview")] [El.txt' preview];
+    El.div ~at:At.[class' (Jstr.v "email-keywords")] keyword_tags;
+  ]
+
+let display_emails emails =
+  let container = get_el "emails" in
+  let email_els = List.map render_email emails in
+  El.set_children container email_els;
+  show_el "email-list"
+
+(* ---- State ---- *)
+
+type state = {
+  mutable connection : Jmap_brr.connection option;
+  mutable account_id : Jmap.Proto.Id.t option;
+}
+
+let state = { connection = None; account_id = None }
+
+(* ---- JMAP Operations ---- *)
+
+let fetch_emails ?(search_text="") conn account_id =
+  let search_msg = if search_text = "" then "Fetching recent emails..."
+    else Printf.sprintf "Searching emails for '%s'..." search_text in
+  Log.info search_msg;
+
+  let capabilities = [
+    Jmap.Capability.core_uri;
+    Jmap.Capability.mail_uri
+  ] in
+
+  (* First, get mailboxes to find the inbox *)
+  let request, mailbox_handle =
+    let open Jmap.Chain in
+    build ~capabilities (mailbox_get ~account_id ())
+  in
+
+  let* response = Jmap_brr.request conn request in
+  match response with
+  | Error e ->
+      Log.error (Printf.sprintf "Failed to get mailboxes: %s"
+        (Jstr.to_string (Jv.Error.message e)));
+      Fut.return ()
+  | Ok resp ->
+      match Jmap.Chain.parse mailbox_handle resp with
+      | Error e ->
+          Log.error (Printf.sprintf "Failed to parse mailboxes: %s"
+            (Jsont.Error.to_string e));
+          Fut.return ()
+      | Ok mailbox_resp ->
+          let mailboxes = mailbox_resp.list in
+          Log.info (Printf.sprintf "Found %d mailboxes" (List.length mailboxes));
+
+          (* Find inbox or use first mailbox *)
+          let inbox_id =
+            match List.find_opt (fun m ->
+              match m.Jmap.Proto.Mailbox.role with
+              | Some `Inbox -> true
+              | _ -> false
+            ) mailboxes with
+            | Some m -> m.Jmap.Proto.Mailbox.id
+            | None ->
+                match mailboxes with
+                | m :: _ -> m.Jmap.Proto.Mailbox.id
+                | [] ->
+                    Log.error "No mailboxes found";
+                    failwith "No mailboxes"
+          in
+          let inbox_id = match inbox_id with
+            | Some id -> id
+            | None ->
+                Log.error "Inbox has no ID";
+                failwith "Inbox has no ID"
+          in
+
+          let query_msg = if search_text = "" then "Querying emails from inbox..."
+            else Printf.sprintf "Querying inbox for '%s'..." search_text in
+          Log.info query_msg;
+
+          (* Query for recent emails with optional text search *)
+          let text_filter = if search_text = "" then None else Some search_text in
+          let filter_condition : Jmap.Proto.Email.Filter_condition.t = {
+            in_mailbox = Some inbox_id;
+            in_mailbox_other_than = None;
+            before = None;
+            after = None;
+            min_size = None;
+            max_size = None;
+            all_in_thread_have_keyword = None;
+            some_in_thread_have_keyword = None;
+            none_in_thread_have_keyword = None;
+            has_keyword = None;
+            not_keyword = None;
+            has_attachment = None;
+            text = text_filter;
+            from = None;
+            to_ = None;
+            cc = None;
+            bcc = None;
+            subject = None;
+            body = None;
+            header = None;
+          } in
+
+          let request2, email_handle =
+            let open Jmap.Chain in
+            build ~capabilities begin
+              let* query = email_query ~account_id
+                ~filter:(Jmap.Proto.Filter.Condition filter_condition)
+                ~sort:[Jmap.Proto.Filter.comparator ~is_ascending:false "receivedAt"]
+                ~limit:20L
+                ()
+              in
+              email_get ~account_id
+                ~ids:(from_query query)
+                ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "keywords";
+                            "size"; "receivedAt"; "from"; "subject"; "preview";
+                            "hasAttachment"]
+                ()
+            end
+          in
+
+          Log.info "Sending email query request...";
+          let* response2 = Jmap_brr.request conn request2 in
+          Log.info "Got email query response";
+          match response2 with
+          | Error e ->
+              Log.error (Printf.sprintf "Failed to query emails: %s"
+                (Jstr.to_string (Jv.Error.message e)));
+              Fut.return ()
+          | Ok resp2 ->
+              Log.info "Parsing email response...";
+              match Jmap.Chain.parse email_handle resp2 with
+              | Error e ->
+                  Log.error (Printf.sprintf "Failed to parse emails: %s"
+                    (Jsont.Error.to_string e));
+                  Fut.return ()
+              | Ok email_resp ->
+                  let emails = email_resp.list in
+                  Log.success (Printf.sprintf "Loaded %d emails" (List.length emails));
+                  (try
+                    display_emails emails
+                  with exn ->
+                    Log.error (Printf.sprintf "Display error: %s" (Printexc.to_string exn)));
+                  Fut.return ()
+
+(* ---- Connection ---- *)
+
+let connect () =
+  let session_url = get_input_value "session-url" in
+  let api_token = get_input_value "api-token" in
+
+  if String.length api_token = 0 then begin
+    Log.error "Please enter an API token";
+    Fut.return ()
+  end else begin
+    Log.info (Printf.sprintf "Connecting to %s..." session_url);
+    set_button_loading "connect-btn" true;
+
+    let* result = Jmap_brr.get_session
+      ~url:(Jstr.v session_url)
+      ~token:(Jstr.v api_token)
+    in
+
+    set_button_loading "connect-btn" false;
+
+    match result with
+    | Error e ->
+        let msg = Jstr.to_string (Jv.Error.message e) in
+        Log.error (Printf.sprintf "Connection failed: %s" msg);
+        Fut.return ()
+    | Ok conn ->
+        let session = Jmap_brr.session conn in
+        let username = Jmap.Proto.Session.username session in
+        let api_url = Jmap.Proto.Session.api_url session in
+
+        Log.success (Printf.sprintf "Connected as %s" username);
+
+        (* Find primary mail account *)
+        let account_id =
+          match Jmap.Proto.Session.primary_account_for
+                  Jmap.Capability.mail_uri session with
+          | Some id -> id
+          | None ->
+              match Jmap.Proto.Session.accounts session with
+              | (id, _) :: _ -> id
+              | [] -> failwith "No accounts found"
+        in
+
+        state.connection <- Some conn;
+        state.account_id <- Some account_id;
+
+        (* Update UI *)
+        set_text "session-username" username;
+        set_text "session-api-url" api_url;
+        set_text "session-account-id" (Jmap.Proto.Id.to_string account_id);
+        show_el "session-info";
+
+        (* Show disconnect button *)
+        let connect_btn = get_el "connect-btn" in
+        let disconnect_btn = get_el "disconnect-btn" in
+        El.set_inline_style (Jstr.v "display") (Jstr.v "none") connect_btn;
+        El.set_inline_style (Jstr.v "display") (Jstr.v "block") disconnect_btn;
+
+        (* Fetch emails *)
+        fetch_emails conn account_id
+  end
+
+let disconnect () =
+  state.connection <- None;
+  state.account_id <- None;
+
+  hide_el "session-info";
+  hide_el "email-list";
+
+  (* Reset buttons *)
+  let connect_btn = get_el "connect-btn" in
+  let disconnect_btn = get_el "disconnect-btn" in
+  El.set_inline_style (Jstr.v "display") (Jstr.v "block") connect_btn;
+  El.set_inline_style (Jstr.v "display") (Jstr.v "none") disconnect_btn;
+
+  Log.info "Disconnected"
+
+let search_emails () =
+  match state.connection, state.account_id with
+  | Some conn, Some account_id ->
+      let search_text = get_input_value "email-search" in
+      ignore (fetch_emails ~search_text conn account_id)
+  | _ ->
+      Log.warning "Not connected"
+
+(* ---- Main ---- *)
+
+let setup_handlers () =
+  let connect_btn = get_el "connect-btn" in
+  let disconnect_btn = get_el "disconnect-btn" in
+
+  (* Connect button click *)
+  ignore @@ Ev.listen Ev.click (fun _ev ->
+    ignore (connect ())
+  ) (El.as_target connect_btn);
+
+  (* Disconnect button click *)
+  ignore @@ Ev.listen Ev.click (fun _ev ->
+    disconnect ()
+  ) (El.as_target disconnect_btn);
+
+  (* Enter key in token field *)
+  let token_input = get_el "api-token" in
+  ignore @@ Ev.listen Ev.keydown (fun ev ->
+    let kev = Ev.as_type ev in
+    if Jstr.equal (Ev.Keyboard.key kev) (Jstr.v "Enter") then
+      ignore (connect ())
+  ) (El.as_target token_input);
+
+  (* Search button click *)
+  let search_btn = get_el "search-btn" in
+  ignore @@ Ev.listen Ev.click (fun _ev ->
+    search_emails ()
+  ) (El.as_target search_btn);
+
+  (* Enter key in search field *)
+  let search_input = get_el "email-search" in
+  ignore @@ Ev.listen Ev.keydown (fun ev ->
+    let kev = Ev.as_type ev in
+    if Jstr.equal (Ev.Keyboard.key kev) (Jstr.v "Enter") then
+      search_emails ()
+  ) (El.as_target search_input)
+
+let main () =
+  (* Register JSON loggers *)
+  Jmap_brr.set_request_logger JsonLog.request;
+  Jmap_brr.set_response_logger JsonLog.response;
+
+  Log.info "JMAP Email Client initialized";
+  Log.info "Enter your JMAP server URL and API token to connect";
+  setup_handlers ()
+
+let () = main ()

web/dune

···
+(executable
+ (name brr_app)
+ (libraries jmap_brr brr)
+ (modes js)
+ (flags (:standard -w -32-69))
+ (js_of_ocaml))
+
+(rule
+ (targets brr.js)
+ (deps brr_app.bc.js)
+ (action (copy %{deps} %{targets})))
+
+(alias
+ (name web)
+ (deps brr.js brr.html))