My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** Email object property identifiers for selective retrieval.
2
3 This module defines property identifiers for Email objects as specified
4 in RFC 8621 Section 4.1. These identifiers are used in Email/get requests
5 to specify which properties should be returned, allowing efficient partial
6 object retrieval and reducing bandwidth usage.
7
8 Properties cover all standard email metadata, headers, body structure,
9 and content access points defined in the JMAP specification.
10
11 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1> RFC 8621, Section 4.1
12*)
13
14(** Email object property identifier type.
15
16 Polymorphic variant enumeration of all standard and extended properties
17 available on Email objects. Each property corresponds to a specific field
18 or computed value that can be requested when fetching Email objects from the server.
19
20 Polymorphic variants provide flexibility for extension and composition while
21 maintaining type safety and JMAP protocol compliance.
22*)
23type t = [
24 | `Id (** Server-assigned unique identifier for the email *)
25 | `BlobId (** Blob ID for downloading the complete raw RFC 5322 message *)
26 | `ThreadId (** Thread identifier linking related messages *)
27 | `MailboxIds (** Set of mailbox IDs where this email is located *)
28 | `Keywords (** Set of keywords/flags applied to this email *)
29 | `Size (** Total size of the raw message in octets *)
30 | `ReceivedAt (** Server timestamp when message was received *)
31 | `MessageId (** Message-ID header field values (list of strings) *)
32 | `InReplyTo (** In-Reply-To header field values for threading *)
33 | `References (** References header field values for threading *)
34 | `Sender (** Sender header field (single address) *)
35 | `From (** From header field (list of addresses) *)
36 | `To (** To header field (list of addresses) *)
37 | `Cc (** Cc header field (list of addresses) *)
38 | `Bcc (** Bcc header field (list of addresses) *)
39 | `ReplyTo (** Reply-To header field (list of addresses) *)
40 | `Subject (** Subject header field text *)
41 | `SentAt (** Date header field (when message was sent) *)
42 | `HasAttachment (** Boolean indicating presence of non-inline attachments *)
43 | `Preview (** Server-generated preview text for display *)
44 | `BodyStructure (** Complete MIME structure tree of the message *)
45 | `BodyValues (** Decoded content of requested text body parts *)
46 | `TextBody (** List of text/plain body parts for display *)
47 | `HtmlBody (** List of text/html body parts for display *)
48 | `Attachments (** List of attachment body parts *)
49 | `Header of string (** Raw value of specific header field by name *)
50 | `Other of string (** Server-specific extension property *)
51]
52
53(** Convert a property to its JMAP protocol string representation.
54
55 Transforms the property variant into the string format used in JMAP
56 protocol messages. Header properties are formatted as "header:name"
57 and other properties use their canonical JMAP names.
58
59 @param t The property to convert
60 @return JMAP protocol string representation *)
61val to_string : t -> string
62
63(** Parse a JMAP protocol string into a property variant.
64
65 Parses strings from JMAP protocol messages back into the corresponding
66 property variant. Handles special cases like "header:name" syntax for
67 custom headers.
68
69 @param str The protocol string to parse
70 @return Corresponding property variant *)
71val of_string : string -> t
72
73(** Get properties commonly needed for email list display.
74
75 Returns a curated list of Email properties that are typically needed
76 for showing emails in a list view: ID, thread, mailboxes, keywords,
77 sender, recipients, subject, timestamps, attachments, and preview.
78
79 This provides a convenient starting point for most email client list views
80 without over-fetching unnecessary data.
81
82 @return List of properties suitable for email list views
83*)
84val common_list_properties : t list
85
86(** Get properties for detailed email view.
87
88 Returns a comprehensive list of Email properties suitable for displaying
89 full email details, including all headers, body structure, and metadata.
90 This covers most properties except body values which need to be requested
91 specifically based on the body structure.
92
93 @return List of properties suitable for detailed email display
94*)
95val detailed_view_properties : t list
96
97(** Get minimal properties for email existence checks.
98
99 Returns the absolute minimum set of properties needed to verify email
100 existence and basic metadata. Useful for efficient bulk operations
101 where full email data is not needed.
102
103 @return Minimal list of properties for existence verification
104*)
105val minimal_properties : t list
106
107(** Convert a list of properties to their string representations.
108
109 Convenience function to convert a list of property variants to their
110 JMAP protocol string representations for use in API requests.
111
112 @param properties List of property variants
113 @return List of JMAP protocol strings *)
114val to_string_list : t list -> string list
115
116(** Parse a list of strings into property variants.
117
118 Convenience function to parse a list of JMAP protocol strings back
119 into property variants. Invalid strings are ignored.
120
121 @param strings List of JMAP protocol strings
122 @return List of parsed property variants *)
123val of_string_list : string list -> t list
124
125(** {2 Property Set Builders} *)
126
127(** Build a property list with custom headers.
128
129 Creates a property list from a base set with additional custom headers.
130 Useful for requesting specific headers like "List-ID" or "X-Custom-Header".
131
132 @param base Base property list to extend (default: common_list_properties)
133 @param headers List of header names to include (without "header:" prefix)
134 @return Extended property list with header properties *)
135val with_headers : ?base:t list -> headers:string list -> unit -> t list
136
137(** Build a minimal property list for efficient queries.
138
139 Creates the smallest possible property list for basic email operations.
140 Includes only ID, thread ID, mailbox membership, and received date.
141
142 @return Minimal property list for efficiency *)
143val minimal_for_query : unit -> t list
144
145(** Build property list optimized for email preview display.
146
147 Optimized for showing email previews with sender, subject, date, and snippet.
148 Does not include body content or large metadata fields.
149
150 @return Property list optimized for preview display *)
151val for_preview : unit -> t list
152
153(** Build property list for full email reading.
154
155 Includes all properties needed for displaying complete email content
156 including text/HTML bodies, attachments, and all standard headers.
157
158 @return Comprehensive property list for full email display *)
159val for_reading : unit -> t list
160
161(** Build property list for email composition context.
162
163 Includes properties needed when composing replies or forwards:
164 thread information, addresses, subject, and body structure.
165
166 @return Property list optimized for composition workflows *)
167val for_composition : unit -> t list