My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** JMAP Email Submission types and operations.
2
3 This module implements the JMAP EmailSubmission data type as specified in
4 RFC 8621 Section 7. EmailSubmission objects represent email messages that
5 are being sent or have been sent through the JMAP server's submission system.
6
7 EmailSubmission provides a way to track the sending process, including
8 delivery status, undo capabilities (before final sending), and integration
9 with SMTP delivery status notifications (DSNs) and message disposition
10 notifications (MDNs).
11
12 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7: EmailSubmission
13*)
14
15(** {1 Supporting Types} *)
16
17(** SMTP envelope address representation.
18
19 Represents an email address as used in the SMTP envelope (MAIL FROM
20 and RCPT TO commands). Includes the email address and optional SMTP
21 parameters that may be needed for delivery.
22
23 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)
24module EnvelopeAddress : sig
25
26 (** Envelope address type *)
27 type t
28
29 (** JSON serialization interface *)
30 include Jmap_sigs.JSONABLE with type t := t
31
32 (** Get the email address for SMTP envelope.
33 @param address The envelope address object
34 @return Email address for SMTP envelope *)
35 val email : t -> string
36
37 (** Get the optional SMTP parameters.
38 @param address The envelope address object
39 @return Optional SMTP parameters *)
40 val parameters : t -> (string, Yojson.Safe.t) Hashtbl.t option
41
42 (** Create an envelope address.
43 @param email Email address for SMTP envelope
44 @param parameters Optional SMTP parameters
45 @return Ok with address object, or Error with validation message *)
46 val create :
47 email:string ->
48 ?parameters:(string, Yojson.Safe.t) Hashtbl.t ->
49 unit -> (t, string) result
50end
51
52(** SMTP envelope information.
53
54 Contains the SMTP envelope data (MAIL FROM and RCPT TO) that will be
55 used for message delivery. This overrides the addresses derived from
56 the email headers and allows for different envelope routing.
57
58 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)
59module Envelope : sig
60
61 (** SMTP envelope type *)
62 type t
63
64 (** JSON serialization interface *)
65 include Jmap_sigs.JSONABLE with type t := t
66
67 (** Get the SMTP MAIL FROM address.
68 @param envelope The envelope object
69 @return SMTP MAIL FROM address *)
70 val mail_from : t -> EnvelopeAddress.t
71
72 (** Get the SMTP RCPT TO addresses.
73 @param envelope The envelope object
74 @return SMTP RCPT TO addresses *)
75 val rcpt_to : t -> EnvelopeAddress.t list
76
77 (** Create an SMTP envelope.
78 @param mail_from SMTP MAIL FROM address
79 @param rcpt_to SMTP RCPT TO addresses
80 @return Ok with envelope object, or Error with validation message *)
81 val create :
82 mail_from:EnvelopeAddress.t ->
83 rcpt_to:EnvelopeAddress.t list ->
84 (t, string) result
85end
86
87(** Delivery status information for a recipient.
88
89 Contains information about the delivery attempt for a specific recipient,
90 including SMTP response codes and current delivery/display status.
91 Updated by the server as delivery progresses.
92
93 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)
94module DeliveryStatus : sig
95
96 (** Delivery status type *)
97 type t
98
99 (** JSON serialization interface *)
100 include Jmap_sigs.JSONABLE with type t := t
101
102 (** Get the SMTP server response message.
103 @param status The delivery status object
104 @return SMTP server response message *)
105 val smtp_reply : t -> string
106
107 (** Get the delivery attempt status.
108 @param status The delivery status object
109 @return Delivery attempt status *)
110 val delivered : t -> [`Queued | `Yes | `No | `Unknown]
111
112 (** Get the message display status (from MDN).
113 @param status The delivery status object
114 @return Message display status (from MDN) *)
115 val displayed : t -> [`Yes | `Unknown]
116
117 (** Create a delivery status.
118 @param smtp_reply SMTP server response message
119 @param delivered Delivery attempt status
120 @param displayed Message display status (from MDN)
121 @return Ok with status object, or Error with validation message *)
122 val create :
123 smtp_reply:string ->
124 delivered:[`Queued | `Yes | `No | `Unknown] ->
125 displayed:[`Yes | `Unknown] ->
126 (t, string) result
127end
128
129(** {1 Main EmailSubmission Type} *)
130
131(** Main EmailSubmission object representation as defined in
132 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-7}RFC 8621 Section 7}.
133
134 Represents a complete EmailSubmission with all properties including
135 server-computed fields. EmailSubmission objects track the sending
136 process for individual email messages. *)
137type t
138
139(** Alias for the main EmailSubmission type for use in submodules *)
140type email_submission_t = t
141
142(** JSON serialization interface *)
143include Jmap_sigs.JSONABLE with type t := t
144
145(** Printable formatting interface *)
146include Jmap_sigs.PRINTABLE with type t := t
147
148(** JMAP object interface for property-based operations *)
149include Jmap_sigs.JMAP_OBJECT with type t := t and type id_type := string
150
151(** {1 Property Accessors} *)
152
153(** Get the server-assigned submission identifier.
154 @param submission The email submission object
155 @return Immutable server-assigned submission ID *)
156val id : t -> Jmap.Id.t option
157
158(** Get the identity used for sending this email.
159 @param submission The email submission object
160 @return Immutable identity ID used for sending *)
161val identity_id : t -> Jmap.Id.t
162
163(** Get the email being submitted.
164 @param submission The email submission object
165 @return Immutable email ID being submitted *)
166val email_id : t -> Jmap.Id.t
167
168(** Get the thread this email belongs to.
169 @param submission The email submission object
170 @return Immutable thread ID (server-set) *)
171val thread_id : t -> Jmap.Id.t
172
173(** Get the SMTP envelope override.
174 @param submission The email submission object
175 @return Optional envelope override for SMTP delivery *)
176val envelope : t -> Envelope.t option
177
178(** Get the scheduled send time.
179 @param submission The email submission object
180 @return Immutable scheduled send time (server-set) *)
181val send_at : t -> Jmap.Date.t
182
183(** Get the current undo/cancellation status.
184 @param submission The email submission object
185 @return Current undo status *)
186val undo_status : t -> [`Pending | `Final | `Canceled]
187
188(** Get the per-recipient delivery status.
189 @param submission The email submission object
190 @return Per-recipient delivery status (server-set) *)
191val delivery_status : t -> (string, DeliveryStatus.t) Hashtbl.t option
192
193(** Get the delivery status notification blob IDs.
194 @param submission The email submission object
195 @return Delivery status notification blobs (server-set) *)
196val dsn_blob_ids : t -> Jmap.Id.t list
197
198(** Get the message disposition notification blob IDs.
199 @param submission The email submission object
200 @return Message disposition notification blobs (server-set) *)
201val mdn_blob_ids : t -> Jmap.Id.t list
202
203(** {1 Smart Constructors} *)
204
205(** Create an EmailSubmission object from all properties.
206 @param Jmap.Id.t Server-assigned submission ID
207 @param identity_id Identity used for sending
208 @param email_id Email being submitted
209 @param thread_id Thread ID (server-set)
210 @param envelope Optional SMTP envelope override
211 @param send_at Scheduled send time (server-set)
212 @param undo_status Current undo/cancellation status
213 @param delivery_status Per-recipient delivery status (server-set)
214 @param dsn_blob_ids Delivery status notification blobs (server-set)
215 @param mdn_blob_ids Message disposition notification blobs (server-set)
216 @return Ok with submission object, or Error with validation message *)
217val create :
218 id:Jmap.Id.t ->
219 identity_id:Jmap.Id.t ->
220 email_id:Jmap.Id.t ->
221 thread_id:Jmap.Id.t ->
222 ?envelope:Envelope.t ->
223 send_at:Jmap.Date.t ->
224 undo_status:[`Pending | `Final | `Canceled] ->
225 ?delivery_status:(string, DeliveryStatus.t) Hashtbl.t ->
226 ?dsn_blob_ids:Jmap.Id.t list ->
227 ?mdn_blob_ids:Jmap.Id.t list ->
228 unit -> (t, string) result
229
230(** {1 JMAP Method Operations} *)
231
232(** EmailSubmission creation parameters.
233
234 Contains only the properties that can be specified when creating a new
235 EmailSubmission. Server-computed properties (ID, thread, timestamps,
236 delivery status) are handled separately.
237
238 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)
239module Create : sig
240
241 (** EmailSubmission creation type *)
242 type t
243
244 (** JSON serialization interface *)
245 include Jmap_sigs.JSONABLE with type t := t
246
247 (** Get the identity to use for sending.
248 @param create The creation object
249 @return Identity to use for sending *)
250 val identity_id : t -> Jmap.Id.t
251
252 (** Get the email object to submit.
253 @param create The creation object
254 @return Email object to submit *)
255 val email_id : t -> Jmap.Id.t
256
257 (** Get the optional envelope override.
258 @param create The creation object
259 @return Optional envelope override *)
260 val envelope : t -> Envelope.t option
261
262 (** Create an EmailSubmission creation request.
263 @param identity_id Identity to use for sending
264 @param email_id Email object to submit
265 @param envelope Optional envelope override
266 @return Ok with creation object, or Error with validation message *)
267 val create :
268 identity_id:Jmap.Id.t ->
269 email_id:Jmap.Id.t ->
270 ?envelope:Envelope.t ->
271 unit -> (t, string) result
272
273 (** Server response for successful EmailSubmission creation.
274
275 Contains the server-computed properties for a newly created EmailSubmission,
276 including the assigned ID, thread association, and scheduled send time.
277
278 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)
279 module Response : sig
280
281 (** Creation response type *)
282 type t
283
284 (** JSON serialization interface *)
285 include Jmap_sigs.JSONABLE with type t := t
286
287 (** Get the server-assigned submission ID.
288 @param response The creation response object
289 @return Server-assigned submission ID *)
290 val id : t -> Jmap.Id.t
291
292 (** Get the thread ID the email belongs to.
293 @param response The creation response object
294 @return Thread ID the email belongs to *)
295 val thread_id : t -> Jmap.Id.t
296
297 (** Get the actual/scheduled send timestamp.
298 @param response The creation response object
299 @return Actual/scheduled send timestamp *)
300 val send_at : t -> Jmap.Date.t
301
302 (** Create a creation response.
303 @param Jmap.Id.t Server-assigned submission ID
304 @param thread_id Thread ID the email belongs to
305 @param send_at Actual/scheduled send timestamp
306 @return Ok with response object, or Error with validation message *)
307 val create :
308 id:Jmap.Id.t ->
309 thread_id:Jmap.Id.t ->
310 send_at:Jmap.Date.t ->
311 (t, string) result
312 end
313end
314
315(** EmailSubmission update operations.
316
317 EmailSubmission update patch object. Only the undoStatus property can be
318 modified, and only to cancel pending submissions (change from 'pending'
319 to 'canceled').
320
321 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.4> RFC 8621, Section 7.4 *)
322module Update : sig
323
324 (** EmailSubmission update type (patch object) *)
325 type t
326
327 (** JSON serialization interface *)
328 include Jmap_sigs.JSONABLE with type t := t
329
330 (** Create an update to cancel a pending submission.
331 @return Ok with update object to cancel submission *)
332 val cancel : (t, string) result
333
334 (** Server response for successful EmailSubmission update.
335
336 Contains any server-computed properties that may have changed as a result
337 of the update operation. Typically contains the full submission state after
338 an undo status change.
339
340 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.4> RFC 8621, Section 7.4 *)
341 module Response : sig
342
343 (** Update response type *)
344 type t
345
346 (** JSON serialization interface *)
347 include Jmap_sigs.JSONABLE with type t := t
348
349 (** Get the updated submission object.
350 @param response The update response object
351 @return Updated submission object *)
352 val submission : t -> email_submission_t
353
354 (** Create an update response.
355 @param submission Updated submission object
356 @return Ok with response object, or Error with validation message *)
357 val create :
358 submission:email_submission_t ->
359 (t, string) result
360 end
361end
362
363(** Arguments for EmailSubmission/get method.
364
365 Specialized version of the standard JMAP get arguments for retrieving
366 EmailSubmission objects with their properties.
367
368 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.1> RFC 8621, Section 7.1 *)
369module Get_args : sig
370
371 (** EmailSubmission/get arguments type *)
372 type t
373
374 (** JSON serialization interface *)
375 include Jmap_sigs.JSONABLE with type t := t
376
377 (** Create EmailSubmission get arguments.
378 @param account_id Account where objects exist
379 @param ids Specific submission IDs to retrieve (None for all)
380 @param properties Properties to include (None for all)
381 @return Ok with get arguments, or Error with validation message *)
382 val create :
383 account_id:Jmap.Id.t ->
384 ?ids:Jmap.Id.t list ->
385 ?properties:string list ->
386 unit -> (t, string) result
387end
388
389(** Response for EmailSubmission/get method.
390
391 Contains the retrieved EmailSubmission objects along with standard
392 JMAP response metadata.
393
394 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.1> RFC 8621, Section 7.1 *)
395module Get_response : sig
396
397 (** EmailSubmission/get response type *)
398 type t
399
400 (** JSON serialization interface *)
401 include Jmap_sigs.JSONABLE with type t := t
402
403 (** Get the account ID.
404 @param response The get response object
405 @return Account ID *)
406 val account_id : t -> Jmap.Id.t
407
408 (** Get the current state string.
409 @param response The get response object
410 @return Current state string *)
411 val state : t -> string
412
413 (** Get the list of retrieved submission objects.
414 @param response The get response object
415 @return List of retrieved submission objects *)
416 val list : t -> email_submission_t list
417
418 (** Get the list of submission IDs not found.
419 @param response The get response object
420 @return List of submission IDs not found *)
421 val not_found : t -> Jmap.Id.t list
422end
423
424(** Arguments for EmailSubmission/changes method.
425
426 Used to track changes to EmailSubmission objects since a previous state,
427 typically to update delivery status or detect new submissions.
428
429 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.2> RFC 8621, Section 7.2 *)
430module Changes_args : sig
431
432 (** EmailSubmission/changes arguments type *)
433 type t
434
435 (** JSON serialization interface *)
436 include Jmap_sigs.JSONABLE with type t := t
437
438 (** Create EmailSubmission changes arguments.
439 @param account_id Account where changes occurred
440 @param since_state Previous state to compare against
441 @param max_changes Maximum number of changes to return
442 @return Ok with changes arguments, or Error with validation message *)
443 val create :
444 account_id:Jmap.Id.t ->
445 since_state:string ->
446 ?max_changes:Jmap.UInt.t ->
447 unit -> (t, string) result
448end
449
450(** Response for EmailSubmission/changes method.
451
452 Contains lists of EmailSubmission IDs that were created, updated, or
453 destroyed since the specified state.
454
455 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.2> RFC 8621, Section 7.2 *)
456module Changes_response : sig
457
458 (** EmailSubmission/changes response type *)
459 type t
460
461 (** JSON serialization interface *)
462 include Jmap_sigs.JSONABLE with type t := t
463
464 (** Get the account ID.
465 @param response The changes response object
466 @return Account ID *)
467 val account_id : t -> Jmap.Id.t
468
469 (** Get the old state string.
470 @param response The changes response object
471 @return Old state string *)
472 val old_state : t -> string
473
474 (** Get the new state string.
475 @param response The changes response object
476 @return New state string *)
477 val new_state : t -> string
478
479 (** Get whether there are more changes available.
480 @param response The changes response object
481 @return Whether there are more changes available *)
482 val has_more_changes : t -> bool
483
484 (** Get the list of created submission IDs.
485 @param response The changes response object
486 @return List of created submission IDs *)
487 val created : t -> Jmap.Id.t list
488
489 (** Get the list of updated submission IDs.
490 @param response The changes response object
491 @return List of updated submission IDs *)
492 val updated : t -> Jmap.Id.t list
493
494 (** Get the list of destroyed submission IDs.
495 @param response The changes response object
496 @return List of destroyed submission IDs *)
497 val destroyed : t -> Jmap.Id.t list
498end
499
500(** Arguments for EmailSubmission/query method.
501
502 Used to search for EmailSubmission objects matching specific criteria,
503 with filtering, sorting, and pagination support.
504
505 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.3> RFC 8621, Section 7.3 *)
506module Query_args : sig
507
508 (** EmailSubmission/query arguments type *)
509 type t
510
511 (** JSON serialization interface *)
512 include Jmap_sigs.JSONABLE with type t := t
513
514 (** Create EmailSubmission query arguments.
515 @param account_id Account where objects exist
516 @param filter Filter conditions (None for all)
517 @param sort Sort criteria (None for default)
518 @param position Starting position for results (default: 0)
519 @param anchor Reference ID for positioning
520 @param anchor_offset Offset from anchor position
521 @param limit Maximum number of results (None for no limit)
522 @param calculate_total Whether to calculate total count
523 @return Ok with query arguments, or Error with validation message *)
524 val create :
525 account_id:Jmap.Id.t ->
526 ?filter:Jmap.Methods.Filter.t ->
527 ?sort:Jmap.Methods.Comparator.t list ->
528 ?position:Jmap.UInt.t ->
529 ?anchor:Jmap.Id.t ->
530 ?anchor_offset:int ->
531 ?limit:Jmap.UInt.t ->
532 ?calculate_total:bool ->
533 unit -> (t, string) result
534end
535
536(** Response for EmailSubmission/query method.
537
538 Contains the list of EmailSubmission IDs that match the query criteria,
539 along with position and total count information.
540
541 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.3> RFC 8621, Section 7.3 *)
542module Query_response : sig
543
544 (** EmailSubmission/query response type *)
545 type t
546
547 (** JSON serialization interface *)
548 include Jmap_sigs.JSONABLE with type t := t
549
550 (** Get the account ID.
551 @param response The query response object
552 @return Account ID *)
553 val account_id : t -> Jmap.Id.t
554
555 (** Get the query state string.
556 @param response The query response object
557 @return Query state string *)
558 val query_state : t -> string
559
560 (** Get whether the query can be calculated as an update.
561 @param response The query response object
562 @return Whether the query can be calculated as an update *)
563 val can_calculate_changes : t -> bool
564
565 (** Get the starting position of results.
566 @param response The query response object
567 @return Starting position of results *)
568 val position : t -> Jmap.UInt.t
569
570 (** Get the total number of matching objects.
571 @param response The query response object
572 @return Total number of matching objects (if calculated) *)
573 val total : t -> Jmap.UInt.t option
574
575 (** Get the list of matching submission IDs.
576 @param response The query response object
577 @return List of matching submission IDs *)
578 val ids : t -> Jmap.Id.t list
579end
580
581(** Arguments for EmailSubmission/set method.
582
583 Specialized version of the standard JMAP set arguments that includes
584 the additional onSuccessDestroyEmail parameter for automatically
585 removing draft emails after successful submission.
586
587 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)
588module Set_args : sig
589
590 (** EmailSubmission/set arguments type *)
591 type t
592
593 (** JSON serialization interface *)
594 include Jmap_sigs.JSONABLE with type t := t
595
596 (** Create EmailSubmission set arguments.
597 @param account_id Account where operations will be performed
598 @param if_in_state Conditional update based on state
599 @param create Submissions to create
600 @param update Submissions to update (cancel)
601 @param destroy Submissions to destroy
602 @param on_success_destroy_email Emails to destroy after successful submission
603 @return Ok with set arguments, or Error with validation message *)
604 val create :
605 account_id:Jmap.Id.t ->
606 ?if_in_state:string ->
607 ?create:(Jmap.Id.t * Create.t) list ->
608 ?update:(Jmap.Id.t * Update.t) list ->
609 ?destroy:Jmap.Id.t list ->
610 ?on_success_destroy_email:Jmap.Id.t list ->
611 unit -> (t, string) result
612end
613
614(** Response for EmailSubmission/set method.
615
616 Contains the results of create, update, and destroy operations on
617 EmailSubmission objects, with creation and update info specialized
618 for EmailSubmission types.
619
620 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)
621module Set_response : sig
622
623 (** EmailSubmission/set response type *)
624 type t
625
626 (** JSON serialization interface *)
627 include Jmap_sigs.JSONABLE with type t := t
628
629 (** Get the account ID.
630 @param response The set response object
631 @return Account ID *)
632 val account_id : t -> Jmap.Id.t
633
634 (** Get the old state string.
635 @param response The set response object
636 @return Old state string *)
637 val old_state : t -> string option
638
639 (** Get the new state string.
640 @param response The set response object
641 @return New state string *)
642 val new_state : t -> string
643
644 (** Get the created submissions with server-computed properties.
645 @param response The set response object
646 @return Created submissions with server-computed properties *)
647 val created : t -> (string, Create.Response.t) Hashtbl.t
648
649 (** Get the updated submissions with server-computed properties.
650 @param response The set response object
651 @return Updated submissions with server-computed properties *)
652 val updated : t -> (string, Update.Response.t) Hashtbl.t option
653
654 (** Get the destroyed submission IDs.
655 @param response The set response object
656 @return Destroyed submission IDs *)
657 val destroyed : t -> Jmap.Id.t list option
658
659 (** Get the submission IDs that could not be created.
660 @param response The set response object
661 @return Submission IDs that could not be created *)
662 val not_created : t -> (string, Jmap.Error.Set_error.t) Hashtbl.t option
663
664 (** Get the submission IDs that could not be updated.
665 @param response The set response object
666 @return Submission IDs that could not be updated *)
667 val not_updated : t -> (string, Jmap.Error.Set_error.t) Hashtbl.t option
668
669 (** Get the submission IDs that could not be destroyed.
670 @param response The set response object
671 @return Submission IDs that could not be destroyed *)
672 val not_destroyed : t -> (string, Jmap.Error.Set_error.t) Hashtbl.t option
673end
674
675(** {1 Filter Helper Functions} *)
676
677(** Helper functions for creating EmailSubmission-specific filters.
678
679 These functions provide convenient ways to create filters for common
680 EmailSubmission query patterns, following the standard JMAP filter syntax.
681
682 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.3> RFC 8621, Section 7.3 *)
683module Filter : sig
684
685 (** Create filter for specific identity IDs.
686 @param ids List of identity IDs to match
687 @return Filter that matches submissions using any of these identities *)
688 val identity_ids : Jmap.Id.t list -> Jmap.Methods.Filter.t
689
690 (** Create filter for specific email IDs.
691 @param ids List of email IDs to match
692 @return Filter that matches submissions for any of these emails *)
693 val email_ids : Jmap.Id.t list -> Jmap.Methods.Filter.t
694
695 (** Create filter for specific thread IDs.
696 @param ids List of thread IDs to match
697 @return Filter that matches submissions in any of these threads *)
698 val thread_ids : Jmap.Id.t list -> Jmap.Methods.Filter.t
699
700 (** Create filter for undo status.
701 @param status Undo status to match
702 @return Filter that matches submissions with this undo status *)
703 val undo_status : [`Pending | `Final | `Canceled] -> Jmap.Methods.Filter.t
704
705 (** Create filter for submissions sent before a specific Date.t.
706 @param Date.t UTC timestamp to compare against
707 @return Filter that matches submissions sent before this Date.t *)
708 val before : Jmap.Date.t -> Jmap.Methods.Filter.t
709
710 (** Create filter for submissions sent after a specific Date.t.
711 @param Date.t UTC timestamp to compare against
712 @return Filter that matches submissions sent after this Date.t *)
713 val after : Jmap.Date.t -> Jmap.Methods.Filter.t
714
715 (** Create filter for submissions sent within a Date.t range.
716 @param after_date Start of Date.t range
717 @param before_date End of Date.t range
718 @return Filter that matches submissions sent within this range *)
719 val date_range : after_date:Jmap.Date.t -> before_date:Jmap.Date.t -> Jmap.Methods.Filter.t
720end
721
722(** {1 Sort Helper Functions} *)
723
724(** Helper functions for creating EmailSubmission-specific sorts.
725
726 These functions provide convenient ways to create sort criteria for
727 EmailSubmission queries, following the standard JMAP comparator syntax.
728
729 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.3> RFC 8621, Section 7.3 *)
730module Sort : sig
731
732 (** Sort by sendAt, newest first.
733 @return Comparator that sorts by send time, most recent first *)
734 val send_newest_first : unit -> Jmap.Methods.Comparator.t
735
736 (** Sort by sendAt, oldest first.
737 @return Comparator that sorts by send time, oldest first *)
738 val send_oldest_first : unit -> Jmap.Methods.Comparator.t
739
740 (** Sort by identity ID.
741 @param ?ascending Sort direction (default: true for ascending)
742 @return Comparator that sorts by identity ID *)
743 val identity_id : ?ascending:bool -> unit -> Jmap.Methods.Comparator.t
744
745 (** Sort by email ID.
746 @param ?ascending Sort direction (default: true for ascending)
747 @return Comparator that sorts by email ID *)
748 val email_id : ?ascending:bool -> unit -> Jmap.Methods.Comparator.t
749
750 (** Sort by thread ID.
751 @param ?ascending Sort direction (default: true for ascending)
752 @return Comparator that sorts by thread ID *)
753 val thread_id : ?ascending:bool -> unit -> Jmap.Methods.Comparator.t
754
755 (** Sort by undo status.
756 @param ?ascending Sort direction (default: true for ascending)
757 @return Comparator that sorts by undo status *)
758 val undo_status : ?ascending:bool -> unit -> Jmap.Methods.Comparator.t
759end
760
761(** {1 Property System} *)
762
763(** EmailSubmission object property identifiers for selective retrieval.
764
765 Property identifiers for EmailSubmission objects as specified in RFC 8621 Section 7.
766 These identifiers are used in EmailSubmission/get requests to specify which properties
767 should be returned, enabling efficient partial object retrieval.
768
769 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7
770*)
771module Property : sig
772 (** EmailSubmission object property identifier type.
773
774 Polymorphic variant enumeration of all standard properties available
775 on EmailSubmission objects as defined in RFC 8621.
776 *)
777 type t = [
778 | `Id (** Server-assigned unique identifier (immutable, server-set) *)
779 | `IdentityId (** Identity to associate with submission (immutable) *)
780 | `EmailId (** Email to send (immutable) *)
781 | `ThreadId (** Thread ID of email being sent (immutable, server-set) *)
782 | `Envelope (** SMTP envelope information (immutable) *)
783 | `SendAt (** Date submission was/will be released (immutable, server-set) *)
784 | `UndoStatus (** Whether submission may be canceled *)
785 | `DeliveryStatus (** Per-recipient delivery status (server-set) *)
786 | `DsnBlobIds (** Delivery Status Notification blob IDs (server-set) *)
787 | `MdnBlobIds (** Message Disposition Notification blob IDs (server-set) *)
788 ]
789
790 (** Convert a property to its JMAP protocol string representation.
791
792 @param prop The property to convert
793 @return JMAP protocol string representation *)
794 val to_string : t -> string
795
796 (** Parse a JMAP protocol string into a property variant.
797
798 @param str The protocol string to parse
799 @return Some property if valid, None if unknown *)
800 val of_string : string -> t option
801
802 (** Get all standard EmailSubmission properties.
803
804 @return Complete list of all defined EmailSubmission properties *)
805 val all_properties : t list
806
807 (** Convert a list of properties to their string representations.
808
809 @param properties List of property variants
810 @return List of JMAP protocol strings *)
811 val to_string_list : t list -> string list
812
813 (** Parse a list of strings into property variants.
814
815 @param strings List of JMAP protocol strings
816 @return List of parsed property variants (invalid strings ignored) *)
817 val of_string_list : string list -> t list
818
819 (** Get properties commonly needed for submission tracking.
820
821 @return List of properties suitable for submission status displays *)
822 val common_properties : t list
823
824 (** Get properties for detailed submission monitoring.
825
826 @return Complete list of all properties for detailed submission views *)
827 val detailed_properties : t list
828end