My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** High-level email submission API for JMAP clients.
2
3 Note: The 'context' type parameter should be Jmap_unix.context when using
4 this module through the Jmap_unix interface.
5
6 This module provides ergonomic functions for submitting emails via JMAP,
7 including creating submissions, managing envelopes, and tracking delivery status.
8
9 Inspired by the rust-jmap API design for familiarity and ease of use.
10
11 Example usage:
12 {[
13 (* Simple email submission *)
14 let result = Email_submission.submit_email env ctx
15 ~email_id ~identity_id in
16
17 (* Submit with custom envelope *)
18 let result = Email_submission.submit_email_with_envelope env ctx
19 ~email_id ~identity_id
20 ~mail_from:"sender@example.com"
21 ~rcpt_to:["recipient@example.com"] in
22
23 (* Cancel a pending submission *)
24 let result = Email_submission.cancel_submission env ctx
25 ~submission_id in
26 ]}
27*)
28
29(** Result type alias for cleaner signatures *)
30type 'a result = ('a, Jmap.Error.error) Result.t
31
32(** {1 Email Submission Creation} *)
33
34(** Submit an email with minimal configuration.
35
36 Creates an EmailSubmission for the specified email using the given identity.
37 The email will be sent immediately unless the server applies scheduling rules.
38
39 @param env Eio environment for network operations
40 @param ctx Connection context
41 @param email_id The ID of the email to submit
42 @param identity_id The identity to use for sending
43 @return The created EmailSubmission object or an error
44
45 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)
46val submit_email :
47 < net : 'a Eio.Net.t ; .. > ->
48 'context ->
49 email_id:Jmap.Id.t ->
50 identity_id:Jmap.Id.t ->
51 Jmap_email.Submission.t result
52
53(** Submit an email with a custom SMTP envelope.
54
55 Creates an EmailSubmission with explicit SMTP envelope addresses,
56 overriding the addresses derived from the email headers. This is useful
57 for scenarios like:
58 - Sending to undisclosed recipients
59 - Implementing mailing lists
60 - Testing email delivery
61
62 @param env Eio environment for network operations
63 @param ctx Connection context
64 @param email_id The ID of the email to submit
65 @param identity_id The identity to use for sending
66 @param mail_from SMTP MAIL FROM address
67 @param rcpt_to List of SMTP RCPT TO addresses
68 @return The created EmailSubmission object or an error
69
70 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)
71val submit_email_with_envelope :
72 < net : 'a Eio.Net.t ; .. > ->
73 'context ->
74 email_id:Jmap.Id.t ->
75 identity_id:Jmap.Id.t ->
76 mail_from:string ->
77 rcpt_to:string list ->
78 Jmap_email.Submission.t result
79
80(** Submit an email and automatically destroy the draft.
81
82 Creates an EmailSubmission and marks the original email for destruction
83 upon successful submission. This is the typical workflow for sending
84 draft emails, ensuring the draft is removed from the drafts folder
85 after being sent.
86
87 @param env Eio environment for network operations
88 @param ctx Connection context
89 @param email_id The ID of the draft email to submit and destroy
90 @param identity_id The identity to use for sending
91 @return The created EmailSubmission object or an error
92
93 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)
94val submit_and_destroy_draft :
95 < net : 'a Eio.Net.t ; .. > ->
96 'context ->
97 email_id:Jmap.Id.t ->
98 identity_id:Jmap.Id.t ->
99 Jmap_email.Submission.t result
100
101(** {1 Submission Status Management} *)
102
103(** Cancel a pending email submission.
104
105 Changes the undo status of a pending submission to 'canceled',
106 preventing it from being sent. This operation only succeeds if:
107 - The submission exists
108 - The submission has undoStatus = 'pending'
109 - The server still allows cancellation
110
111 Common use cases:
112 - User clicked "Undo Send" after submission
113 - Batch processing found an error
114 - User changed their mind before final delivery
115
116 @param env Eio environment for network operations
117 @param ctx Connection context
118 @param submission_id The ID of the submission to cancel
119 @return Unit on success or an error
120
121 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.4> RFC 8621, Section 7.4 *)
122val cancel_submission :
123 < net : 'a Eio.Net.t ; .. > ->
124 'context ->
125 submission_id:Jmap.Id.t ->
126 unit result
127
128(** {1 Submission Queries} *)
129
130(** Get an email submission by ID.
131
132 Retrieves a single EmailSubmission object with all or specified properties.
133 Use this to check the current status of a submission, including:
134 - Undo status (pending/final/canceled)
135 - Delivery status per recipient
136 - DSN/MDN blob IDs for delivery/read receipts
137
138 @param env Eio environment for network operations
139 @param ctx Connection context
140 @param submission_id The ID of the submission to retrieve
141 @param properties Optional list of property names to fetch (None for all)
142 @return Some submission if found, None if not found, or an error
143
144 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.1> RFC 8621, Section 7.1 *)
145val get_submission :
146 < net : 'a Eio.Net.t ; .. > ->
147 'context ->
148 submission_id:Jmap.Id.t ->
149 ?properties:string list ->
150 unit ->
151 Jmap_email.Submission.t option result
152
153(** Query email submissions with filters.
154
155 Searches for EmailSubmission objects matching the specified criteria.
156 This is useful for:
157 - Finding all submissions in a date range
158 - Listing submissions for specific emails
159 - Monitoring submission queue status
160
161 @param env Eio environment for network operations
162 @param ctx Connection context
163 @param filter Optional filter to apply (e.g., by status, email, date)
164 @param sort Optional sort order (e.g., by sendAt date)
165 @param limit Maximum number of results to return
166 @return List of submission IDs matching the query
167
168 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.3> RFC 8621, Section 7.3 *)
169val query_submissions :
170 < net : 'a Eio.Net.t ; .. > ->
171 'context ->
172 ?filter:Jmap.Methods.Filter.t ->
173 ?sort:Jmap.Methods.Comparator.t list ->
174 ?limit:Jmap.UInt.t ->
175 unit ->
176 Jmap.Id.t list result
177
178(** Query for pending submissions.
179
180 Convenience function to find all submissions that can still be cancelled.
181 This returns submissions with undoStatus = 'pending'.
182
183 @param env Eio environment for network operations
184 @param ctx Connection context
185 @return List of pending submission IDs *)
186val query_pending_submissions :
187 < net : 'a Eio.Net.t ; .. > ->
188 'context ->
189 Jmap.Id.t list result
190
191(** Query submissions for a specific email.
192
193 Finds all submissions associated with a particular email ID.
194 Useful for tracking the submission history of an email.
195
196 @param env Eio environment for network operations
197 @param ctx Connection context
198 @param email_id The email ID to search for
199 @return List of submission IDs for the email *)
200val query_submissions_for_email :
201 < net : 'a Eio.Net.t ; .. > ->
202 'context ->
203 email_id:Jmap.Id.t ->
204 Jmap.Id.t list result
205
206(** {1 Delivery Status} *)
207
208(** Check delivery status of a submission.
209
210 Retrieves the current delivery status for all recipients of a submission.
211 The returned hashtable maps recipient email addresses to their delivery
212 status, including:
213 - SMTP response from the receiving server
214 - Delivery outcome (queued/yes/no/unknown)
215 - Display status from MDN (yes/unknown)
216
217 @param env Eio environment for network operations
218 @param ctx Connection context
219 @param submission_id The submission to check
220 @return Some hashtable of recipient to status if submission exists, None otherwise
221
222 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)
223val get_delivery_status :
224 < net : 'a Eio.Net.t ; .. > ->
225 'context ->
226 submission_id:Jmap.Id.t ->
227 (string, Jmap_email.Submission.DeliveryStatus.t) Hashtbl.t option result
228
229(** {1 Batch Operations} *)
230
231(** Cancel all pending submissions.
232
233 Queries for all pending submissions and attempts to cancel each one.
234 This is useful for:
235 - Emergency stop of outgoing mail
236 - Cleanup during testing
237 - Account suspension scenarios
238
239 Note: Some submissions may fail to cancel if they've already
240 transitioned to 'final' status between the query and cancel operations.
241
242 @param env Eio environment for network operations
243 @param ctx Connection context
244 @return Number of submissions successfully cancelled
245
246 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.4> RFC 8621, Section 7.4 *)
247val cancel_all_pending :
248 < net : 'a Eio.Net.t ; .. > ->
249 'context ->
250 int result