this repo has no description
anil.recoil.org
1(** Implementation of the JMAP Mail extension, as defined in RFC8621
2 @see <https://datatracker.ietf.org/doc/html/rfc8621> RFC8621
3
4 This module implements the JMAP Mail specification, providing types and
5 functions for working with emails, mailboxes, threads, and other mail-related
6 objects in the JMAP protocol.
7*)
8
9(** Module for managing JMAP Mail-specific capability URIs as defined in RFC8621 Section 1.3
10 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3> RFC8621 Section 1.3
11*)
12module Capability : sig
13 (** Mail capability URI as defined in RFC8621 Section 1.3
14 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
15 *)
16 val mail_uri : string
17
18 (** Submission capability URI as defined in RFC8621 Section 1.3
19 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
20 *)
21 val submission_uri : string
22
23 (** Vacation response capability URI as defined in RFC8621 Section 1.3
24 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
25 *)
26 val vacation_response_uri : string
27
28 (** All mail extension capability types as defined in RFC8621 Section 1.3
29 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
30 *)
31 type t =
32 | Mail (** Mail capability for emails and mailboxes *)
33 | Submission (** Submission capability for sending emails *)
34 | VacationResponse (** Vacation response capability for auto-replies *)
35 | Extension of string (** Custom extension capabilities *)
36
37 (** Convert capability to URI string
38 @param capability The capability to convert
39 @return The full URI string for the capability
40 *)
41 val to_string : t -> string
42
43 (** Parse a string to a capability
44 @param uri The capability URI string to parse
45 @return The parsed capability type
46 *)
47 val of_string : string -> t
48
49 (** Check if a capability is a standard mail capability
50 @param capability The capability to check
51 @return True if the capability is a standard JMAP Mail capability
52 *)
53 val is_standard : t -> bool
54
55 (** Check if a capability string is a standard mail capability
56 @param uri The capability URI string to check
57 @return True if the string represents a standard JMAP Mail capability
58 *)
59 val is_standard_string : string -> bool
60
61 (** Create a list of capability strings
62 @param capabilities List of capability types
63 @return List of capability URI strings
64 *)
65 val strings_of_capabilities : t list -> string list
66end
67
68(** Types for the JMAP Mail extension as defined in RFC8621
69 @see <https://datatracker.ietf.org/doc/html/rfc8621>
70*)
71module Types : sig
72 open Jmap.Types
73
74 (** {1 Mail capabilities}
75 Capability URIs for JMAP Mail extension as defined in RFC8621 Section 1.3
76 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
77 *)
78
79 (** Capability URI for JMAP Mail as defined in RFC8621 Section 1.3
80 Identifies support for the Mail data model
81 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
82 *)
83 val capability_mail : string
84
85 (** Capability URI for JMAP Submission as defined in RFC8621 Section 1.3
86 Identifies support for email submission
87 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
88 *)
89 val capability_submission : string
90
91 (** Capability URI for JMAP Vacation Response as defined in RFC8621 Section 1.3
92 Identifies support for vacation auto-reply functionality
93 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
94 *)
95 val capability_vacation_response : string
96
97 (** {1:mailbox Mailbox objects}
98 Mailbox types as defined in RFC8621 Section 2
99 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
100 *)
101
102 (** A role for a mailbox as defined in RFC8621 Section 2.
103 Standardized roles for special mailboxes like Inbox, Sent, etc.
104 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
105 *)
106 type mailbox_role =
107 | All (** All mail mailbox *)
108 | Archive (** Archived mail mailbox *)
109 | Drafts (** Draft messages mailbox *)
110 | Flagged (** Starred/flagged mail mailbox *)
111 | Important (** Important mail mailbox *)
112 | Inbox (** Primary inbox mailbox *)
113 | Junk (** Spam/Junk mail mailbox *)
114 | Sent (** Sent mail mailbox *)
115 | Trash (** Deleted/Trash mail mailbox *)
116 | Unknown of string (** Server-specific custom roles *)
117
118 (** A mailbox (folder) in a mail account as defined in RFC8621 Section 2.
119 Represents an email folder or label in the account.
120 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
121 *)
122 type mailbox = {
123 id : id; (** Server-assigned ID for the mailbox *)
124 name : string; (** User-visible name for the mailbox *)
125 parent_id : id option; (** ID of the parent mailbox, if any *)
126 role : mailbox_role option; (** The role of this mailbox, if it's a special mailbox *)
127 sort_order : unsigned_int; (** Position for mailbox in the UI *)
128 total_emails : unsigned_int; (** Total number of emails in the mailbox *)
129 unread_emails : unsigned_int; (** Number of unread emails in the mailbox *)
130 total_threads : unsigned_int; (** Total number of threads in the mailbox *)
131 unread_threads : unsigned_int; (** Number of threads with unread emails *)
132 is_subscribed : bool; (** Has the user subscribed to this mailbox *)
133 my_rights : mailbox_rights; (** Access rights for the user on this mailbox *)
134 }
135
136 (** Rights for a mailbox as defined in RFC8621 Section 2.
137 Determines the operations a user can perform on a mailbox.
138 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
139 *)
140 and mailbox_rights = {
141 may_read_items : bool; (** Can the user read messages in this mailbox *)
142 may_add_items : bool; (** Can the user add messages to this mailbox *)
143 may_remove_items : bool; (** Can the user remove messages from this mailbox *)
144 may_set_seen : bool; (** Can the user mark messages as read/unread *)
145 may_set_keywords : bool; (** Can the user set keywords/flags on messages *)
146 may_create_child : bool; (** Can the user create child mailboxes *)
147 may_rename : bool; (** Can the user rename this mailbox *)
148 may_delete : bool; (** Can the user delete this mailbox *)
149 may_submit : bool; (** Can the user submit messages in this mailbox for delivery *)
150 }
151
152 (** Filter condition for mailbox queries as defined in RFC8621 Section 2.3.
153 Used to filter mailboxes in queries.
154 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
155 *)
156 type mailbox_filter_condition = {
157 parent_id : id option; (** Only include mailboxes with this parent *)
158 name : string option; (** Only include mailboxes with this name (case-insensitive substring match) *)
159 role : string option; (** Only include mailboxes with this role *)
160 has_any_role : bool option; (** If true, only include mailboxes with a role, if false those without *)
161 is_subscribed : bool option; (** If true, only include subscribed mailboxes, if false unsubscribed *)
162 }
163
164 (** Filter for mailbox queries as defined in RFC8621 Section 2.3.
165 Complex filter for Mailbox/query method.
166 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
167 *)
168 type mailbox_query_filter = [
169 | `And of mailbox_query_filter list (** Logical AND of filters *)
170 | `Or of mailbox_query_filter list (** Logical OR of filters *)
171 | `Not of mailbox_query_filter (** Logical NOT of a filter *)
172 | `Condition of mailbox_filter_condition (** Simple condition filter *)
173 ]
174
175 (** Mailbox/get request arguments as defined in RFC8621 Section 2.1.
176 Used to fetch mailboxes by ID.
177 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.1>
178 *)
179 type mailbox_get_arguments = {
180 account_id : id; (** The account to fetch mailboxes from *)
181 ids : id list option; (** The IDs of mailboxes to fetch, null means all *)
182 properties : string list option; (** Properties to return, null means all *)
183 }
184
185 (** Mailbox/get response as defined in RFC8621 Section 2.1.
186 Contains requested mailboxes.
187 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.1>
188 *)
189 type mailbox_get_response = {
190 account_id : id; (** The account from which mailboxes were fetched *)
191 state : string; (** A string representing the state on the server *)
192 list : mailbox list; (** The list of mailboxes requested *)
193 not_found : id list; (** IDs requested that could not be found *)
194 }
195
196 (** Mailbox/changes request arguments as defined in RFC8621 Section 2.2.
197 Used to get mailbox changes since a previous state.
198 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.2>
199 *)
200 type mailbox_changes_arguments = {
201 account_id : id; (** The account to get changes for *)
202 since_state : string; (** The previous state to compare to *)
203 max_changes : unsigned_int option; (** Maximum number of changes to return *)
204 }
205
206 (** Mailbox/changes response as defined in RFC8621 Section 2.2.
207 Reports mailboxes that have changed since a previous state.
208 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.2>
209 *)
210 type mailbox_changes_response = {
211 account_id : id; (** The account changes are for *)
212 old_state : string; (** The state provided in the request *)
213 new_state : string; (** The current state on the server *)
214 has_more_changes : bool; (** If true, more changes are available *)
215 created : id list; (** IDs of mailboxes created since old_state *)
216 updated : id list; (** IDs of mailboxes updated since old_state *)
217 destroyed : id list; (** IDs of mailboxes destroyed since old_state *)
218 }
219
220 (** Mailbox/query request arguments as defined in RFC8621 Section 2.3.
221 Used to query mailboxes based on filter criteria.
222 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
223 *)
224 type mailbox_query_arguments = {
225 account_id : id; (** The account to query *)
226 filter : mailbox_query_filter option; (** Filter to match mailboxes against *)
227 sort : [ `name | `role | `sort_order ] list option; (** Sort criteria *)
228 limit : unsigned_int option; (** Maximum number of results to return *)
229 }
230
231 (** Mailbox/query response as defined in RFC8621 Section 2.3.
232 Contains IDs of mailboxes matching the query.
233 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
234 *)
235 type mailbox_query_response = {
236 account_id : id; (** The account that was queried *)
237 query_state : string; (** State string for the query results *)
238 can_calculate_changes : bool; (** Whether queryChanges can be used with these results *)
239 position : unsigned_int; (** Zero-based index of the first result *)
240 ids : id list; (** IDs of mailboxes matching the query *)
241 total : unsigned_int option; (** Total number of matches if requested *)
242 }
243
244 (** Mailbox/queryChanges request arguments as defined in RFC8621 Section 2.4.
245 Used to get changes to mailbox query results.
246 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
247 *)
248 type mailbox_query_changes_arguments = {
249 account_id : id; (** The account to query *)
250 filter : mailbox_query_filter option; (** Same filter as the original query *)
251 sort : [ `name | `role | `sort_order ] list option; (** Same sort as the original query *)
252 since_query_state : string; (** The query_state from the previous result *)
253 max_changes : unsigned_int option; (** Maximum number of changes to return *)
254 up_to_id : id option; (** ID of the last mailbox to check for changes *)
255 }
256
257 (** Mailbox/queryChanges response as defined in RFC8621 Section 2.4.
258 Reports changes to a mailbox query since the previous state.
259 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
260 *)
261 type mailbox_query_changes_response = {
262 account_id : id; (** The account that was queried *)
263 old_query_state : string; (** The query_state from the request *)
264 new_query_state : string; (** The current query_state on the server *)
265 total : unsigned_int option; (** Updated total number of matches, if requested *)
266 removed : id list; (** IDs that were in the old results but not the new *)
267 added : mailbox_query_changes_added list; (** IDs that are in the new results but not the old *)
268 }
269
270 (** Added item in mailbox query changes as defined in RFC8621 Section 2.4.
271 Represents a mailbox added to query results.
272 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
273 *)
274 and mailbox_query_changes_added = {
275 id : id; (** ID of the added mailbox *)
276 index : unsigned_int; (** Zero-based index of the added mailbox in the results *)
277 }
278
279 (** Mailbox/set request arguments as defined in RFC8621 Section 2.5.
280 Used to create, update, and destroy mailboxes.
281 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
282 *)
283 type mailbox_set_arguments = {
284 account_id : id; (** The account to make changes in *)
285 if_in_state : string option; (** Only apply changes if in this state *)
286 create : (id * mailbox_creation) list option; (** Map of creation IDs to mailboxes to create *)
287 update : (id * mailbox_update) list option; (** Map of IDs to update properties *)
288 destroy : id list option; (** List of IDs to destroy *)
289 }
290
291 (** Properties for mailbox creation as defined in RFC8621 Section 2.5.
292 Used to create new mailboxes.
293 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
294 *)
295 and mailbox_creation = {
296 name : string; (** Name for the new mailbox *)
297 parent_id : id option; (** ID of the parent mailbox, if any *)
298 role : string option; (** Role for the mailbox, if it's a special-purpose mailbox *)
299 sort_order : unsigned_int option; (** Sort order, defaults to 0 *)
300 is_subscribed : bool option; (** Whether the mailbox is subscribed, defaults to true *)
301 }
302
303 (** Properties for mailbox update as defined in RFC8621 Section 2.5.
304 Used to update existing mailboxes.
305 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
306 *)
307 and mailbox_update = {
308 name : string option; (** New name for the mailbox *)
309 parent_id : id option; (** New parent ID for the mailbox *)
310 role : string option; (** New role for the mailbox *)
311 sort_order : unsigned_int option; (** New sort order for the mailbox *)
312 is_subscribed : bool option; (** New subscription status for the mailbox *)
313 }
314
315 (** Mailbox/set response as defined in RFC8621 Section 2.5.
316 Reports the results of mailbox changes.
317 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
318 *)
319 type mailbox_set_response = {
320 account_id : id; (** The account that was modified *)
321 old_state : string option; (** The state before processing, if changed *)
322 new_state : string; (** The current state on the server *)
323 created : (id * mailbox) list option; (** Map of creation IDs to created mailboxes *)
324 updated : id list option; (** List of IDs that were successfully updated *)
325 destroyed : id list option; (** List of IDs that were successfully destroyed *)
326 not_created : (id * set_error) list option; (** Map of IDs to errors for failed creates *)
327 not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
328 not_destroyed : (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
329 }
330
331 (** {1:thread Thread objects}
332 Thread types as defined in RFC8621 Section 3
333 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3>
334 *)
335
336 (** A thread in a mail account as defined in RFC8621 Section 3.
337 Represents a group of related email messages.
338 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3>
339 *)
340 type thread = {
341 id : id; (** Server-assigned ID for the thread *)
342 email_ids : id list; (** IDs of emails in the thread *)
343 }
344
345 (** Thread/get request arguments as defined in RFC8621 Section 3.1.
346 Used to fetch threads by ID.
347 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.1>
348 *)
349 type thread_get_arguments = {
350 account_id : id; (** The account to fetch threads from *)
351 ids : id list option; (** The IDs of threads to fetch, null means all *)
352 properties : string list option; (** Properties to return, null means all *)
353 }
354
355 (** Thread/get response as defined in RFC8621 Section 3.1.
356 Contains requested threads.
357 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.1>
358 *)
359 type thread_get_response = {
360 account_id : id; (** The account from which threads were fetched *)
361 state : string; (** A string representing the state on the server *)
362 list : thread list; (** The list of threads requested *)
363 not_found : id list; (** IDs requested that could not be found *)
364 }
365
366 (** Thread/changes request arguments as defined in RFC8621 Section 3.2.
367 Used to get thread changes since a previous state.
368 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.2>
369 *)
370 type thread_changes_arguments = {
371 account_id : id; (** The account to get changes for *)
372 since_state : string; (** The previous state to compare to *)
373 max_changes : unsigned_int option; (** Maximum number of changes to return *)
374 }
375
376 (** Thread/changes response as defined in RFC8621 Section 3.2.
377 Reports threads that have changed since a previous state.
378 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.2>
379 *)
380 type thread_changes_response = {
381 account_id : id; (** The account changes are for *)
382 old_state : string; (** The state provided in the request *)
383 new_state : string; (** The current state on the server *)
384 has_more_changes : bool; (** If true, more changes are available *)
385 created : id list; (** IDs of threads created since old_state *)
386 updated : id list; (** IDs of threads updated since old_state *)
387 destroyed : id list; (** IDs of threads destroyed since old_state *)
388 }
389
390 (** {1:email Email objects}
391 Email types as defined in RFC8621 Section 4
392 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4>
393 *)
394
395 (** Addressing (mailbox) information as defined in RFC8621 Section 4.1.1.
396 Represents an email address with optional display name.
397 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.1>
398 *)
399 type email_address = {
400 name : string option; (** Display name of the mailbox (e.g., "John Doe") *)
401 email : string; (** The email address (e.g., "john@example.com") *)
402 parameters : (string * string) list; (** Additional parameters for the address *)
403 }
404
405 (** Message header field as defined in RFC8621 Section 4.1.2.
406 Represents an email header.
407 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.2>
408 *)
409 type header = {
410 name : string; (** Name of the header field (e.g., "Subject") *)
411 value : string; (** Value of the header field *)
412 }
413
414 (** Email keyword (flag) as defined in RFC8621 Section 4.3.
415 Represents a flag or tag on an email message.
416 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.3>
417 *)
418 type keyword =
419 | Flagged (** Message is flagged/starred *)
420 | Answered (** Message has been replied to *)
421 | Draft (** Message is a draft *)
422 | Forwarded (** Message has been forwarded *)
423 | Phishing (** Message has been reported as phishing *)
424 | Junk (** Message is spam/junk *)
425 | NotJunk (** Message is explicitly not spam *)
426 | Seen (** Message has been read *)
427 | Unread (** Message is unread (inverse of $seen) *)
428 | Custom of string (** Custom/non-standard keywords *)
429
430 (** Email message as defined in RFC8621 Section 4.
431 Represents an email message in a mail account.
432 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4>
433 *)
434 type email = {
435 id : id; (** Server-assigned ID for the message *)
436 blob_id : id; (** ID of the raw message content blob *)
437 thread_id : id; (** ID of the thread this message belongs to *)
438 mailbox_ids : (id * bool) list; (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
439 keywords : (keyword * bool) list; (** Map of keywords to boolean (whether message has keyword) *)
440 size : unsigned_int; (** Size of the message in octets *)
441 received_at : utc_date; (** When the message was received by the server *)
442 message_id : string list; (** Message-ID header values *)
443 in_reply_to : string list option; (** In-Reply-To header values *)
444 references : string list option; (** References header values *)
445 sender : email_address list option; (** Sender header addresses *)
446 from : email_address list option; (** From header addresses *)
447 to_ : email_address list option; (** To header addresses *)
448 cc : email_address list option; (** Cc header addresses *)
449 bcc : email_address list option; (** Bcc header addresses *)
450 reply_to : email_address list option; (** Reply-To header addresses *)
451 subject : string option; (** Subject header value *)
452 sent_at : utc_date option; (** Date header value as a date-time *)
453 has_attachment : bool option; (** Does the message have any attachments *)
454 preview : string option; (** Preview of the message (first bit of text) *)
455 body_values : (string * string) list option; (** Map of part IDs to text content *)
456 text_body : email_body_part list option; (** Plain text message body parts *)
457 html_body : email_body_part list option; (** HTML message body parts *)
458 attachments : email_body_part list option; (** Attachment parts in the message *)
459 headers : header list option; (** All headers in the message *)
460 }
461
462 (** Email body part as defined in RFC8621 Section 4.1.4.
463 Represents a MIME part in an email message.
464 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.4>
465 *)
466 and email_body_part = {
467 part_id : string option; (** Server-assigned ID for the MIME part *)
468 blob_id : id option; (** ID of the raw content for this part *)
469 size : unsigned_int option; (** Size of the part in octets *)
470 headers : header list option; (** Headers for this MIME part *)
471 name : string option; (** Filename of this part, if any *)
472 type_ : string option; (** MIME type of the part *)
473 charset : string option; (** Character set of the part, if applicable *)
474 disposition : string option; (** Content-Disposition value *)
475 cid : string option; (** Content-ID value *)
476 language : string list option; (** Content-Language values *)
477 location : string option; (** Content-Location value *)
478 sub_parts : email_body_part list option; (** Child MIME parts for multipart types *)
479 header_parameter_name : string option; (** Header parameter name (for headers with parameters) *)
480 header_parameter_value : string option; (** Header parameter value (for headers with parameters) *)
481 }
482
483 (** Email query filter condition as defined in RFC8621 Section 4.4.
484 Specifies conditions for filtering emails in queries.
485 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
486 *)
487 type email_filter_condition = {
488 in_mailbox : id option; (** Only include emails in this mailbox *)
489 in_mailbox_other_than : id list option; (** Only include emails not in these mailboxes *)
490 min_size : unsigned_int option; (** Only include emails of at least this size in octets *)
491 max_size : unsigned_int option; (** Only include emails of at most this size in octets *)
492 before : utc_date option; (** Only include emails received before this date-time *)
493 after : utc_date option; (** Only include emails received after this date-time *)
494 header : (string * string) option; (** Only include emails with header matching value (name, value) *)
495 from : string option; (** Only include emails with From containing this text *)
496 to_ : string option; (** Only include emails with To containing this text *)
497 cc : string option; (** Only include emails with CC containing this text *)
498 bcc : string option; (** Only include emails with BCC containing this text *)
499 subject : string option; (** Only include emails with Subject containing this text *)
500 body : string option; (** Only include emails with body containing this text *)
501 has_keyword : string option; (** Only include emails with this keyword *)
502 not_keyword : string option; (** Only include emails without this keyword *)
503 has_attachment : bool option; (** If true, only include emails with attachments *)
504 text : string option; (** Only include emails with this text in headers or body *)
505 }
506
507 (** Filter for email queries as defined in RFC8621 Section 4.4.
508 Complex filter for Email/query method.
509 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
510 *)
511 type email_query_filter = [
512 | `And of email_query_filter list (** Logical AND of filters *)
513 | `Or of email_query_filter list (** Logical OR of filters *)
514 | `Not of email_query_filter (** Logical NOT of a filter *)
515 | `Condition of email_filter_condition (** Simple condition filter *)
516 ]
517
518 (** Email/get request arguments as defined in RFC8621 Section 4.5.
519 Used to fetch emails by ID.
520 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.5>
521 *)
522 type email_get_arguments = {
523 account_id : id; (** The account to fetch emails from *)
524 ids : id list option; (** The IDs of emails to fetch, null means all *)
525 properties : string list option; (** Properties to return, null means all *)
526 body_properties : string list option; (** Properties to return on body parts *)
527 fetch_text_body_values : bool option; (** Whether to fetch text body content *)
528 fetch_html_body_values : bool option; (** Whether to fetch HTML body content *)
529 fetch_all_body_values : bool option; (** Whether to fetch all body content *)
530 max_body_value_bytes : unsigned_int option; (** Maximum size of body values to return *)
531 }
532
533 (** Email/get response as defined in RFC8621 Section 4.5.
534 Contains requested emails.
535 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.5>
536 *)
537 type email_get_response = {
538 account_id : id; (** The account from which emails were fetched *)
539 state : string; (** A string representing the state on the server *)
540 list : email list; (** The list of emails requested *)
541 not_found : id list; (** IDs requested that could not be found *)
542 }
543
544 (** Email/changes request arguments as defined in RFC8621 Section 4.6.
545 Used to get email changes since a previous state.
546 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.6>
547 *)
548 type email_changes_arguments = {
549 account_id : id; (** The account to get changes for *)
550 since_state : string; (** The previous state to compare to *)
551 max_changes : unsigned_int option; (** Maximum number of changes to return *)
552 }
553
554 (** Email/changes response as defined in RFC8621 Section 4.6.
555 Reports emails that have changed since a previous state.
556 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.6>
557 *)
558 type email_changes_response = {
559 account_id : id; (** The account changes are for *)
560 old_state : string; (** The state provided in the request *)
561 new_state : string; (** The current state on the server *)
562 has_more_changes : bool; (** If true, more changes are available *)
563 created : id list; (** IDs of emails created since old_state *)
564 updated : id list; (** IDs of emails updated since old_state *)
565 destroyed : id list; (** IDs of emails destroyed since old_state *)
566 }
567
568 (** Email/query request arguments as defined in RFC8621 Section 4.4.
569 Used to query emails based on filter criteria.
570 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
571 *)
572 type email_query_arguments = {
573 account_id : id; (** The account to query *)
574 filter : email_query_filter option; (** Filter to match emails against *)
575 sort : comparator list option; (** Sort criteria *)
576 collapse_threads : bool option; (** Whether to collapse threads in the results *)
577 position : unsigned_int option; (** Zero-based index of first result to return *)
578 anchor : id option; (** ID of email to use as reference point *)
579 anchor_offset : int_t option; (** Offset from anchor to start returning results *)
580 limit : unsigned_int option; (** Maximum number of results to return *)
581 calculate_total : bool option; (** Whether to calculate the total number of matching emails *)
582 }
583
584 (** Email/query response as defined in RFC8621 Section 4.4.
585 Contains IDs of emails matching the query.
586 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
587 *)
588 type email_query_response = {
589 account_id : id; (** The account that was queried *)
590 query_state : string; (** State string for the query results *)
591 can_calculate_changes : bool; (** Whether queryChanges can be used with these results *)
592 position : unsigned_int; (** Zero-based index of the first result *)
593 ids : id list; (** IDs of emails matching the query *)
594 total : unsigned_int option; (** Total number of matches if requested *)
595 thread_ids : id list option; (** IDs of threads if collapse_threads was true *)
596 }
597
598 (** Email/queryChanges request arguments as defined in RFC8621 Section 4.7.
599 Used to get changes to email query results.
600 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
601 *)
602 type email_query_changes_arguments = {
603 account_id : id; (** The account to query *)
604 filter : email_query_filter option; (** Same filter as the original query *)
605 sort : comparator list option; (** Same sort as the original query *)
606 collapse_threads : bool option; (** Same collapse_threads as the original query *)
607 since_query_state : string; (** The query_state from the previous result *)
608 max_changes : unsigned_int option; (** Maximum number of changes to return *)
609 up_to_id : id option; (** ID of the last email to check for changes *)
610 }
611
612 (** Email/queryChanges response as defined in RFC8621 Section 4.7.
613 Reports changes to an email query since the previous state.
614 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
615 *)
616 type email_query_changes_response = {
617 account_id : id; (** The account that was queried *)
618 old_query_state : string; (** The query_state from the request *)
619 new_query_state : string; (** The current query_state on the server *)
620 total : unsigned_int option; (** Updated total number of matches, if requested *)
621 removed : id list; (** IDs that were in the old results but not the new *)
622 added : email_query_changes_added list; (** IDs that are in the new results but not the old *)
623 }
624
625 (** Added item in email query changes as defined in RFC8621 Section 4.7.
626 Represents an email added to query results.
627 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
628 *)
629 and email_query_changes_added = {
630 id : id; (** ID of the added email *)
631 index : unsigned_int; (** Zero-based index of the added email in the results *)
632 }
633
634 (** Email/set request arguments as defined in RFC8621 Section 4.8.
635 Used to create, update, and destroy emails.
636 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
637 *)
638 type email_set_arguments = {
639 account_id : id; (** The account to make changes in *)
640 if_in_state : string option; (** Only apply changes if in this state *)
641 create : (id * email_creation) list option; (** Map of creation IDs to emails to create *)
642 update : (id * email_update) list option; (** Map of IDs to update properties *)
643 destroy : id list option; (** List of IDs to destroy *)
644 }
645
646 (** Properties for email creation as defined in RFC8621 Section 4.8.
647 Used to create new emails.
648 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
649 *)
650 and email_creation = {
651 mailbox_ids : (id * bool) list; (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
652 keywords : (keyword * bool) list option; (** Map of keywords to boolean (whether message has keyword) *)
653 received_at : utc_date option; (** When the message was received by the server *)
654 message_id : string list option; (** Message-ID header values *)
655 in_reply_to : string list option; (** In-Reply-To header values *)
656 references : string list option; (** References header values *)
657 sender : email_address list option; (** Sender header addresses *)
658 from : email_address list option; (** From header addresses *)
659 to_ : email_address list option; (** To header addresses *)
660 cc : email_address list option; (** Cc header addresses *)
661 bcc : email_address list option; (** Bcc header addresses *)
662 reply_to : email_address list option; (** Reply-To header addresses *)
663 subject : string option; (** Subject header value *)
664 body_values : (string * string) list option; (** Map of part IDs to text content *)
665 text_body : email_body_part list option; (** Plain text message body parts *)
666 html_body : email_body_part list option; (** HTML message body parts *)
667 attachments : email_body_part list option; (** Attachment parts in the message *)
668 headers : header list option; (** All headers in the message *)
669 }
670
671 (** Properties for email update as defined in RFC8621 Section 4.8.
672 Used to update existing emails.
673 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
674 *)
675 and email_update = {
676 keywords : (keyword * bool) list option; (** New keywords to set on the email *)
677 mailbox_ids : (id * bool) list option; (** New mailboxes to set for the email *)
678 }
679
680 (** Email/set response as defined in RFC8621 Section 4.8.
681 Reports the results of email changes.
682 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
683 *)
684 type email_set_response = {
685 account_id : id; (** The account that was modified *)
686 old_state : string option; (** The state before processing, if changed *)
687 new_state : string; (** The current state on the server *)
688 created : (id * email) list option; (** Map of creation IDs to created emails *)
689 updated : id list option; (** List of IDs that were successfully updated *)
690 destroyed : id list option; (** List of IDs that were successfully destroyed *)
691 not_created : (id * set_error) list option; (** Map of IDs to errors for failed creates *)
692 not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
693 not_destroyed : (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
694 }
695
696 (** Email/copy request arguments as defined in RFC8621 Section 4.9.
697 Used to copy emails between accounts.
698 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.9>
699 *)
700 type email_copy_arguments = {
701 from_account_id : id; (** The account to copy emails from *)
702 account_id : id; (** The account to copy emails to *)
703 create : (id * email_creation) list; (** Map of creation IDs to email creation properties *)
704 on_success_destroy_original : bool option; (** Whether to destroy originals after copying *)
705 }
706
707 (** Email/copy response as defined in RFC8621 Section 4.9.
708 Reports the results of copying emails.
709 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.9>
710 *)
711 type email_copy_response = {
712 from_account_id : id; (** The account emails were copied from *)
713 account_id : id; (** The account emails were copied to *)
714 created : (id * email) list option; (** Map of creation IDs to created emails *)
715 not_created : (id * set_error) list option; (** Map of IDs to errors for failed copies *)
716 }
717
718 (** Email/import request arguments as defined in RFC8621 Section 4.10.
719 Used to import raw emails from blobs.
720 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
721 *)
722 type email_import_arguments = {
723 account_id : id; (** The account to import emails into *)
724 emails : (id * email_import) list; (** Map of creation IDs to import properties *)
725 }
726
727 (** Properties for email import as defined in RFC8621 Section 4.10.
728 Used to import raw emails from blobs.
729 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
730 *)
731 and email_import = {
732 blob_id : id; (** ID of the blob containing the raw message *)
733 mailbox_ids : (id * bool) list; (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
734 keywords : (keyword * bool) list option; (** Map of keywords to boolean (whether message has keyword) *)
735 received_at : utc_date option; (** When the message was received, defaults to now *)
736 }
737
738 (** Email/import response as defined in RFC8621 Section 4.10.
739 Reports the results of importing emails.
740 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
741 *)
742 type email_import_response = {
743 account_id : id; (** The account emails were imported into *)
744 created : (id * email) list option; (** Map of creation IDs to created emails *)
745 not_created : (id * set_error) list option; (** Map of IDs to errors for failed imports *)
746 }
747
748 (** {1:search_snippet Search snippets}
749 Search snippet types as defined in RFC8621 Section 4.11
750 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
751 *)
752
753 (** SearchSnippet/get request arguments as defined in RFC8621 Section 4.11.
754 Used to get highlighted snippets from emails matching a search.
755 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
756 *)
757 type search_snippet_get_arguments = {
758 account_id : id; (** The account to search in *)
759 email_ids : id list; (** The IDs of emails to get snippets for *)
760 filter : email_filter_condition; (** Filter containing the text to find and highlight *)
761 }
762
763 (** SearchSnippet/get response as defined in RFC8621 Section 4.11.
764 Contains search result snippets with highlighted text.
765 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
766 *)
767 type search_snippet_get_response = {
768 account_id : id; (** The account that was searched *)
769 list : (id * search_snippet) list; (** Map of email IDs to their search snippets *)
770 not_found : id list; (** IDs for which no snippet could be generated *)
771 }
772
773 (** Search snippet for an email as defined in RFC8621 Section 4.11.
774 Contains highlighted parts of emails matching a search.
775 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
776 *)
777 and search_snippet = {
778 subject : string option; (** Subject with search terms highlighted *)
779 preview : string option; (** Email body preview with search terms highlighted *)
780 }
781
782 (** {1:submission EmailSubmission objects}
783 Email submission types as defined in RFC8621 Section 5
784 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5>
785 *)
786
787 (** EmailSubmission address as defined in RFC8621 Section 5.1.
788 Represents an email address for mail submission.
789 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
790 *)
791 type submission_address = {
792 email : string; (** The email address (e.g., "john@example.com") *)
793 parameters : (string * string) list option; (** SMTP extension parameters *)
794 }
795
796 (** Email submission object as defined in RFC8621 Section 5.1.
797 Represents an email that has been or will be sent.
798 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
799 *)
800 type email_submission = {
801 id : id; (** Server-assigned ID for the submission *)
802 identity_id : id; (** ID of the identity used to send the email *)
803 email_id : id; (** ID of the email to send *)
804 thread_id : id; (** ID of the thread containing the message *)
805 envelope : envelope option; (** SMTP envelope for the message *)
806 send_at : utc_date option; (** When to send the email, null for immediate *)
807 undo_status : [
808 | `pending (** Submission can still be canceled *)
809 | `final (** Submission can no longer be canceled *)
810 | `canceled (** Submission was canceled *)
811 ] option; (** Current undo status of the submission *)
812 delivery_status : (string * submission_status) list option; (** Map of recipient to delivery status *)
813 dsn_blob_ids : (string * id) list option; (** Map of recipient to DSN blob ID *)
814 mdn_blob_ids : (string * id) list option; (** Map of recipient to MDN blob ID *)
815 }
816
817 (** Envelope for mail submission as defined in RFC8621 Section 5.1.
818 Represents the SMTP envelope for a message.
819 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
820 *)
821 and envelope = {
822 mail_from : submission_address; (** Return path for the message *)
823 rcpt_to : submission_address list; (** Recipients for the message *)
824 }
825
826 (** Delivery status for submitted email as defined in RFC8621 Section 5.1.
827 Represents the SMTP status of a delivery attempt.
828 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
829 *)
830 and submission_status = {
831 smtp_reply : string; (** SMTP response from the server *)
832 delivered : string option; (** Timestamp when message was delivered, if successful *)
833 }
834
835 (** EmailSubmission/get request arguments as defined in RFC8621 Section 5.3.
836 Used to fetch email submissions by ID.
837 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.3>
838 *)
839 type email_submission_get_arguments = {
840 account_id : id; (** The account to fetch submissions from *)
841 ids : id list option; (** The IDs of submissions to fetch, null means all *)
842 properties : string list option; (** Properties to return, null means all *)
843 }
844
845 (** EmailSubmission/get response as defined in RFC8621 Section 5.3.
846 Contains requested email submissions.
847 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.3>
848 *)
849 type email_submission_get_response = {
850 account_id : id; (** The account from which submissions were fetched *)
851 state : string; (** A string representing the state on the server *)
852 list : email_submission list; (** The list of submissions requested *)
853 not_found : id list; (** IDs requested that could not be found *)
854 }
855
856 (** EmailSubmission/changes request arguments as defined in RFC8621 Section 5.4.
857 Used to get submission changes since a previous state.
858 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.4>
859 *)
860 type email_submission_changes_arguments = {
861 account_id : id; (** The account to get changes for *)
862 since_state : string; (** The previous state to compare to *)
863 max_changes : unsigned_int option; (** Maximum number of changes to return *)
864 }
865
866 (** EmailSubmission/changes response as defined in RFC8621 Section 5.4.
867 Reports submissions that have changed since a previous state.
868 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.4>
869 *)
870 type email_submission_changes_response = {
871 account_id : id; (** The account changes are for *)
872 old_state : string; (** The state provided in the request *)
873 new_state : string; (** The current state on the server *)
874 has_more_changes : bool; (** If true, more changes are available *)
875 created : id list; (** IDs of submissions created since old_state *)
876 updated : id list; (** IDs of submissions updated since old_state *)
877 destroyed : id list; (** IDs of submissions destroyed since old_state *)
878 }
879
880 (** EmailSubmission/query filter condition as defined in RFC8621 Section 5.5.
881 Specifies conditions for filtering email submissions in queries.
882 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
883 *)
884 type email_submission_filter_condition = {
885 identity_id : id option; (** Only include submissions with this identity *)
886 email_id : id option; (** Only include submissions for this email *)
887 thread_id : id option; (** Only include submissions for emails in this thread *)
888 before : utc_date option; (** Only include submissions created before this date-time *)
889 after : utc_date option; (** Only include submissions created after this date-time *)
890 subject : string option; (** Only include submissions with matching subjects *)
891 }
892
893 (** Filter for email submission queries as defined in RFC8621 Section 5.5.
894 Complex filter for EmailSubmission/query method.
895 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
896 *)
897 type email_submission_query_filter = [
898 | `And of email_submission_query_filter list (** Logical AND of filters *)
899 | `Or of email_submission_query_filter list (** Logical OR of filters *)
900 | `Not of email_submission_query_filter (** Logical NOT of a filter *)
901 | `Condition of email_submission_filter_condition (** Simple condition filter *)
902 ]
903
904 (** EmailSubmission/query request arguments as defined in RFC8621 Section 5.5.
905 Used to query email submissions based on filter criteria.
906 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
907 *)
908 type email_submission_query_arguments = {
909 account_id : id; (** The account to query *)
910 filter : email_submission_query_filter option; (** Filter to match submissions against *)
911 sort : comparator list option; (** Sort criteria *)
912 position : unsigned_int option; (** Zero-based index of first result to return *)
913 anchor : id option; (** ID of submission to use as reference point *)
914 anchor_offset : int_t option; (** Offset from anchor to start returning results *)
915 limit : unsigned_int option; (** Maximum number of results to return *)
916 calculate_total : bool option; (** Whether to calculate the total number of matching submissions *)
917 }
918
919 (** EmailSubmission/query response as defined in RFC8621 Section 5.5.
920 Contains IDs of email submissions matching the query.
921 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
922 *)
923 type email_submission_query_response = {
924 account_id : id; (** The account that was queried *)
925 query_state : string; (** State string for the query results *)
926 can_calculate_changes : bool; (** Whether queryChanges can be used with these results *)
927 position : unsigned_int; (** Zero-based index of the first result *)
928 ids : id list; (** IDs of email submissions matching the query *)
929 total : unsigned_int option; (** Total number of matches if requested *)
930 }
931
932 (** EmailSubmission/set request arguments as defined in RFC8621 Section 5.6.
933 Used to create, update, and destroy email submissions.
934 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
935 *)
936 type email_submission_set_arguments = {
937 account_id : id; (** The account to make changes in *)
938 if_in_state : string option; (** Only apply changes if in this state *)
939 create : (id * email_submission_creation) list option; (** Map of creation IDs to submissions to create *)
940 update : (id * email_submission_update) list option; (** Map of IDs to update properties *)
941 destroy : id list option; (** List of IDs to destroy *)
942 on_success_update_email : (id * email_update) list option; (** Emails to update if submissions succeed *)
943 }
944
945 (** Properties for email submission creation as defined in RFC8621 Section 5.6.
946 Used to create new email submissions.
947 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
948 *)
949 and email_submission_creation = {
950 email_id : id; (** ID of the email to send *)
951 identity_id : id; (** ID of the identity to send from *)
952 envelope : envelope option; (** Custom envelope, if needed *)
953 send_at : utc_date option; (** When to send the email, defaults to now *)
954 }
955
956 (** Properties for email submission update as defined in RFC8621 Section 5.6.
957 Used to update existing email submissions.
958 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
959 *)
960 and email_submission_update = {
961 email_id : id option; (** New email ID to use for this submission *)
962 identity_id : id option; (** New identity ID to use for this submission *)
963 envelope : envelope option; (** New envelope to use for this submission *)
964 undo_status : [`canceled] option; (** Set to cancel a pending submission *)
965 }
966
967 (** EmailSubmission/set response as defined in RFC8621 Section 5.6.
968 Reports the results of email submission changes.
969 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
970 *)
971 type email_submission_set_response = {
972 account_id : id; (** The account that was modified *)
973 old_state : string option; (** The state before processing, if changed *)
974 new_state : string; (** The current state on the server *)
975 created : (id * email_submission) list option; (** Map of creation IDs to created submissions *)
976 updated : id list option; (** List of IDs that were successfully updated *)
977 destroyed : id list option; (** List of IDs that were successfully destroyed *)
978 not_created : (id * set_error) list option; (** Map of IDs to errors for failed creates *)
979 not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
980 not_destroyed : (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
981 }
982
983 (** {1:identity Identity objects}
984 Identity types as defined in RFC8621 Section 6
985 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6>
986 *)
987
988 (** Identity for sending mail as defined in RFC8621 Section 6.
989 Represents an email identity that can be used to send messages.
990 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6>
991 *)
992 type identity = {
993 id : id; (** Server-assigned ID for the identity *)
994 name : string; (** Display name for the identity *)
995 email : string; (** Email address for the identity *)
996 reply_to : email_address list option; (** Reply-To addresses to use when sending *)
997 bcc : email_address list option; (** BCC addresses to automatically include *)
998 text_signature : string option; (** Plain text signature for the identity *)
999 html_signature : string option; (** HTML signature for the identity *)
1000 may_delete : bool; (** Whether this identity can be deleted *)
1001 }
1002
1003 (** Identity/get request arguments as defined in RFC8621 Section 6.1.
1004 Used to fetch identities by ID.
1005 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.1>
1006 *)
1007 type identity_get_arguments = {
1008 account_id : id; (** The account to fetch identities from *)
1009 ids : id list option; (** The IDs of identities to fetch, null means all *)
1010 properties : string list option; (** Properties to return, null means all *)
1011 }
1012
1013 (** Identity/get response as defined in RFC8621 Section 6.1.
1014 Contains requested identities.
1015 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.1>
1016 *)
1017 type identity_get_response = {
1018 account_id : id; (** The account from which identities were fetched *)
1019 state : string; (** A string representing the state on the server *)
1020 list : identity list; (** The list of identities requested *)
1021 not_found : id list; (** IDs requested that could not be found *)
1022 }
1023
1024 (** Identity/changes request arguments as defined in RFC8621 Section 6.2.
1025 Used to get identity changes since a previous state.
1026 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.2>
1027 *)
1028 type identity_changes_arguments = {
1029 account_id : id; (** The account to get changes for *)
1030 since_state : string; (** The previous state to compare to *)
1031 max_changes : unsigned_int option; (** Maximum number of changes to return *)
1032 }
1033
1034 (** Identity/changes response as defined in RFC8621 Section 6.2.
1035 Reports identities that have changed since a previous state.
1036 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.2>
1037 *)
1038 type identity_changes_response = {
1039 account_id : id; (** The account changes are for *)
1040 old_state : string; (** The state provided in the request *)
1041 new_state : string; (** The current state on the server *)
1042 has_more_changes : bool; (** If true, more changes are available *)
1043 created : id list; (** IDs of identities created since old_state *)
1044 updated : id list; (** IDs of identities updated since old_state *)
1045 destroyed : id list; (** IDs of identities destroyed since old_state *)
1046 }
1047
1048 (** Identity/set request arguments as defined in RFC8621 Section 6.3.
1049 Used to create, update, and destroy identities.
1050 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
1051 *)
1052 type identity_set_arguments = {
1053 account_id : id; (** The account to make changes in *)
1054 if_in_state : string option; (** Only apply changes if in this state *)
1055 create : (id * identity_creation) list option; (** Map of creation IDs to identities to create *)
1056 update : (id * identity_update) list option; (** Map of IDs to update properties *)
1057 destroy : id list option; (** List of IDs to destroy *)
1058 }
1059
1060 (** Properties for identity creation as defined in RFC8621 Section 6.3.
1061 Used to create new identities.
1062 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
1063 *)
1064 and identity_creation = {
1065 name : string; (** Display name for the identity *)
1066 email : string; (** Email address for the identity *)
1067 reply_to : email_address list option; (** Reply-To addresses to use when sending *)
1068 bcc : email_address list option; (** BCC addresses to automatically include *)
1069 text_signature : string option; (** Plain text signature for the identity *)
1070 html_signature : string option; (** HTML signature for the identity *)
1071 }
1072
1073 (** Properties for identity update as defined in RFC8621 Section 6.3.
1074 Used to update existing identities.
1075 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
1076 *)
1077 and identity_update = {
1078 name : string option; (** New display name for the identity *)
1079 email : string option; (** New email address for the identity *)
1080 reply_to : email_address list option; (** New Reply-To addresses to use *)
1081 bcc : email_address list option; (** New BCC addresses to automatically include *)
1082 text_signature : string option; (** New plain text signature *)
1083 html_signature : string option; (** New HTML signature *)
1084 }
1085
1086 (** Identity/set response as defined in RFC8621 Section 6.3.
1087 Reports the results of identity changes.
1088 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
1089 *)
1090 type identity_set_response = {
1091 account_id : id; (** The account that was modified *)
1092 old_state : string option; (** The state before processing, if changed *)
1093 new_state : string; (** The current state on the server *)
1094 created : (id * identity) list option; (** Map of creation IDs to created identities *)
1095 updated : id list option; (** List of IDs that were successfully updated *)
1096 destroyed : id list option; (** List of IDs that were successfully destroyed *)
1097 not_created : (id * set_error) list option; (** Map of IDs to errors for failed creates *)
1098 not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
1099 not_destroyed : (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
1100 }
1101
1102 (** {1:vacation_response VacationResponse objects}
1103 Vacation response types as defined in RFC8621 Section 7
1104 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7>
1105 *)
1106
1107 (** Vacation auto-reply setting as defined in RFC8621 Section 7.
1108 Represents an automatic vacation/out-of-office response.
1109 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7>
1110 *)
1111 type vacation_response = {
1112 id : id; (** Server-assigned ID for the vacation response *)
1113 is_enabled : bool; (** Whether the vacation response is active *)
1114 from_date : utc_date option; (** Start date-time of the vacation period *)
1115 to_date : utc_date option; (** End date-time of the vacation period *)
1116 subject : string option; (** Subject line for the vacation response *)
1117 text_body : string option; (** Plain text body for the vacation response *)
1118 html_body : string option; (** HTML body for the vacation response *)
1119 }
1120
1121 (** VacationResponse/get request arguments as defined in RFC8621 Section 7.2.
1122 Used to fetch vacation responses by ID.
1123 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.2>
1124 *)
1125 type vacation_response_get_arguments = {
1126 account_id : id; (** The account to fetch vacation responses from *)
1127 ids : id list option; (** The IDs of vacation responses to fetch, null means all *)
1128 properties : string list option; (** Properties to return, null means all *)
1129 }
1130
1131 (** VacationResponse/get response as defined in RFC8621 Section 7.2.
1132 Contains requested vacation responses.
1133 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.2>
1134 *)
1135 type vacation_response_get_response = {
1136 account_id : id; (** The account from which vacation responses were fetched *)
1137 state : string; (** A string representing the state on the server *)
1138 list : vacation_response list; (** The list of vacation responses requested *)
1139 not_found : id list; (** IDs requested that could not be found *)
1140 }
1141
1142 (** VacationResponse/set request arguments as defined in RFC8621 Section 7.3.
1143 Used to update vacation responses.
1144 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
1145 *)
1146 type vacation_response_set_arguments = {
1147 account_id : id; (** The account to make changes in *)
1148 if_in_state : string option; (** Only apply changes if in this state *)
1149 update : (id * vacation_response_update) list; (** Map of IDs to update properties *)
1150 }
1151
1152 (** Properties for vacation response update as defined in RFC8621 Section 7.3.
1153 Used to update existing vacation responses.
1154 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
1155 *)
1156 and vacation_response_update = {
1157 is_enabled : bool option; (** Whether the vacation response is active *)
1158 from_date : utc_date option; (** Start date-time of the vacation period *)
1159 to_date : utc_date option; (** End date-time of the vacation period *)
1160 subject : string option; (** Subject line for the vacation response *)
1161 text_body : string option; (** Plain text body for the vacation response *)
1162 html_body : string option; (** HTML body for the vacation response *)
1163 }
1164
1165 (** VacationResponse/set response as defined in RFC8621 Section 7.3.
1166 Reports the results of vacation response changes.
1167 @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
1168 *)
1169 type vacation_response_set_response = {
1170 account_id : id; (** The account that was modified *)
1171 old_state : string option; (** The state before processing, if changed *)
1172 new_state : string; (** The current state on the server *)
1173 updated : id list option; (** List of IDs that were successfully updated *)
1174 not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
1175 }
1176
1177 (** {1:message_flags Message Flags and Mailbox Attributes}
1178 Message flag types as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02
1179 @see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute>
1180 *)
1181
1182 (** Flag color defined by the combination of MailFlagBit0, MailFlagBit1, and MailFlagBit2 keywords
1183 as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 3.
1184 @see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-3>
1185 *)
1186 type flag_color =
1187 | Red (** Bit pattern 000 - default color *)
1188 | Orange (** Bit pattern 100 - MailFlagBit2 set *)
1189 | Yellow (** Bit pattern 010 - MailFlagBit1 set *)
1190 | Green (** Bit pattern 111 - all bits set *)
1191 | Blue (** Bit pattern 001 - MailFlagBit0 set *)
1192 | Purple (** Bit pattern 101 - MailFlagBit2 and MailFlagBit0 set *)
1193 | Gray (** Bit pattern 011 - MailFlagBit1 and MailFlagBit0 set *)
1194
1195 (** Standard message keywords as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 4.1.
1196 These are standardized keywords that can be applied to email messages.
1197 @see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-4.1>
1198 *)
1199 type message_keyword =
1200 | Notify (** Indicate a notification should be shown for this message *)
1201 | Muted (** User is not interested in future replies to this thread *)
1202 | Followed (** User is particularly interested in future replies to this thread *)
1203 | Memo (** Message is a note-to-self about another message in the same thread *)
1204 | HasMemo (** Message has an associated memo with the $memo keyword *)
1205 | HasAttachment (** Message has an attachment *)
1206 | HasNoAttachment (** Message does not have an attachment *)
1207 | AutoSent (** Message was sent automatically as a response due to a user rule *)
1208 | Unsubscribed (** User has unsubscribed from the thread this message is in *)
1209 | CanUnsubscribe (** Message has an RFC8058-compliant List-Unsubscribe header *)
1210 | Imported (** Message was imported from another mailbox *)
1211 | IsTrusted (** Server has verified authenticity of the from name and email *)
1212 | MaskedEmail (** Message was received via an alias created for an individual sender *)
1213 | New (** Message should be made more prominent due to a recent action *)
1214 | MailFlagBit0 (** Bit 0 of the 3-bit flag color pattern *)
1215 | MailFlagBit1 (** Bit 1 of the 3-bit flag color pattern *)
1216 | MailFlagBit2 (** Bit 2 of the 3-bit flag color pattern *)
1217 | OtherKeyword of string (** Other non-standard keywords *)
1218
1219 (** Special mailbox attribute names as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 4.2.
1220 These are standardized attributes for special-purpose mailboxes.
1221 @see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-4.2>
1222 *)
1223 type mailbox_attribute =
1224 | Snoozed (** Mailbox containing messages that have been snoozed *)
1225 | Scheduled (** Mailbox containing messages scheduled to be sent later *)
1226 | Memos (** Mailbox containing messages with the $memo keyword *)
1227 | OtherAttribute of string (** Other non-standard mailbox attributes *)
1228
1229 (** Convert bit values to a flag color
1230 @param bit0 Value of bit 0 (least significant bit)
1231 @param bit1 Value of bit 1
1232 @param bit2 Value of bit 2 (most significant bit)
1233 @return The corresponding flag color
1234 *)
1235 val flag_color_of_bits : bool -> bool -> bool -> flag_color
1236
1237 (** Get the bit values for a flag color
1238 @param color The flag color
1239 @return Tuple of (bit2, bit1, bit0) values
1240 *)
1241 val bits_of_flag_color : flag_color -> bool * bool * bool
1242
1243 (** Check if a message has a flag color based on its keywords
1244 @param keywords The list of keywords for the message
1245 @return True if the message has one or more flag color bits set
1246 *)
1247 val has_flag_color : (keyword * bool) list -> bool
1248
1249 (** Get the flag color from a message's keywords, if present
1250 @param keywords The list of keywords for the message
1251 @return The flag color if all required bits are present, None otherwise
1252 *)
1253 val get_flag_color : (keyword * bool) list -> flag_color option
1254
1255 (** Convert a message keyword to its string representation
1256 @param keyword The message keyword
1257 @return String representation with $ prefix (e.g., "$notify")
1258 *)
1259 val string_of_message_keyword : message_keyword -> string
1260
1261 (** Parse a string into a message keyword
1262 @param s The string to parse (with or without $ prefix)
1263 @return The corresponding message keyword
1264 *)
1265 val message_keyword_of_string : string -> message_keyword
1266
1267 (** Convert a mailbox attribute to its string representation
1268 @param attr The mailbox attribute
1269 @return String representation with $ prefix (e.g., "$snoozed")
1270 *)
1271 val string_of_mailbox_attribute : mailbox_attribute -> string
1272
1273 (** Parse a string into a mailbox attribute
1274 @param s The string to parse (with or without $ prefix)
1275 @return The corresponding mailbox attribute
1276 *)
1277 val mailbox_attribute_of_string : string -> mailbox_attribute
1278
1279 (** Get a human-readable representation of a flag color
1280 @param color The flag color
1281 @return Human-readable name of the color
1282 *)
1283 val human_readable_flag_color : flag_color -> string
1284
1285 (** Get a human-readable representation of a message keyword
1286 @param keyword The message keyword
1287 @return Human-readable description of the keyword
1288 *)
1289 val human_readable_message_keyword : message_keyword -> string
1290
1291 (** Format email keywords into a human-readable string representation
1292 @param keywords The list of keywords and their values
1293 @return Human-readable comma-separated list of keywords
1294 *)
1295 val format_email_keywords : (keyword * bool) list -> string
1296end
1297
1298(** {1 JSON serialization}
1299 Functions for serializing and deserializing JMAP Mail objects to/from JSON
1300*)
1301
1302module Json : sig
1303 open Types
1304
1305 (** {2 Helper functions for serialization}
1306 Utility functions for converting between OCaml types and JSON representation
1307 *)
1308
1309 (** Convert a mailbox role to its string representation
1310 @param role The mailbox role
1311 @return String representation (e.g., "inbox", "drafts", etc.)
1312 *)
1313 val string_of_mailbox_role : mailbox_role -> string
1314
1315 (** Parse a string into a mailbox role
1316 @param s The string to parse
1317 @return The corresponding mailbox role, or Unknown if not recognized
1318 *)
1319 val mailbox_role_of_string : string -> mailbox_role
1320
1321 (** Convert an email keyword to its string representation
1322 @param keyword The email keyword
1323 @return String representation with $ prefix (e.g., "$flagged")
1324 *)
1325 val string_of_keyword : keyword -> string
1326
1327 (** Parse a string into an email keyword
1328 @param s The string to parse (with or without $ prefix)
1329 @return The corresponding email keyword
1330 *)
1331 val keyword_of_string : string -> keyword
1332
1333 (** {2 Mailbox serialization}
1334 Functions for serializing and deserializing mailbox objects
1335 *)
1336
1337 (** TODO:claude - Need to implement all JSON serialization functions
1338 for each type we've defined. This would be a substantial amount of
1339 code and likely require additional understanding of the ezjsonm API.
1340
1341 The interface would include functions like:
1342
1343 val mailbox_to_json : mailbox -> Ezjsonm.value
1344 val mailbox_of_json : Ezjsonm.value -> mailbox result
1345
1346 And similarly for all other types.
1347 *)
1348end
1349
1350(** {1 API functions}
1351 High-level functions for interacting with JMAP Mail servers
1352*)
1353
1354(** Authentication credentials for a JMAP server *)
1355type credentials = {
1356 username: string; (** Username for authentication *)
1357 password: string; (** Password for authentication *)
1358}
1359
1360(** Connection to a JMAP mail server *)
1361type connection = {
1362 session: Jmap.Types.session; (** Session information from the server *)
1363 config: Jmap.Api.config; (** Configuration for API requests *)
1364}
1365
1366(** Login to a JMAP server and establish a connection
1367 @param uri The URI of the JMAP server
1368 @param credentials Authentication credentials
1369 @return A connection object if successful
1370
1371 Creates a new connection to a JMAP server using username/password authentication.
1372*)
1373val login :
1374 uri:string ->
1375 credentials:credentials ->
1376 (connection, Jmap.Api.error) result Lwt.t
1377
1378(** Login to a JMAP server using an API token
1379 @param uri The URI of the JMAP server
1380 @param api_token The API token for authentication
1381 @return A connection object if successful
1382
1383 Creates a new connection to a JMAP server using Bearer token authentication.
1384*)
1385val login_with_token :
1386 uri:string ->
1387 api_token:string ->
1388 (connection, Jmap.Api.error) result Lwt.t
1389
1390(** Get all mailboxes for an account
1391 @param conn The JMAP connection
1392 @param account_id The account ID to get mailboxes for
1393 @return A list of mailboxes if successful
1394
1395 Retrieves all mailboxes (folders) in the specified account.
1396*)
1397val get_mailboxes :
1398 connection ->
1399 account_id:Jmap.Types.id ->
1400 (Types.mailbox list, Jmap.Api.error) result Lwt.t
1401
1402(** Get a specific mailbox by ID
1403 @param conn The JMAP connection
1404 @param account_id The account ID
1405 @param mailbox_id The mailbox ID to retrieve
1406 @return The mailbox if found
1407
1408 Retrieves a single mailbox by its ID.
1409*)
1410val get_mailbox :
1411 connection ->
1412 account_id:Jmap.Types.id ->
1413 mailbox_id:Jmap.Types.id ->
1414 (Types.mailbox, Jmap.Api.error) result Lwt.t
1415
1416(** Get messages in a mailbox
1417 @param conn The JMAP connection
1418 @param account_id The account ID
1419 @param mailbox_id The mailbox ID to get messages from
1420 @param limit Optional limit on number of messages to return
1421 @return The list of email messages if successful
1422
1423 Retrieves email messages in the specified mailbox, with optional limit.
1424*)
1425val get_messages_in_mailbox :
1426 connection ->
1427 account_id:Jmap.Types.id ->
1428 mailbox_id:Jmap.Types.id ->
1429 ?limit:int ->
1430 unit ->
1431 (Types.email list, Jmap.Api.error) result Lwt.t
1432
1433(** Get a single email message by ID
1434 @param conn The JMAP connection
1435 @param account_id The account ID
1436 @param email_id The email ID to retrieve
1437 @return The email message if found
1438
1439 Retrieves a single email message by its ID.
1440*)
1441val get_email :
1442 connection ->
1443 account_id:Jmap.Types.id ->
1444 email_id:Jmap.Types.id ->
1445 (Types.email, Jmap.Api.error) result Lwt.t
1446
1447(** Check if an email has a specific message keyword
1448 @param email The email to check
1449 @param keyword The message keyword to look for
1450 @return true if the email has the keyword, false otherwise
1451
1452 Tests whether an email has a particular keyword (flag) set.
1453*)
1454val has_message_keyword :
1455 Types.email ->
1456 Types.message_keyword ->
1457 bool
1458
1459(** Add a message keyword to an email
1460 @param conn The JMAP connection
1461 @param account_id The account ID
1462 @param email_id The email ID
1463 @param keyword The message keyword to add
1464 @return Success or error
1465
1466 Adds a keyword (flag) to an email message.
1467*)
1468val add_message_keyword :
1469 connection ->
1470 account_id:Jmap.Types.id ->
1471 email_id:Jmap.Types.id ->
1472 keyword:Types.message_keyword ->
1473 (unit, Jmap.Api.error) result Lwt.t
1474
1475(** Set a flag color for an email
1476 @param conn The JMAP connection
1477 @param account_id The account ID
1478 @param email_id The email ID
1479 @param color The flag color to set
1480 @return Success or error
1481
1482 Sets a flag color on an email message by setting the appropriate bit flags.
1483*)
1484val set_flag_color :
1485 connection ->
1486 account_id:Jmap.Types.id ->
1487 email_id:Jmap.Types.id ->
1488 color:Types.flag_color ->
1489 (unit, Jmap.Api.error) result Lwt.t
1490
1491(** Convert an email's keywords to typed message_keyword list
1492 @param email The email to analyze
1493 @return List of message keywords
1494
1495 Extracts all message keywords from an email's keyword list.
1496*)
1497val get_message_keywords :
1498 Types.email ->
1499 Types.message_keyword list
1500
1501(** Get emails with a specific message keyword
1502 @param conn The JMAP connection
1503 @param account_id The account ID
1504 @param keyword The message keyword to search for
1505 @param limit Optional limit on number of emails to return
1506 @return List of emails with the keyword if successful
1507
1508 Retrieves all emails that have a specific keyword (flag) set.
1509*)
1510val get_emails_with_keyword :
1511 connection ->
1512 account_id:Jmap.Types.id ->
1513 keyword:Types.message_keyword ->
1514 ?limit:int ->
1515 unit ->
1516 (Types.email list, Jmap.Api.error) result Lwt.t
1517
1518(** {1 Email Address Utilities}
1519 Utilities for working with email addresses
1520*)
1521
1522(** Check if an email address matches a filter string
1523 @param email The email address to check
1524 @param pattern The filter pattern to match against
1525 @return True if the email address matches the filter
1526
1527 The filter supports simple wildcards:
1528 - "*" matches any sequence of characters
1529 - "?" matches any single character
1530 - Case-insensitive matching is used
1531 - If no wildcards are present, substring matching is used
1532*)
1533val email_address_matches : string -> string -> bool
1534
1535(** Check if an email matches a sender filter
1536 @param email The email object to check
1537 @param pattern The sender filter pattern
1538 @return True if any sender address matches the filter
1539
1540 Tests whether any of an email's sender addresses match the provided pattern.
1541*)
1542val email_matches_sender : Types.email -> string -> bool