anil.recoil.org
this repo has no description
Improve OCamldoc documentation in library interfaces
- Add detailed documentation for all types and functions in jmap.mli
- Add detailed documentation for all types and functions in jmap_mail.mli
- Include proper @see references with URLs to RFC sections
- Include field-level documentation for record types
- Follow OCamldoc standards with proper parameter documentation
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
+1471
-834
+447
-226
lib/jmap.mli
+447
-226
lib/jmap.mli
···
1
1
(**
2
2
* JMAP protocol implementation based on RFC8620
3
3
* https://datatracker.ietf.org/doc/html/rfc8620
4
+
*
5
+
* This module implements the core JMAP protocol as defined in RFC8620, providing
6
+
* types and functions for making JMAP API requests and handling responses.
4
7
*)
5
8
6
-
(** Initialize and configure logging for JMAP *)
9
+
(** Initialize and configure logging for JMAP
10
+
@param level Optional logging level (higher means more verbose)
11
+
@param enable_logs Whether to enable logging at all (default true)
12
+
@param redact_sensitive Whether to redact sensitive information like tokens (default true)
13
+
*)
7
14
val init_logging : ?level:int -> ?enable_logs:bool -> ?redact_sensitive:bool -> unit -> unit
8
15
9
-
(** Redact sensitive data like tokens *)
16
+
(** Redact sensitive data like authentication tokens from logs
17
+
@param redact Whether to perform redaction (default true)
18
+
@param token The token string to redact
19
+
@return A redacted version of the token (with characters replaced by '*')
20
+
*)
10
21
val redact_token : ?redact:bool -> string -> string
11
22
12
-
(** Module for managing JMAP capability URIs and other constants *)
23
+
(** Module for managing JMAP capability URIs and other constants
24
+
as defined in RFC8620 Section 1.8
25
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.8> RFC8620 Section 1.8
26
+
*)
13
27
module Capability : sig
14
-
(** JMAP capability URI as specified in RFC8620 *)
28
+
(** JMAP core capability URI as specified in RFC8620 Section 2
29
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-2> RFC8620 Section 2
30
+
*)
15
31
val core_uri : string
16
32
17
-
(** All JMAP capability types *)
33
+
(** All JMAP capability types as described in RFC8620 Section 1.8
34
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.8> RFC8620 Section 1.8
35
+
*)
18
36
type t =
19
37
| Core (** Core JMAP capability *)
20
-
| Extension of string (** Extension capabilities *)
38
+
| Extension of string (** Extension capabilities with custom URIs *)
21
39
22
-
(** Convert capability to URI string *)
40
+
(** Convert capability to URI string
41
+
@param capability The capability to convert
42
+
@return The full URI string for the capability
43
+
*)
23
44
val to_string : t -> string
24
45
25
-
(** Parse a string to a capability, returns Extension for non-core capabilities *)
46
+
(** Parse a string to a capability, returns Extension for non-core capabilities
47
+
@param uri The capability URI string to parse
48
+
@return The parsed capability type
49
+
*)
26
50
val of_string : string -> t
27
51
28
-
(** Check if a capability matches a core capability *)
52
+
(** Check if a capability matches the core capability
53
+
@param capability The capability to check
54
+
@return True if the capability is the core JMAP capability
55
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
56
+
*)
29
57
val is_core : t -> bool
30
58
31
-
(** Check if a capability string is a core capability *)
59
+
(** Check if a capability string is the core capability URI
60
+
@param uri The capability URI string to check
61
+
@return True if the string represents the core JMAP capability
62
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
63
+
*)
32
64
val is_core_string : string -> bool
33
65
34
-
(** Create a list of capability strings *)
66
+
(** Create a list of capability URI strings
67
+
@param capabilities List of capability types
68
+
@return List of capability URI strings
69
+
*)
35
70
val strings_of_capabilities : t list -> string list
36
71
end
37
72
38
-
(** {1 Types} *)
73
+
(** {1 Types}
74
+
Core types as defined in RFC8620
75
+
@see <https://datatracker.ietf.org/doc/html/rfc8620> RFC8620
76
+
*)
39
77
40
78
module Types : sig
41
-
(** Id string as per Section 1.2 *)
79
+
(** Id string as defined in RFC8620 Section 1.2.
80
+
A string of at least 1 and maximum 255 octets, case-sensitive,
81
+
and does not begin with the '#' character.
82
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.2>
83
+
*)
42
84
type id = string
43
85
44
-
(** Int bounded within the range -2^53+1 to 2^53-1 as per Section 1.3 *)
86
+
(** Int type bounded within the range -2^53+1 to 2^53-1 as defined in RFC8620 Section 1.3.
87
+
Represented as JSON number where the value MUST be an integer and in the range.
88
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.3>
89
+
*)
45
90
type int_t = int
46
91
47
-
(** UnsignedInt bounded within the range 0 to 2^53-1 as per Section 1.3 *)
92
+
(** UnsignedInt bounded within the range 0 to 2^53-1 as defined in RFC8620 Section 1.3.
93
+
Represented as JSON number where the value MUST be a non-negative integer and in the range.
94
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.3>
95
+
*)
48
96
type unsigned_int = int
49
97
50
-
(** Date string in RFC3339 format as per Section 1.4 *)
98
+
(** Date string in RFC3339 format as defined in RFC8620 Section 1.4.
99
+
Includes date, time and time zone offset information or UTC.
100
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.4>
101
+
*)
51
102
type date = string
52
103
53
-
(** UTCDate is a Date with 'Z' time zone as per Section 1.4 *)
104
+
(** UTCDate is a Date with 'Z' time zone (UTC) as defined in RFC8620 Section 1.4.
105
+
Same format as Date type but always with UTC time zone (Z).
106
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.4>
107
+
*)
54
108
type utc_date = string
55
109
56
-
(** Error object as per Section 3.6.2 *)
110
+
(** Error object as defined in RFC8620 Section 3.6.2.
111
+
Used to represent standard error conditions in method responses.
112
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.6.2>
113
+
*)
57
114
type error = {
58
-
type_: string;
59
-
description: string option;
115
+
type_: string; (** The type of error, e.g., "serverFail" *)
116
+
description: string option; (** Optional human-readable description of the error *)
60
117
}
61
118
62
-
(** Set error object as per Section 5.3 *)
119
+
(** Set error object as defined in RFC8620 Section 5.3.
120
+
Used for reporting errors in set operations.
121
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
122
+
*)
63
123
type set_error = {
64
-
type_: string;
65
-
description: string option;
66
-
properties: string list option;
67
-
(* Additional properties for specific error types *)
68
-
existing_id: id option; (* For alreadyExists error *)
124
+
type_: string; (** The type of error, e.g., "notFound" *)
125
+
description: string option; (** Optional human-readable description of the error *)
126
+
properties: string list option; (** Properties causing the error, if applicable *)
127
+
existing_id: id option; (** For "alreadyExists" error, the ID of the existing object *)
69
128
}
70
129
71
-
(** Invocation object as per Section 3.2 *)
130
+
(** Invocation object as defined in RFC8620 Section 3.2.
131
+
Represents a method call in the JMAP protocol.
132
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.2>
133
+
*)
72
134
type 'a invocation = {
73
-
name: string;
74
-
arguments: 'a;
75
-
method_call_id: string;
135
+
name: string; (** The name of the method to call, e.g., "Mailbox/get" *)
136
+
arguments: 'a; (** The arguments for the method, type varies by method *)
137
+
method_call_id: string; (** Client-specified ID for referencing this call *)
76
138
}
77
139
78
-
(** ResultReference object as per Section 3.7 *)
140
+
(** ResultReference object as defined in RFC8620 Section 3.7.
141
+
Used to reference results from previous method calls.
142
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
143
+
*)
79
144
type result_reference = {
80
-
result_of: string;
81
-
name: string;
82
-
path: string;
145
+
result_of: string; (** The method_call_id of the method to reference *)
146
+
name: string; (** Name of the response in the referenced result *)
147
+
path: string; (** JSON pointer path to the value being referenced *)
83
148
}
84
149
85
-
(** FilterOperator, FilterCondition and Filter as per Section 5.5 *)
150
+
(** FilterOperator, FilterCondition and Filter as defined in RFC8620 Section 5.5.
151
+
Used for complex filtering in query methods.
152
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
153
+
*)
86
154
type filter_operator = {
87
-
operator: string; (* "AND", "OR", "NOT" *)
88
-
conditions: filter list;
155
+
operator: string; (** The operator: "AND", "OR", "NOT" *)
156
+
conditions: filter list; (** The conditions to apply the operator to *)
89
157
}
90
-
and filter_condition = (string * Ezjsonm.value) list
158
+
159
+
(** Property/value pairs for filtering *)
160
+
and filter_condition =
161
+
(string * Ezjsonm.value) list
162
+
91
163
and filter =
92
-
| Operator of filter_operator
93
-
| Condition of filter_condition
164
+
| Operator of filter_operator (** Logical operator combining conditions *)
165
+
| Condition of filter_condition (** Simple property-based condition *)
94
166
95
-
(** Comparator object for sorting as per Section 5.5 *)
167
+
(** Comparator object for sorting as defined in RFC8620 Section 5.5.
168
+
Specifies how to sort query results.
169
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
170
+
*)
96
171
type comparator = {
97
-
property: string;
98
-
is_ascending: bool option; (* Optional, defaults to true *)
99
-
collation: string option; (* Optional, server-dependent default *)
172
+
property: string; (** The property to sort by *)
173
+
is_ascending: bool option; (** Sort order (true for ascending, false for descending) *)
174
+
collation: string option; (** Collation algorithm for string comparison *)
100
175
}
101
176
102
-
(** PatchObject as per Section 5.3 *)
103
-
type patch_object = (string * Ezjsonm.value) list
177
+
(** PatchObject as defined in RFC8620 Section 5.3.
178
+
Used to represent a set of updates to apply to an object.
179
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
180
+
*)
181
+
type patch_object = (string * Ezjsonm.value) list (** List of property/value pairs to update *)
104
182
105
-
(** AddedItem structure as per Section 5.6 *)
183
+
(** AddedItem structure as defined in RFC8620 Section 5.6.
184
+
Represents an item added to a query result.
185
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
186
+
*)
106
187
type added_item = {
107
-
id: id;
108
-
index: unsigned_int;
188
+
id: id; (** The ID of the added item *)
189
+
index: unsigned_int; (** The index in the result list where the item appears *)
109
190
}
110
191
111
-
(** Account object as per Section 1.6.2 *)
192
+
(** Account object as defined in RFC8620 Section 1.6.2.
193
+
Represents a user account in JMAP.
194
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.6.2>
195
+
*)
112
196
type account = {
113
-
name: string;
114
-
is_personal: bool;
115
-
is_read_only: bool;
116
-
account_capabilities: (string * Ezjsonm.value) list;
197
+
name: string; (** User-friendly account name, e.g. "john@example.com" *)
198
+
is_personal: bool; (** Whether this account belongs to the authenticated user *)
199
+
is_read_only: bool; (** Whether this account can be modified *)
200
+
account_capabilities: (string * Ezjsonm.value) list; (** Capabilities available for this account *)
117
201
}
118
202
119
-
(** Core capability object as per Section 2 *)
203
+
(** Core capability object as defined in RFC8620 Section 2.
204
+
Describes limits and features of the JMAP server.
205
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
206
+
*)
120
207
type core_capability = {
121
-
max_size_upload: unsigned_int;
122
-
max_concurrent_upload: unsigned_int;
123
-
max_size_request: unsigned_int;
124
-
max_concurrent_requests: unsigned_int;
125
-
max_calls_in_request: unsigned_int;
126
-
max_objects_in_get: unsigned_int;
127
-
max_objects_in_set: unsigned_int;
128
-
collation_algorithms: string list;
208
+
max_size_upload: unsigned_int; (** Maximum file size in octets for uploads *)
209
+
max_concurrent_upload: unsigned_int; (** Maximum number of concurrent uploads *)
210
+
max_size_request: unsigned_int; (** Maximum size in octets for a request *)
211
+
max_concurrent_requests: unsigned_int; (** Maximum number of concurrent requests *)
212
+
max_calls_in_request: unsigned_int; (** Maximum number of method calls in a request *)
213
+
max_objects_in_get: unsigned_int; (** Maximum number of objects in a get request *)
214
+
max_objects_in_set: unsigned_int; (** Maximum number of objects in a set request *)
215
+
collation_algorithms: string list; (** Supported string collation algorithms *)
129
216
}
130
217
131
-
(** PushSubscription keys object as per Section 7.2 *)
218
+
(** PushSubscription keys object as defined in RFC8620 Section 7.2.
219
+
Contains encryption keys for web push subscriptions.
220
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2>
221
+
*)
132
222
type push_keys = {
133
-
p256dh: string;
134
-
auth: string;
223
+
p256dh: string; (** User agent public key (Base64url-encoded) *)
224
+
auth: string; (** Authentication secret (Base64url-encoded) *)
135
225
}
136
226
137
-
(** Session object as per Section 2 *)
227
+
(** Session object as defined in RFC8620 Section 2.
228
+
Contains information about the server and user's accounts.
229
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
230
+
*)
138
231
type session = {
139
-
capabilities: (string * Ezjsonm.value) list;
140
-
accounts: (id * account) list;
141
-
primary_accounts: (string * id) list;
142
-
username: string;
143
-
api_url: string;
144
-
download_url: string;
145
-
upload_url: string;
146
-
event_source_url: string option;
147
-
state: string;
232
+
capabilities: (string * Ezjsonm.value) list; (** Server capabilities with their properties *)
233
+
accounts: (id * account) list; (** Map of account IDs to account objects *)
234
+
primary_accounts: (string * id) list; (** Map of capability URIs to primary account IDs *)
235
+
username: string; (** Username associated with this session *)
236
+
api_url: string; (** URL to use for JMAP API requests *)
237
+
download_url: string; (** URL endpoint to download files *)
238
+
upload_url: string; (** URL endpoint to upload files *)
239
+
event_source_url: string option; (** URL for Server-Sent Events notifications *)
240
+
state: string; (** String representing the state on the server *)
148
241
}
149
242
150
-
(** TypeState for state changes as per Section 7.1 *)
151
-
type type_state = (string * string) list
243
+
(** TypeState for state changes as defined in RFC8620 Section 7.1.
244
+
Maps data type names to the state string for that type.
245
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.1>
246
+
*)
247
+
type type_state = (string * string) list (** (data type name, state string) pairs *)
152
248
153
-
(** StateChange object as per Section 7.1 *)
249
+
(** StateChange object as defined in RFC8620 Section 7.1.
250
+
Represents changes to data types for different accounts.
251
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.1>
252
+
*)
154
253
type state_change = {
155
-
changed: (id * type_state) list;
254
+
changed: (id * type_state) list; (** Map of account IDs to type state changes *)
156
255
}
157
256
158
-
(** PushVerification object as per Section 7.2.2 *)
257
+
(** PushVerification object as defined in RFC8620 Section 7.2.2.
258
+
Used for verifying push subscription ownership.
259
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2.2>
260
+
*)
159
261
type push_verification = {
160
-
push_subscription_id: id;
161
-
verification_code: string;
262
+
push_subscription_id: id; (** ID of the push subscription being verified *)
263
+
verification_code: string; (** Code the client must submit to verify ownership *)
162
264
}
163
265
164
-
(** PushSubscription object as per Section 7.2 *)
266
+
(** PushSubscription object as defined in RFC8620 Section 7.2.
267
+
Represents a subscription for push notifications.
268
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2>
269
+
*)
165
270
type push_subscription = {
166
-
id: id;
167
-
device_client_id: string;
168
-
url: string;
169
-
keys: push_keys option;
170
-
verification_code: string option;
171
-
expires: utc_date option;
172
-
types: string list option;
271
+
id: id; (** Server-assigned ID for the subscription *)
272
+
device_client_id: string; (** ID representing the client/device *)
273
+
url: string; (** URL to which events are pushed *)
274
+
keys: push_keys option; (** Encryption keys for web push, if any *)
275
+
verification_code: string option; (** Verification code if not yet verified *)
276
+
expires: utc_date option; (** When the subscription expires, if applicable *)
277
+
types: string list option; (** Types of changes to push, null means all *)
173
278
}
174
279
175
-
(** Request object as per Section 3.3 *)
280
+
(** Request object as defined in RFC8620 Section 3.3.
281
+
Represents a JMAP request from client to server.
282
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.3>
283
+
*)
176
284
type request = {
177
-
using: string list;
178
-
method_calls: Ezjsonm.value invocation list;
179
-
created_ids: (id * id) list option;
285
+
using: string list; (** Capabilities required for this request *)
286
+
method_calls: Ezjsonm.value invocation list; (** List of method calls to process *)
287
+
created_ids: (id * id) list option; (** Map of client-created IDs to server IDs *)
180
288
}
181
289
182
-
(** Response object as per Section 3.4 *)
290
+
(** Response object as defined in RFC8620 Section 3.4.
291
+
Represents a JMAP response from server to client.
292
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.4>
293
+
*)
183
294
type response = {
184
-
method_responses: Ezjsonm.value invocation list;
185
-
created_ids: (id * id) list option;
186
-
session_state: string;
295
+
method_responses: Ezjsonm.value invocation list; (** List of method responses *)
296
+
created_ids: (id * id) list option; (** Map of client-created IDs to server IDs *)
297
+
session_state: string; (** Current session state on the server *)
187
298
}
188
299
189
-
(** Standard method arguments and responses *)
300
+
(** {2 Standard method arguments and responses}
301
+
Standard method patterns defined in RFC8620 Section 5
302
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5>
303
+
*)
190
304
191
-
(** Arguments for Foo/get method as per Section 5.1 *)
305
+
(** Arguments for Foo/get method as defined in RFC8620 Section 5.1.
306
+
Generic template for retrieving objects by ID.
307
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.1>
308
+
*)
192
309
type 'a get_arguments = {
193
-
account_id: id;
194
-
ids: id list option;
195
-
properties: string list option;
310
+
account_id: id; (** The account ID to operate on *)
311
+
ids: id list option; (** IDs to fetch, null means all *)
312
+
properties: string list option; (** Properties to return, null means all *)
196
313
}
197
314
198
-
(** Response for Foo/get method as per Section 5.1 *)
315
+
(** Response for Foo/get method as defined in RFC8620 Section 5.1.
316
+
Generic template for returning requested objects.
317
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.1>
318
+
*)
199
319
type 'a get_response = {
200
-
account_id: id;
201
-
state: string;
202
-
list: 'a list;
203
-
not_found: id list;
320
+
account_id: id; (** The account ID that was operated on *)
321
+
state: string; (** Server state for the type at the time of processing *)
322
+
list: 'a list; (** The list of requested objects *)
323
+
not_found: id list; (** IDs that could not be found *)
204
324
}
205
325
206
-
(** Arguments for Foo/changes method as per Section 5.2 *)
326
+
(** Arguments for Foo/changes method as defined in RFC8620 Section 5.2.
327
+
Generic template for getting state changes.
328
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.2>
329
+
*)
207
330
type changes_arguments = {
208
-
account_id: id;
209
-
since_state: string;
210
-
max_changes: unsigned_int option;
331
+
account_id: id; (** The account ID to operate on *)
332
+
since_state: string; (** The last state seen by the client *)
333
+
max_changes: unsigned_int option; (** Maximum number of changes to return *)
211
334
}
212
335
213
-
(** Response for Foo/changes method as per Section 5.2 *)
336
+
(** Response for Foo/changes method as defined in RFC8620 Section 5.2.
337
+
Generic template for returning object changes.
338
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.2>
339
+
*)
214
340
type changes_response = {
215
-
account_id: id;
216
-
old_state: string;
217
-
new_state: string;
218
-
has_more_changes: bool;
219
-
created: id list;
220
-
updated: id list;
221
-
destroyed: id list;
341
+
account_id: id; (** The account ID that was operated on *)
342
+
old_state: string; (** The state provided in the request *)
343
+
new_state: string; (** The current server state *)
344
+
has_more_changes: bool; (** True if more changes are available *)
345
+
created: id list; (** IDs of objects created since old_state *)
346
+
updated: id list; (** IDs of objects updated since old_state *)
347
+
destroyed: id list; (** IDs of objects destroyed since old_state *)
222
348
}
223
349
224
-
(** Arguments for Foo/set method as per Section 5.3 *)
350
+
(** Arguments for Foo/set method as defined in RFC8620 Section 5.3.
351
+
Generic template for creating, updating, and destroying objects.
352
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
353
+
*)
225
354
type 'a set_arguments = {
226
-
account_id: id;
227
-
if_in_state: string option;
228
-
create: (id * 'a) list option;
229
-
update: (id * patch_object) list option;
230
-
destroy: id list option;
355
+
account_id: id; (** The account ID to operate on *)
356
+
if_in_state: string option; (** Only apply changes if in this state *)
357
+
create: (id * 'a) list option; (** Map of creation IDs to objects to create *)
358
+
update: (id * patch_object) list option; (** Map of IDs to patches to apply *)
359
+
destroy: id list option; (** List of IDs to destroy *)
231
360
}
232
361
233
-
(** Response for Foo/set method as per Section 5.3 *)
362
+
(** Response for Foo/set method as defined in RFC8620 Section 5.3.
363
+
Generic template for reporting create/update/destroy status.
364
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
365
+
*)
234
366
type 'a set_response = {
235
-
account_id: id;
236
-
old_state: string option;
237
-
new_state: string;
238
-
created: (id * 'a) list option;
239
-
updated: (id * 'a option) list option;
240
-
destroyed: id list option;
241
-
not_created: (id * set_error) list option;
242
-
not_updated: (id * set_error) list option;
243
-
not_destroyed: (id * set_error) list option;
367
+
account_id: id; (** The account ID that was operated on *)
368
+
old_state: string option; (** The state before processing, if changed *)
369
+
new_state: string; (** The current server state *)
370
+
created: (id * 'a) list option; (** Map of creation IDs to created objects *)
371
+
updated: (id * 'a option) list option; (** Map of IDs to updated objects *)
372
+
destroyed: id list option; (** List of IDs successfully destroyed *)
373
+
not_created: (id * set_error) list option; (** Map of IDs to errors for failed creates *)
374
+
not_updated: (id * set_error) list option; (** Map of IDs to errors for failed updates *)
375
+
not_destroyed: (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
244
376
}
245
377
246
-
(** Arguments for Foo/copy method as per Section 5.4 *)
378
+
(** Arguments for Foo/copy method as defined in RFC8620 Section 5.4.
379
+
Generic template for copying objects between accounts.
380
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.4>
381
+
*)
247
382
type 'a copy_arguments = {
248
-
from_account_id: id;
249
-
if_from_in_state: string option;
250
-
account_id: id;
251
-
if_in_state: string option;
252
-
create: (id * 'a) list;
253
-
on_success_destroy_original: bool option;
254
-
destroy_from_if_in_state: string option;
383
+
from_account_id: id; (** The account ID to copy from *)
384
+
if_from_in_state: string option; (** Only copy if source account in this state *)
385
+
account_id: id; (** The account ID to copy to *)
386
+
if_in_state: string option; (** Only copy if destination account in this state *)
387
+
create: (id * 'a) list; (** Map of creation IDs to objects to copy *)
388
+
on_success_destroy_original: bool option; (** Whether to destroy the original after copying *)
389
+
destroy_from_if_in_state: string option; (** Only destroy originals if in this state *)
255
390
}
256
391
257
-
(** Response for Foo/copy method as per Section 5.4 *)
392
+
(** Response for Foo/copy method as defined in RFC8620 Section 5.4.
393
+
Generic template for reporting copy operation status.
394
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.4>
395
+
*)
258
396
type 'a copy_response = {
259
-
from_account_id: id;
260
-
account_id: id;
261
-
old_state: string option;
262
-
new_state: string;
263
-
created: (id * 'a) list option;
264
-
not_created: (id * set_error) list option;
397
+
from_account_id: id; (** The account ID that was copied from *)
398
+
account_id: id; (** The account ID that was copied to *)
399
+
old_state: string option; (** The state before processing, if changed *)
400
+
new_state: string; (** The current server state *)
401
+
created: (id * 'a) list option; (** Map of creation IDs to created objects *)
402
+
not_created: (id * set_error) list option; (** Map of IDs to errors for failed copies *)
265
403
}
266
404
267
-
(** Arguments for Foo/query method as per Section 5.5 *)
405
+
(** Arguments for Foo/query method as defined in RFC8620 Section 5.5.
406
+
Generic template for querying objects.
407
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
408
+
*)
268
409
type query_arguments = {
269
-
account_id: id;
270
-
filter: filter option;
271
-
sort: comparator list option;
272
-
position: int_t option;
273
-
anchor: id option;
274
-
anchor_offset: int_t option;
275
-
limit: unsigned_int option;
276
-
calculate_total: bool option;
410
+
account_id: id; (** The account ID to operate on *)
411
+
filter: filter option; (** Filter to determine which objects are returned *)
412
+
sort: comparator list option; (** Sort order for returned objects *)
413
+
position: int_t option; (** Zero-based index of first result to return *)
414
+
anchor: id option; (** ID of object to use as reference point *)
415
+
anchor_offset: int_t option; (** Offset from anchor to start returning results *)
416
+
limit: unsigned_int option; (** Maximum number of results to return *)
417
+
calculate_total: bool option; (** Whether to calculate the total number of matching objects *)
277
418
}
278
419
279
-
(** Response for Foo/query method as per Section 5.5 *)
420
+
(** Response for Foo/query method as defined in RFC8620 Section 5.5.
421
+
Generic template for returning query results.
422
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
423
+
*)
280
424
type query_response = {
281
-
account_id: id;
282
-
query_state: string;
283
-
can_calculate_changes: bool;
284
-
position: unsigned_int;
285
-
ids: id list;
286
-
total: unsigned_int option;
287
-
limit: unsigned_int option;
425
+
account_id: id; (** The account ID that was operated on *)
426
+
query_state: string; (** State string for the query results *)
427
+
can_calculate_changes: bool; (** Whether queryChanges can be used with these results *)
428
+
position: unsigned_int; (** Zero-based index of the first result *)
429
+
ids: id list; (** The list of IDs for objects matching the query *)
430
+
total: unsigned_int option; (** Total number of matching objects, if calculated *)
431
+
limit: unsigned_int option; (** Limit enforced on the results, if requested *)
288
432
}
289
433
290
-
(** Arguments for Foo/queryChanges method as per Section 5.6 *)
434
+
(** Arguments for Foo/queryChanges method as defined in RFC8620 Section 5.6.
435
+
Generic template for getting query result changes.
436
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
437
+
*)
291
438
type query_changes_arguments = {
292
-
account_id: id;
293
-
filter: filter option;
294
-
sort: comparator list option;
295
-
since_query_state: string;
296
-
max_changes: unsigned_int option;
297
-
up_to_id: id option;
298
-
calculate_total: bool option;
439
+
account_id: id; (** The account ID to operate on *)
440
+
filter: filter option; (** Same filter as used in the original query *)
441
+
sort: comparator list option; (** Same sort as used in the original query *)
442
+
since_query_state: string; (** The query_state from previous results *)
443
+
max_changes: unsigned_int option; (** Maximum number of changes to return *)
444
+
up_to_id: id option; (** Only calculate changes until this ID is encountered *)
445
+
calculate_total: bool option; (** Whether to recalculate the total matches *)
299
446
}
300
447
301
-
(** Response for Foo/queryChanges method as per Section 5.6 *)
448
+
(** Response for Foo/queryChanges method as defined in RFC8620 Section 5.6.
449
+
Generic template for returning query result changes.
450
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
451
+
*)
302
452
type query_changes_response = {
303
-
account_id: id;
304
-
old_query_state: string;
305
-
new_query_state: string;
306
-
total: unsigned_int option;
307
-
removed: id list;
308
-
added: added_item list option;
453
+
account_id: id; (** The account ID that was operated on *)
454
+
old_query_state: string; (** The query_state from the request *)
455
+
new_query_state: string; (** The current query_state on the server *)
456
+
total: unsigned_int option; (** Updated total number of matches, if calculated *)
457
+
removed: id list; (** IDs that were in the old results but not in the new *)
458
+
added: added_item list option; (** IDs that are in the new results but not the old *)
309
459
}
310
460
311
-
(** Arguments for Blob/copy method as per Section 6.3 *)
461
+
(** Arguments for Blob/copy method as defined in RFC8620 Section 6.3.
462
+
Used for copying binary data between accounts.
463
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.3>
464
+
*)
312
465
type blob_copy_arguments = {
313
-
from_account_id: id;
314
-
account_id: id;
315
-
blob_ids: id list;
466
+
from_account_id: id; (** The account ID to copy blobs from *)
467
+
account_id: id; (** The account ID to copy blobs to *)
468
+
blob_ids: id list; (** IDs of blobs to copy *)
316
469
}
317
470
318
-
(** Response for Blob/copy method as per Section 6.3 *)
471
+
(** Response for Blob/copy method as defined in RFC8620 Section 6.3.
472
+
Reports the results of copying binary data.
473
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.3>
474
+
*)
319
475
type blob_copy_response = {
320
-
from_account_id: id;
321
-
account_id: id;
322
-
copied: (id * id) list option;
323
-
not_copied: (id * set_error) list option;
476
+
from_account_id: id; (** The account ID that was copied from *)
477
+
account_id: id; (** The account ID that was copied to *)
478
+
copied: (id * id) list option; (** Map of source IDs to destination IDs *)
479
+
not_copied: (id * set_error) list option; (** Map of IDs to errors for failed copies *)
324
480
}
325
481
326
-
(** Upload response as per Section 6.1 *)
482
+
(** Upload response as defined in RFC8620 Section 6.1.
483
+
Contains information about an uploaded binary blob.
484
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.1>
485
+
*)
327
486
type upload_response = {
328
-
account_id: id;
329
-
blob_id: id;
330
-
type_: string;
331
-
size: unsigned_int;
487
+
account_id: id; (** The account ID the blob was uploaded to *)
488
+
blob_id: id; (** The ID for the uploaded blob *)
489
+
type_: string; (** Media type of the blob *)
490
+
size: unsigned_int; (** Size of the blob in octets *)
332
491
}
333
492
334
-
(** Problem details object as per RFC7807 and Section 3.6.1 *)
493
+
(** Problem details object as defined in RFC8620 Section 3.6.1 and RFC7807.
494
+
Used for HTTP error responses in the JMAP protocol.
495
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.6.1>
496
+
@see <https://datatracker.ietf.org/doc/html/rfc7807>
497
+
*)
335
498
type problem_details = {
336
-
type_: string;
337
-
status: int option;
338
-
detail: string option;
339
-
limit: string option; (* For "limit" error *)
499
+
type_: string; (** URI that identifies the problem type *)
500
+
status: int option; (** HTTP status code for this problem *)
501
+
detail: string option; (** Human-readable explanation of the problem *)
502
+
limit: string option; (** For "limit" errors, which limit was exceeded *)
340
503
}
341
504
end
342
505
343
-
(** {1 API Client} *)
506
+
(** {1 API Client}
507
+
Modules for interacting with JMAP servers
508
+
*)
344
509
345
510
(** Module for working with ResultReferences as described in Section 3.7 of RFC8620.
346
-
Provides utilities to create and compose results from previous methods. *)
511
+
Provides utilities to create and compose results from previous methods.
512
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
513
+
*)
347
514
module ResultReference : sig
348
-
(** Create a reference to a previous method result *)
515
+
(** Create a reference to a previous method result
516
+
@param result_of The methodCallId of the method call to reference
517
+
@param name The name in the response to reference (e.g., "list")
518
+
@param path JSON pointer path to the value being referenced
519
+
@return A result_reference object
520
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
521
+
*)
349
522
val create :
350
523
result_of:string ->
351
524
name:string ->
352
525
path:string ->
353
526
Types.result_reference
354
527
355
-
(** Create a JSON pointer path to access a specific property *)
528
+
(** Create a JSON pointer path to access a specific property
529
+
@param property The property name to access
530
+
@return A JSON pointer path string
531
+
*)
356
532
val property_path : string -> string
357
533
358
-
(** Create a JSON pointer path to access all items in an array with a specific property *)
534
+
(** Create a JSON pointer path to access all items in an array with a specific property
535
+
@param property Optional property to access within each array item
536
+
@param array_name The name of the array to access
537
+
@return A JSON pointer path string that references all items in the array
538
+
*)
359
539
val array_items_path : ?property:string -> string -> string
360
540
361
541
(** Create argument with result reference.
362
-
Returns string key prefixed with # and ResultReference value. *)
542
+
@param arg_name The name of the argument
543
+
@param reference The result reference to use
544
+
@return A tuple of string key (with # prefix) and ResultReference JSON value
545
+
*)
363
546
val reference_arg : string -> Types.result_reference -> string * Ezjsonm.value
364
547
365
-
(** Create a reference to all IDs returned by a query method *)
548
+
(** Create a reference to all IDs returned by a query method
549
+
@param result_of The methodCallId of the query method call
550
+
@return A result_reference to the IDs returned by the query
551
+
*)
366
552
val query_ids :
367
553
result_of:string ->
368
554
Types.result_reference
369
555
370
-
(** Create a reference to properties of objects returned by a get method *)
556
+
(** Create a reference to properties of objects returned by a get method
557
+
@param result_of The methodCallId of the get method call
558
+
@param property The property to reference in the returned objects
559
+
@return A result_reference to the specified property in the get results
560
+
*)
371
561
val get_property :
372
562
result_of:string ->
373
563
property:string ->
···
375
565
end
376
566
377
567
(** Module for making JMAP API requests over HTTP.
378
-
Provides functionality to interact with JMAP servers according to RFC8620. *)
568
+
Provides functionality to interact with JMAP servers according to RFC8620.
569
+
@see <https://datatracker.ietf.org/doc/html/rfc8620>
570
+
*)
379
571
module Api : sig
380
572
(** Error that may occur during API requests *)
381
573
type error =
382
-
| Connection_error of string
383
-
| HTTP_error of int * string
384
-
| Parse_error of string
385
-
| Authentication_error
574
+
| Connection_error of string (** Network-related errors *)
575
+
| HTTP_error of int * string (** HTTP errors with status code and message *)
576
+
| Parse_error of string (** JSON parsing errors *)
577
+
| Authentication_error (** Authentication failures *)
386
578
387
579
(** Result type for API operations *)
388
580
type 'a result = ('a, error) Stdlib.result
389
581
390
-
(** Configuration for a JMAP API client *)
582
+
(** Configuration for a JMAP API client as defined in RFC8620 Section 3.1
583
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.1>
584
+
*)
391
585
type config = {
392
-
api_uri: Uri.t;
393
-
username: string;
394
-
authentication_token: string;
586
+
api_uri: Uri.t; (** The JMAP API endpoint URI *)
587
+
username: string; (** The username for authentication *)
588
+
authentication_token: string; (** The token for authentication *)
395
589
}
396
590
397
-
(** Make a raw JMAP API request *)
591
+
(** Make a raw JMAP API request as defined in RFC8620 Section 3.3
592
+
@param config The API client configuration
593
+
@param request The JMAP request to send
594
+
@return A result containing the JMAP response or an error
595
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.3>
596
+
*)
398
597
val make_request :
399
598
config ->
400
599
Types.request ->
401
600
Types.response result Lwt.t
402
601
403
-
(** Fetch a Session object from a JMAP server.
404
-
Can authenticate with either username/password or API token. *)
602
+
(** Fetch a Session object from a JMAP server as defined in RFC8620 Section 2
603
+
Can authenticate with either username/password or API token.
604
+
@param uri The URI of the JMAP session resource
605
+
@param username Optional username for authentication
606
+
@param authentication_token Optional password or token for authentication
607
+
@param api_token Optional API token for Bearer authentication
608
+
@return A result containing the session object or an error
609
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
610
+
*)
405
611
val get_session :
406
612
Uri.t ->
407
613
?username:string ->
···
410
616
unit ->
411
617
Types.session result Lwt.t
412
618
413
-
(** Upload a binary blob to the server *)
619
+
(** Upload a binary blob to the server as defined in RFC8620 Section 6.1
620
+
@param config The API client configuration
621
+
@param account_id The account ID to upload to
622
+
@param content_type The MIME type of the blob
623
+
@param data The blob data as a string
624
+
@return A result containing the upload response or an error
625
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.1>
626
+
*)
414
627
val upload_blob :
415
628
config ->
416
629
account_id:Types.id ->
···
418
631
string ->
419
632
Types.upload_response result Lwt.t
420
633
421
-
(** Download a binary blob from the server *)
634
+
(** Download a binary blob from the server as defined in RFC8620 Section 6.2
635
+
@param config The API client configuration
636
+
@param account_id The account ID that contains the blob
637
+
@param blob_id The ID of the blob to download
638
+
@param type_ Optional MIME type to require for the blob
639
+
@param name Optional name for the downloaded blob
640
+
@return A result containing the blob data as a string or an error
641
+
@see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.2>
642
+
*)
422
643
val download_blob :
423
644
config ->
424
645
account_id:Types.id ->
···
427
648
?name:string ->
428
649
unit ->
429
650
string result Lwt.t
430
-
end
651
+
end
+1024
-608
lib/jmap_mail.mli
+1024
-608
lib/jmap_mail.mli
···
1
-
(** Implementation of the JMAP Mail extension, as defined in RFC8621 *)
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
+
*)
2
8
3
-
(** Module for managing JMAP Mail-specific capability URIs *)
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
+
*)
4
12
module Capability : sig
5
-
(** Mail capability URI *)
13
+
(** Mail capability URI as defined in RFC8621 Section 1.3
14
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
15
+
*)
6
16
val mail_uri : string
7
17
8
-
(** Submission capability URI *)
18
+
(** Submission capability URI as defined in RFC8621 Section 1.3
19
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
20
+
*)
9
21
val submission_uri : string
10
22
11
-
(** Vacation response capability URI *)
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
+
*)
12
26
val vacation_response_uri : string
13
27
14
-
(** All mail extension capability types *)
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
+
*)
15
31
type t =
16
-
| Mail (** Mail capability *)
17
-
| Submission (** Submission capability *)
18
-
| VacationResponse (** Vacation response capability *)
19
-
| Extension of string (** Custom extension *)
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 *)
20
36
21
-
(** Convert capability to URI string *)
37
+
(** Convert capability to URI string
38
+
@param capability The capability to convert
39
+
@return The full URI string for the capability
40
+
*)
22
41
val to_string : t -> string
23
42
24
-
(** Parse a string to a capability *)
43
+
(** Parse a string to a capability
44
+
@param uri The capability URI string to parse
45
+
@return The parsed capability type
46
+
*)
25
47
val of_string : string -> t
26
48
27
-
(** Check if a capability is a standard mail capability *)
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
+
*)
28
53
val is_standard : t -> bool
29
54
30
-
(** Check if a capability string is a standard mail capability *)
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
+
*)
31
59
val is_standard_string : string -> bool
32
60
33
-
(** Create a list of capability strings *)
61
+
(** Create a list of capability strings
62
+
@param capabilities List of capability types
63
+
@return List of capability URI strings
64
+
*)
34
65
val strings_of_capabilities : t list -> string list
35
66
end
36
67
37
-
(** Types for the JMAP Mail extension *)
68
+
(** Types for the JMAP Mail extension as defined in RFC8621
69
+
@see <https://datatracker.ietf.org/doc/html/rfc8621>
70
+
*)
38
71
module Types : sig
39
72
open Jmap.Types
40
73
41
-
(** {1 Mail capabilities} *)
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
+
*)
42
78
43
-
(** Capability URI for JMAP Mail*)
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
+
*)
44
83
val capability_mail : string
45
84
46
-
(** Capability URI for JMAP Submission *)
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
+
*)
47
89
val capability_submission : string
48
90
49
-
(** Capability URI for JMAP Vacation Response *)
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
+
*)
50
95
val capability_vacation_response : string
51
96
52
-
(** {1:mailbox Mailbox objects} *)
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
+
*)
53
101
54
-
(** A role for a mailbox. See RFC8621 Section 2. *)
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
+
*)
55
106
type mailbox_role =
56
-
| All (** All mail *)
57
-
| Archive (** Archived mail *)
58
-
| Drafts (** Draft messages *)
59
-
| Flagged (** Starred/flagged mail *)
60
-
| Important (** Important mail *)
61
-
| Inbox (** Inbox *)
62
-
| Junk (** Spam/Junk mail *)
63
-
| Sent (** Sent mail *)
64
-
| Trash (** Deleted/Trash mail *)
65
-
| Unknown of string (** Server-specific roles *)
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 *)
66
117
67
-
(** A mailbox (folder) in a mail account. See RFC8621 Section 2. *)
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
+
*)
68
122
type mailbox = {
69
-
id : id;
70
-
name : string;
71
-
parent_id : id option;
72
-
role : mailbox_role option;
73
-
sort_order : unsigned_int;
74
-
total_emails : unsigned_int;
75
-
unread_emails : unsigned_int;
76
-
total_threads : unsigned_int;
77
-
unread_threads : unsigned_int;
78
-
is_subscribed : bool;
79
-
my_rights : mailbox_rights;
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 *)
80
134
}
81
135
82
-
(** Rights for a mailbox. See RFC8621 Section 2. *)
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
+
*)
83
140
and mailbox_rights = {
84
-
may_read_items : bool;
85
-
may_add_items : bool;
86
-
may_remove_items : bool;
87
-
may_set_seen : bool;
88
-
may_set_keywords : bool;
89
-
may_create_child : bool;
90
-
may_rename : bool;
91
-
may_delete : bool;
92
-
may_submit : bool;
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 *)
93
150
}
94
151
95
-
(** Filter condition for mailbox queries. See RFC8621 Section 2.3. *)
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
+
*)
96
156
type mailbox_filter_condition = {
97
-
parent_id : id option;
98
-
name : string option;
99
-
role : string option;
100
-
has_any_role : bool option;
101
-
is_subscribed : bool option;
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 *)
102
162
}
103
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
+
*)
104
168
type mailbox_query_filter = [
105
-
| `And of mailbox_query_filter list
106
-
| `Or of mailbox_query_filter list
107
-
| `Not of mailbox_query_filter
108
-
| `Condition of mailbox_filter_condition
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 *)
109
173
]
110
174
111
-
(** Mailbox/get request arguments. See RFC8621 Section 2.1. *)
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
+
*)
112
179
type mailbox_get_arguments = {
113
-
account_id : id;
114
-
ids : id list option;
115
-
properties : string list option;
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 *)
116
183
}
117
184
118
-
(** Mailbox/get response. See RFC8621 Section 2.1. *)
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
+
*)
119
189
type mailbox_get_response = {
120
-
account_id : id;
121
-
state : string;
122
-
list : mailbox list;
123
-
not_found : id list;
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 *)
124
194
}
125
195
126
-
(** Mailbox/changes request arguments. See RFC8621 Section 2.2. *)
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
+
*)
127
200
type mailbox_changes_arguments = {
128
-
account_id : id;
129
-
since_state : string;
130
-
max_changes : unsigned_int option;
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 *)
131
204
}
132
205
133
-
(** Mailbox/changes response. See RFC8621 Section 2.2. *)
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
+
*)
134
210
type mailbox_changes_response = {
135
-
account_id : id;
136
-
old_state : string;
137
-
new_state : string;
138
-
has_more_changes : bool;
139
-
created : id list;
140
-
updated : id list;
141
-
destroyed : id list;
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 *)
142
218
}
143
219
144
-
(** Mailbox/query request arguments. See RFC8621 Section 2.3. *)
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
+
*)
145
224
type mailbox_query_arguments = {
146
-
account_id : id;
147
-
filter : mailbox_query_filter option;
148
-
sort : [ `name | `role | `sort_order ] list option;
149
-
limit : unsigned_int option;
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 *)
150
229
}
151
230
152
-
(** Mailbox/query response. See RFC8621 Section 2.3. *)
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
+
*)
153
235
type mailbox_query_response = {
154
-
account_id : id;
155
-
query_state : string;
156
-
can_calculate_changes : bool;
157
-
position : unsigned_int;
158
-
ids : id list;
159
-
total : unsigned_int option;
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 *)
160
242
}
161
243
162
-
(** Mailbox/queryChanges request arguments. See RFC8621 Section 2.4. *)
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
+
*)
163
248
type mailbox_query_changes_arguments = {
164
-
account_id : id;
165
-
filter : mailbox_query_filter option;
166
-
sort : [ `name | `role | `sort_order ] list option;
167
-
since_query_state : string;
168
-
max_changes : unsigned_int option;
169
-
up_to_id : id option;
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 *)
170
255
}
171
256
172
-
(** Mailbox/queryChanges response. See RFC8621 Section 2.4. *)
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
+
*)
173
261
type mailbox_query_changes_response = {
174
-
account_id : id;
175
-
old_query_state : string;
176
-
new_query_state : string;
177
-
total : unsigned_int option;
178
-
removed : id list;
179
-
added : mailbox_query_changes_added list;
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 *)
180
268
}
181
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
+
*)
182
274
and mailbox_query_changes_added = {
183
-
id : id;
184
-
index : unsigned_int;
275
+
id : id; (** ID of the added mailbox *)
276
+
index : unsigned_int; (** Zero-based index of the added mailbox in the results *)
185
277
}
186
278
187
-
(** Mailbox/set request arguments. See RFC8621 Section 2.5. *)
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
+
*)
188
283
type mailbox_set_arguments = {
189
-
account_id : id;
190
-
if_in_state : string option;
191
-
create : (id * mailbox_creation) list option;
192
-
update : (id * mailbox_update) list option;
193
-
destroy : id list option;
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 *)
194
289
}
195
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
+
*)
196
295
and mailbox_creation = {
197
-
name : string;
198
-
parent_id : id option;
199
-
role : string option;
200
-
sort_order : unsigned_int option;
201
-
is_subscribed : bool option;
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 *)
202
301
}
203
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
+
*)
204
307
and mailbox_update = {
205
-
name : string option;
206
-
parent_id : id option;
207
-
role : string option;
208
-
sort_order : unsigned_int option;
209
-
is_subscribed : bool option;
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 *)
210
313
}
211
314
212
-
(** Mailbox/set response. See RFC8621 Section 2.5. *)
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
+
*)
213
319
type mailbox_set_response = {
214
-
account_id : id;
215
-
old_state : string option;
216
-
new_state : string;
217
-
created : (id * mailbox) list option;
218
-
updated : id list option;
219
-
destroyed : id list option;
220
-
not_created : (id * set_error) list option;
221
-
not_updated : (id * set_error) list option;
222
-
not_destroyed : (id * set_error) list option;
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 *)
223
329
}
224
330
225
-
(** {1:thread Thread objects} *)
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
+
*)
226
335
227
-
(** A thread in a mail account. See RFC8621 Section 3. *)
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
+
*)
228
340
type thread = {
229
-
id : id;
230
-
email_ids : id list;
341
+
id : id; (** Server-assigned ID for the thread *)
342
+
email_ids : id list; (** IDs of emails in the thread *)
231
343
}
232
344
233
-
(** Thread/get request arguments. See RFC8621 Section 3.1. *)
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
+
*)
234
349
type thread_get_arguments = {
235
-
account_id : id;
236
-
ids : id list option;
237
-
properties : string list option;
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 *)
238
353
}
239
354
240
-
(** Thread/get response. See RFC8621 Section 3.1. *)
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
+
*)
241
359
type thread_get_response = {
242
-
account_id : id;
243
-
state : string;
244
-
list : thread list;
245
-
not_found : id list;
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 *)
246
364
}
247
365
248
-
(** Thread/changes request arguments. See RFC8621 Section 3.2. *)
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
+
*)
249
370
type thread_changes_arguments = {
250
-
account_id : id;
251
-
since_state : string;
252
-
max_changes : unsigned_int option;
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 *)
253
374
}
254
375
255
-
(** Thread/changes response. See RFC8621 Section 3.2. *)
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
+
*)
256
380
type thread_changes_response = {
257
-
account_id : id;
258
-
old_state : string;
259
-
new_state : string;
260
-
has_more_changes : bool;
261
-
created : id list;
262
-
updated : id list;
263
-
destroyed : id list;
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 *)
264
388
}
265
389
266
-
(** {1:email Email objects} *)
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
+
*)
267
394
268
-
(** Addressing (mailbox) information. See RFC8621 Section 4.1.1. *)
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
+
*)
269
399
type email_address = {
270
-
name : string option;
271
-
email : string;
272
-
parameters : (string * string) list;
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 *)
273
403
}
274
404
275
-
(** Message header field. See RFC8621 Section 4.1.2. *)
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
+
*)
276
409
type header = {
277
-
name : string;
278
-
value : string;
410
+
name : string; (** Name of the header field (e.g., "Subject") *)
411
+
value : string; (** Value of the header field *)
279
412
}
280
413
281
-
(** Email keyword (flag). See RFC8621 Section 4.3. *)
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
+
*)
282
418
type keyword =
283
-
| Flagged
284
-
| Answered
285
-
| Draft
286
-
| Forwarded
287
-
| Phishing
288
-
| Junk
289
-
| NotJunk
290
-
| Seen
291
-
| Unread
292
-
| Custom of string
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 *)
293
429
294
-
(** Email message. See RFC8621 Section 4. *)
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
+
*)
295
434
type email = {
296
-
id : id;
297
-
blob_id : id;
298
-
thread_id : id;
299
-
mailbox_ids : (id * bool) list;
300
-
keywords : (keyword * bool) list;
301
-
size : unsigned_int;
302
-
received_at : utc_date;
303
-
message_id : string list;
304
-
in_reply_to : string list option;
305
-
references : string list option;
306
-
sender : email_address list option;
307
-
from : email_address list option;
308
-
to_ : email_address list option;
309
-
cc : email_address list option;
310
-
bcc : email_address list option;
311
-
reply_to : email_address list option;
312
-
subject : string option;
313
-
sent_at : utc_date option;
314
-
has_attachment : bool option;
315
-
preview : string option;
316
-
body_values : (string * string) list option;
317
-
text_body : email_body_part list option;
318
-
html_body : email_body_part list option;
319
-
attachments : email_body_part list option;
320
-
headers : header list option;
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 *)
321
460
}
322
461
323
-
(** Email body part. See RFC8621 Section 4.1.4. *)
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
+
*)
324
466
and email_body_part = {
325
-
part_id : string option;
326
-
blob_id : id option;
327
-
size : unsigned_int option;
328
-
headers : header list option;
329
-
name : string option;
330
-
type_ : string option;
331
-
charset : string option;
332
-
disposition : string option;
333
-
cid : string option;
334
-
language : string list option;
335
-
location : string option;
336
-
sub_parts : email_body_part list option;
337
-
header_parameter_name : string option;
338
-
header_parameter_value : string option;
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) *)
339
481
}
340
482
341
-
(** Email query filter condition. See RFC8621 Section 4.4. *)
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
+
*)
342
487
type email_filter_condition = {
343
-
in_mailbox : id option;
344
-
in_mailbox_other_than : id list option;
345
-
min_size : unsigned_int option;
346
-
max_size : unsigned_int option;
347
-
before : utc_date option;
348
-
after : utc_date option;
349
-
header : (string * string) option;
350
-
from : string option;
351
-
to_ : string option;
352
-
cc : string option;
353
-
bcc : string option;
354
-
subject : string option;
355
-
body : string option;
356
-
has_keyword : string option;
357
-
not_keyword : string option;
358
-
has_attachment : bool option;
359
-
text : string option;
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 *)
360
505
}
361
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
+
*)
362
511
type email_query_filter = [
363
-
| `And of email_query_filter list
364
-
| `Or of email_query_filter list
365
-
| `Not of email_query_filter
366
-
| `Condition of email_filter_condition
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 *)
367
516
]
368
517
369
-
(** Email/get request arguments. See RFC8621 Section 4.5. *)
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
+
*)
370
522
type email_get_arguments = {
371
-
account_id : id;
372
-
ids : id list option;
373
-
properties : string list option;
374
-
body_properties : string list option;
375
-
fetch_text_body_values : bool option;
376
-
fetch_html_body_values : bool option;
377
-
fetch_all_body_values : bool option;
378
-
max_body_value_bytes : unsigned_int option;
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 *)
379
531
}
380
532
381
-
(** Email/get response. See RFC8621 Section 4.5. *)
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
+
*)
382
537
type email_get_response = {
383
-
account_id : id;
384
-
state : string;
385
-
list : email list;
386
-
not_found : id list;
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 *)
387
542
}
388
543
389
-
(** Email/changes request arguments. See RFC8621 Section 4.6. *)
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
+
*)
390
548
type email_changes_arguments = {
391
-
account_id : id;
392
-
since_state : string;
393
-
max_changes : unsigned_int option;
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 *)
394
552
}
395
553
396
-
(** Email/changes response. See RFC8621 Section 4.6. *)
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
+
*)
397
558
type email_changes_response = {
398
-
account_id : id;
399
-
old_state : string;
400
-
new_state : string;
401
-
has_more_changes : bool;
402
-
created : id list;
403
-
updated : id list;
404
-
destroyed : id list;
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 *)
405
566
}
406
567
407
-
(** Email/query request arguments. See RFC8621 Section 4.4. *)
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
+
*)
408
572
type email_query_arguments = {
409
-
account_id : id;
410
-
filter : email_query_filter option;
411
-
sort : comparator list option;
412
-
collapse_threads : bool option;
413
-
position : unsigned_int option;
414
-
anchor : id option;
415
-
anchor_offset : int_t option;
416
-
limit : unsigned_int option;
417
-
calculate_total : bool option;
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 *)
418
582
}
419
583
420
-
(** Email/query response. See RFC8621 Section 4.4. *)
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
+
*)
421
588
type email_query_response = {
422
-
account_id : id;
423
-
query_state : string;
424
-
can_calculate_changes : bool;
425
-
position : unsigned_int;
426
-
ids : id list;
427
-
total : unsigned_int option;
428
-
thread_ids : id list option;
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 *)
429
596
}
430
597
431
-
(** Email/queryChanges request arguments. See RFC8621 Section 4.7. *)
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
+
*)
432
602
type email_query_changes_arguments = {
433
-
account_id : id;
434
-
filter : email_query_filter option;
435
-
sort : comparator list option;
436
-
collapse_threads : bool option;
437
-
since_query_state : string;
438
-
max_changes : unsigned_int option;
439
-
up_to_id : id option;
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 *)
440
610
}
441
611
442
-
(** Email/queryChanges response. See RFC8621 Section 4.7. *)
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
+
*)
443
616
type email_query_changes_response = {
444
-
account_id : id;
445
-
old_query_state : string;
446
-
new_query_state : string;
447
-
total : unsigned_int option;
448
-
removed : id list;
449
-
added : email_query_changes_added list;
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 *)
450
623
}
451
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
+
*)
452
629
and email_query_changes_added = {
453
-
id : id;
454
-
index : unsigned_int;
630
+
id : id; (** ID of the added email *)
631
+
index : unsigned_int; (** Zero-based index of the added email in the results *)
455
632
}
456
633
457
-
(** Email/set request arguments. See RFC8621 Section 4.8. *)
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
+
*)
458
638
type email_set_arguments = {
459
-
account_id : id;
460
-
if_in_state : string option;
461
-
create : (id * email_creation) list option;
462
-
update : (id * email_update) list option;
463
-
destroy : id list option;
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 *)
464
644
}
465
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
+
*)
466
650
and email_creation = {
467
-
mailbox_ids : (id * bool) list;
468
-
keywords : (keyword * bool) list option;
469
-
received_at : utc_date option;
470
-
message_id : string list option;
471
-
in_reply_to : string list option;
472
-
references : string list option;
473
-
sender : email_address list option;
474
-
from : email_address list option;
475
-
to_ : email_address list option;
476
-
cc : email_address list option;
477
-
bcc : email_address list option;
478
-
reply_to : email_address list option;
479
-
subject : string option;
480
-
body_values : (string * string) list option;
481
-
text_body : email_body_part list option;
482
-
html_body : email_body_part list option;
483
-
attachments : email_body_part list option;
484
-
headers : header list option;
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 *)
485
669
}
486
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
+
*)
487
675
and email_update = {
488
-
keywords : (keyword * bool) list option;
489
-
mailbox_ids : (id * bool) list option;
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 *)
490
678
}
491
679
492
-
(** Email/set response. See RFC8621 Section 4.8. *)
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
+
*)
493
684
type email_set_response = {
494
-
account_id : id;
495
-
old_state : string option;
496
-
new_state : string;
497
-
created : (id * email) list option;
498
-
updated : id list option;
499
-
destroyed : id list option;
500
-
not_created : (id * set_error) list option;
501
-
not_updated : (id * set_error) list option;
502
-
not_destroyed : (id * set_error) list option;
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 *)
503
694
}
504
695
505
-
(** Email/copy request arguments. See RFC8621 Section 4.9. *)
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
+
*)
506
700
type email_copy_arguments = {
507
-
from_account_id : id;
508
-
account_id : id;
509
-
create : (id * email_creation) list;
510
-
on_success_destroy_original : bool option;
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 *)
511
705
}
512
706
513
-
(** Email/copy response. See RFC8621 Section 4.9. *)
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
+
*)
514
711
type email_copy_response = {
515
-
from_account_id : id;
516
-
account_id : id;
517
-
created : (id * email) list option;
518
-
not_created : (id * set_error) list option;
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 *)
519
716
}
520
717
521
-
(** Email/import request arguments. See RFC8621 Section 4.10. *)
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
+
*)
522
722
type email_import_arguments = {
523
-
account_id : id;
524
-
emails : (id * email_import) list;
723
+
account_id : id; (** The account to import emails into *)
724
+
emails : (id * email_import) list; (** Map of creation IDs to import properties *)
525
725
}
526
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
+
*)
527
731
and email_import = {
528
-
blob_id : id;
529
-
mailbox_ids : (id * bool) list;
530
-
keywords : (keyword * bool) list option;
531
-
received_at : utc_date option;
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 *)
532
736
}
533
737
534
-
(** Email/import response. See RFC8621 Section 4.10. *)
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
+
*)
535
742
type email_import_response = {
536
-
account_id : id;
537
-
created : (id * email) list option;
538
-
not_created : (id * set_error) list option;
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 *)
539
746
}
540
747
541
-
(** {1:search_snippet Search snippets} *)
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
+
*)
542
752
543
-
(** SearchSnippet/get request arguments. See RFC8621 Section 4.11. *)
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
+
*)
544
757
type search_snippet_get_arguments = {
545
-
account_id : id;
546
-
email_ids : id list;
547
-
filter : email_filter_condition;
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 *)
548
761
}
549
762
550
-
(** SearchSnippet/get response. See RFC8621 Section 4.11. *)
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
+
*)
551
767
type search_snippet_get_response = {
552
-
account_id : id;
553
-
list : (id * search_snippet) list;
554
-
not_found : id list;
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 *)
555
771
}
556
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
+
*)
557
777
and search_snippet = {
558
-
subject : string option;
559
-
preview : string option;
778
+
subject : string option; (** Subject with search terms highlighted *)
779
+
preview : string option; (** Email body preview with search terms highlighted *)
560
780
}
561
781
562
-
(** {1:submission EmailSubmission objects} *)
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
+
*)
563
786
564
-
(** EmailSubmission address. See RFC8621 Section 5.1. *)
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
+
*)
565
791
type submission_address = {
566
-
email : string;
567
-
parameters : (string * string) list option;
792
+
email : string; (** The email address (e.g., "john@example.com") *)
793
+
parameters : (string * string) list option; (** SMTP extension parameters *)
568
794
}
569
795
570
-
(** Email submission object. See RFC8621 Section 5.1. *)
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
+
*)
571
800
type email_submission = {
572
-
id : id;
573
-
identity_id : id;
574
-
email_id : id;
575
-
thread_id : id;
576
-
envelope : envelope option;
577
-
send_at : utc_date option;
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 *)
578
807
undo_status : [
579
-
| `pending
580
-
| `final
581
-
| `canceled
582
-
] option;
583
-
delivery_status : (string * submission_status) list option;
584
-
dsn_blob_ids : (string * id) list option;
585
-
mdn_blob_ids : (string * id) list option;
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 *)
586
815
}
587
816
588
-
(** Envelope for mail submission. See RFC8621 Section 5.1. *)
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
+
*)
589
821
and envelope = {
590
-
mail_from : submission_address;
591
-
rcpt_to : submission_address list;
822
+
mail_from : submission_address; (** Return path for the message *)
823
+
rcpt_to : submission_address list; (** Recipients for the message *)
592
824
}
593
825
594
-
(** Delivery status for submitted email. See RFC8621 Section 5.1. *)
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
+
*)
595
830
and submission_status = {
596
-
smtp_reply : string;
597
-
delivered : string option;
831
+
smtp_reply : string; (** SMTP response from the server *)
832
+
delivered : string option; (** Timestamp when message was delivered, if successful *)
598
833
}
599
834
600
-
(** EmailSubmission/get request arguments. See RFC8621 Section 5.3. *)
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
+
*)
601
839
type email_submission_get_arguments = {
602
-
account_id : id;
603
-
ids : id list option;
604
-
properties : string list option;
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 *)
605
843
}
606
844
607
-
(** EmailSubmission/get response. See RFC8621 Section 5.3. *)
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
+
*)
608
849
type email_submission_get_response = {
609
-
account_id : id;
610
-
state : string;
611
-
list : email_submission list;
612
-
not_found : id list;
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 *)
613
854
}
614
855
615
-
(** EmailSubmission/changes request arguments. See RFC8621 Section 5.4. *)
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
+
*)
616
860
type email_submission_changes_arguments = {
617
-
account_id : id;
618
-
since_state : string;
619
-
max_changes : unsigned_int option;
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 *)
620
864
}
621
865
622
-
(** EmailSubmission/changes response. See RFC8621 Section 5.4. *)
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
+
*)
623
870
type email_submission_changes_response = {
624
-
account_id : id;
625
-
old_state : string;
626
-
new_state : string;
627
-
has_more_changes : bool;
628
-
created : id list;
629
-
updated : id list;
630
-
destroyed : id list;
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 *)
631
878
}
632
879
633
-
(** EmailSubmission/query filter condition. See RFC8621 Section 5.5. *)
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
+
*)
634
884
type email_submission_filter_condition = {
635
-
identity_id : id option;
636
-
email_id : id option;
637
-
thread_id : id option;
638
-
before : utc_date option;
639
-
after : utc_date option;
640
-
subject : string option;
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 *)
641
891
}
642
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
+
*)
643
897
type email_submission_query_filter = [
644
-
| `And of email_submission_query_filter list
645
-
| `Or of email_submission_query_filter list
646
-
| `Not of email_submission_query_filter
647
-
| `Condition of email_submission_filter_condition
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 *)
648
902
]
649
903
650
-
(** EmailSubmission/query request arguments. See RFC8621 Section 5.5. *)
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
+
*)
651
908
type email_submission_query_arguments = {
652
-
account_id : id;
653
-
filter : email_submission_query_filter option;
654
-
sort : comparator list option;
655
-
position : unsigned_int option;
656
-
anchor : id option;
657
-
anchor_offset : int_t option;
658
-
limit : unsigned_int option;
659
-
calculate_total : bool option;
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 *)
660
917
}
661
918
662
-
(** EmailSubmission/query response. See RFC8621 Section 5.5. *)
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
+
*)
663
923
type email_submission_query_response = {
664
-
account_id : id;
665
-
query_state : string;
666
-
can_calculate_changes : bool;
667
-
position : unsigned_int;
668
-
ids : id list;
669
-
total : unsigned_int option;
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 *)
670
930
}
671
931
672
-
(** EmailSubmission/set request arguments. See RFC8621 Section 5.6. *)
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
+
*)
673
936
type email_submission_set_arguments = {
674
-
account_id : id;
675
-
if_in_state : string option;
676
-
create : (id * email_submission_creation) list option;
677
-
update : (id * email_submission_update) list option;
678
-
destroy : id list option;
679
-
on_success_update_email : (id * email_update) list option;
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 *)
680
943
}
681
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
+
*)
682
949
and email_submission_creation = {
683
-
email_id : id;
684
-
identity_id : id;
685
-
envelope : envelope option;
686
-
send_at : utc_date option;
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 *)
687
954
}
688
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
+
*)
689
960
and email_submission_update = {
690
-
email_id : id option;
691
-
identity_id : id option;
692
-
envelope : envelope option;
693
-
undo_status : [`canceled] option;
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 *)
694
965
}
695
966
696
-
(** EmailSubmission/set response. See RFC8621 Section 5.6. *)
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
+
*)
697
971
type email_submission_set_response = {
698
-
account_id : id;
699
-
old_state : string option;
700
-
new_state : string;
701
-
created : (id * email_submission) list option;
702
-
updated : id list option;
703
-
destroyed : id list option;
704
-
not_created : (id * set_error) list option;
705
-
not_updated : (id * set_error) list option;
706
-
not_destroyed : (id * set_error) list option;
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 *)
707
981
}
708
982
709
-
(** {1:identity Identity objects} *)
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
+
*)
710
987
711
-
(** Identity for sending mail. See RFC8621 Section 6. *)
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
+
*)
712
992
type identity = {
713
-
id : id;
714
-
name : string;
715
-
email : string;
716
-
reply_to : email_address list option;
717
-
bcc : email_address list option;
718
-
text_signature : string option;
719
-
html_signature : string option;
720
-
may_delete : bool;
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 *)
721
1001
}
722
1002
723
-
(** Identity/get request arguments. See RFC8621 Section 6.1. *)
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
+
*)
724
1007
type identity_get_arguments = {
725
-
account_id : id;
726
-
ids : id list option;
727
-
properties : string list option;
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 *)
728
1011
}
729
1012
730
-
(** Identity/get response. See RFC8621 Section 6.1. *)
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
+
*)
731
1017
type identity_get_response = {
732
-
account_id : id;
733
-
state : string;
734
-
list : identity list;
735
-
not_found : id list;
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 *)
736
1022
}
737
1023
738
-
(** Identity/changes request arguments. See RFC8621 Section 6.2. *)
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
+
*)
739
1028
type identity_changes_arguments = {
740
-
account_id : id;
741
-
since_state : string;
742
-
max_changes : unsigned_int option;
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 *)
743
1032
}
744
1033
745
-
(** Identity/changes response. See RFC8621 Section 6.2. *)
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
+
*)
746
1038
type identity_changes_response = {
747
-
account_id : id;
748
-
old_state : string;
749
-
new_state : string;
750
-
has_more_changes : bool;
751
-
created : id list;
752
-
updated : id list;
753
-
destroyed : id list;
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 *)
754
1046
}
755
1047
756
-
(** Identity/set request arguments. See RFC8621 Section 6.3. *)
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
+
*)
757
1052
type identity_set_arguments = {
758
-
account_id : id;
759
-
if_in_state : string option;
760
-
create : (id * identity_creation) list option;
761
-
update : (id * identity_update) list option;
762
-
destroy : id list option;
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 *)
763
1058
}
764
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
+
*)
765
1064
and identity_creation = {
766
-
name : string;
767
-
email : string;
768
-
reply_to : email_address list option;
769
-
bcc : email_address list option;
770
-
text_signature : string option;
771
-
html_signature : string option;
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 *)
772
1071
}
773
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
+
*)
774
1077
and identity_update = {
775
-
name : string option;
776
-
email : string option;
777
-
reply_to : email_address list option;
778
-
bcc : email_address list option;
779
-
text_signature : string option;
780
-
html_signature : string option;
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 *)
781
1084
}
782
1085
783
-
(** Identity/set response. See RFC8621 Section 6.3. *)
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
+
*)
784
1090
type identity_set_response = {
785
-
account_id : id;
786
-
old_state : string option;
787
-
new_state : string;
788
-
created : (id * identity) list option;
789
-
updated : id list option;
790
-
destroyed : id list option;
791
-
not_created : (id * set_error) list option;
792
-
not_updated : (id * set_error) list option;
793
-
not_destroyed : (id * set_error) list option;
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 *)
794
1100
}
795
1101
796
-
(** {1:vacation_response VacationResponse objects} *)
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
+
*)
797
1106
798
-
(** Vacation auto-reply setting. See RFC8621 Section 7. *)
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
+
*)
799
1111
type vacation_response = {
800
-
id : id;
801
-
is_enabled : bool;
802
-
from_date : utc_date option;
803
-
to_date : utc_date option;
804
-
subject : string option;
805
-
text_body : string option;
806
-
html_body : string option;
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 *)
807
1119
}
808
1120
809
-
(** VacationResponse/get request arguments. See RFC8621 Section 7.2. *)
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
+
*)
810
1125
type vacation_response_get_arguments = {
811
-
account_id : id;
812
-
ids : id list option;
813
-
properties : string list option;
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 *)
814
1129
}
815
1130
816
-
(** VacationResponse/get response. See RFC8621 Section 7.2. *)
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
+
*)
817
1135
type vacation_response_get_response = {
818
-
account_id : id;
819
-
state : string;
820
-
list : vacation_response list;
821
-
not_found : id list;
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 *)
822
1140
}
823
1141
824
-
(** VacationResponse/set request arguments. See RFC8621 Section 7.3. *)
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
+
*)
825
1146
type vacation_response_set_arguments = {
826
-
account_id : id;
827
-
if_in_state : string option;
828
-
update : (id * vacation_response_update) list;
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 *)
829
1150
}
830
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
+
*)
831
1156
and vacation_response_update = {
832
-
is_enabled : bool option;
833
-
from_date : utc_date option;
834
-
to_date : utc_date option;
835
-
subject : string option;
836
-
text_body : string option;
837
-
html_body : string option;
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 *)
838
1163
}
839
1164
840
-
(** VacationResponse/set response. See RFC8621 Section 7.3. *)
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
+
*)
841
1169
type vacation_response_set_response = {
842
-
account_id : id;
843
-
old_state : string option;
844
-
new_state : string;
845
-
updated : id list option;
846
-
not_updated : (id * set_error) list option;
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 *)
847
1175
}
848
1176
849
-
(** {1:message_flags Message Flags and Mailbox Attributes} *)
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
+
*)
850
1181
851
-
(** Flag color defined by the combination of MailFlagBit0, MailFlagBit1, and MailFlagBit2 keywords *)
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
+
*)
852
1186
type flag_color =
853
-
| Red (** Bit pattern 000 *)
854
-
| Orange (** Bit pattern 100 *)
855
-
| Yellow (** Bit pattern 010 *)
856
-
| Green (** Bit pattern 111 *)
857
-
| Blue (** Bit pattern 001 *)
858
-
| Purple (** Bit pattern 101 *)
859
-
| Gray (** Bit pattern 011 *)
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 *)
860
1194
861
-
(** Standard message keywords as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 *)
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
+
*)
862
1199
type message_keyword =
863
1200
| Notify (** Indicate a notification should be shown for this message *)
864
1201
| Muted (** User is not interested in future replies to this thread *)
···
879
1216
| MailFlagBit2 (** Bit 2 of the 3-bit flag color pattern *)
880
1217
| OtherKeyword of string (** Other non-standard keywords *)
881
1218
882
-
(** Special mailbox attribute names as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 *)
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
+
*)
883
1223
type mailbox_attribute =
884
1224
| Snoozed (** Mailbox containing messages that have been snoozed *)
885
1225
| Scheduled (** Mailbox containing messages scheduled to be sent later *)
886
1226
| Memos (** Mailbox containing messages with the $memo keyword *)
887
1227
| OtherAttribute of string (** Other non-standard mailbox attributes *)
888
1228
889
-
(** Functions for working with flag colors *)
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
+
*)
890
1235
val flag_color_of_bits : bool -> bool -> bool -> flag_color
891
1236
892
-
(** Get bits for a flag color *)
1237
+
(** Get the bit values for a flag color
1238
+
@param color The flag color
1239
+
@return Tuple of (bit2, bit1, bit0) values
1240
+
*)
893
1241
val bits_of_flag_color : flag_color -> bool * bool * bool
894
1242
895
-
(** Check if a message has a flag color based on its keywords *)
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
+
*)
896
1247
val has_flag_color : (keyword * bool) list -> bool
897
1248
898
-
(** Get the flag color from a message's keywords, if present *)
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
+
*)
899
1253
val get_flag_color : (keyword * bool) list -> flag_color option
900
1254
901
-
(** Convert a message keyword to its string representation *)
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
+
*)
902
1259
val string_of_message_keyword : message_keyword -> string
903
1260
904
-
(** Parse a string into a message keyword *)
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
+
*)
905
1265
val message_keyword_of_string : string -> message_keyword
906
1266
907
-
(** Convert a mailbox attribute to its string representation *)
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
+
*)
908
1271
val string_of_mailbox_attribute : mailbox_attribute -> string
909
1272
910
-
(** Parse a string into a mailbox attribute *)
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
+
*)
911
1277
val mailbox_attribute_of_string : string -> mailbox_attribute
912
1278
913
-
(** Get a human-readable representation of a flag color *)
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
+
*)
914
1283
val human_readable_flag_color : flag_color -> string
915
1284
916
-
(** Get a human-readable representation of a message keyword *)
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
+
*)
917
1289
val human_readable_message_keyword : message_keyword -> string
918
1290
919
-
(** Format email keywords into a human-readable string representation *)
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
+
*)
920
1295
val format_email_keywords : (keyword * bool) list -> string
921
1296
end
922
1297
923
-
(** {1 JSON serialization} *)
1298
+
(** {1 JSON serialization}
1299
+
Functions for serializing and deserializing JMAP Mail objects to/from JSON
1300
+
*)
924
1301
925
1302
module Json : sig
926
1303
open Types
927
1304
928
-
(** {2 Helper functions for serialization} *)
1305
+
(** {2 Helper functions for serialization}
1306
+
Utility functions for converting between OCaml types and JSON representation
1307
+
*)
929
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
+
*)
930
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
+
*)
931
1319
val mailbox_role_of_string : string -> mailbox_role
932
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
+
*)
933
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
+
*)
934
1331
val keyword_of_string : string -> keyword
935
1332
936
-
(** {2 Mailbox serialization} *)
1333
+
(** {2 Mailbox serialization}
1334
+
Functions for serializing and deserializing mailbox objects
1335
+
*)
937
1336
938
1337
(** TODO:claude - Need to implement all JSON serialization functions
939
1338
for each type we've defined. This would be a substantial amount of
···
948
1347
*)
949
1348
end
950
1349
951
-
(** {1 API functions} *)
1350
+
(** {1 API functions}
1351
+
High-level functions for interacting with JMAP Mail servers
1352
+
*)
952
1353
953
1354
(** Authentication credentials for a JMAP server *)
954
1355
type credentials = {
955
-
username: string;
956
-
password: string;
1356
+
username: string; (** Username for authentication *)
1357
+
password: string; (** Password for authentication *)
957
1358
}
958
1359
959
1360
(** Connection to a JMAP mail server *)
960
1361
type connection = {
961
-
session: Jmap.Types.session;
962
-
config: Jmap.Api.config;
1362
+
session: Jmap.Types.session; (** Session information from the server *)
1363
+
config: Jmap.Api.config; (** Configuration for API requests *)
963
1364
}
964
1365
965
1366
(** Login to a JMAP server and establish a connection
966
1367
@param uri The URI of the JMAP server
967
1368
@param credentials Authentication credentials
968
-
@return A connection object if successful
1369
+
@return A connection object if successful
969
1370
970
-
TODO:claude *)
1371
+
Creates a new connection to a JMAP server using username/password authentication.
1372
+
*)
971
1373
val login :
972
1374
uri:string ->
973
1375
credentials:credentials ->
···
978
1380
@param api_token The API token for authentication
979
1381
@return A connection object if successful
980
1382
981
-
TODO:claude *)
1383
+
Creates a new connection to a JMAP server using Bearer token authentication.
1384
+
*)
982
1385
val login_with_token :
983
1386
uri:string ->
984
1387
api_token:string ->
···
989
1392
@param account_id The account ID to get mailboxes for
990
1393
@return A list of mailboxes if successful
991
1394
992
-
TODO:claude *)
1395
+
Retrieves all mailboxes (folders) in the specified account.
1396
+
*)
993
1397
val get_mailboxes :
994
1398
connection ->
995
1399
account_id:Jmap.Types.id ->
···
1001
1405
@param mailbox_id The mailbox ID to retrieve
1002
1406
@return The mailbox if found
1003
1407
1004
-
TODO:claude *)
1408
+
Retrieves a single mailbox by its ID.
1409
+
*)
1005
1410
val get_mailbox :
1006
1411
connection ->
1007
1412
account_id:Jmap.Types.id ->
···
1015
1420
@param limit Optional limit on number of messages to return
1016
1421
@return The list of email messages if successful
1017
1422
1018
-
TODO:claude *)
1423
+
Retrieves email messages in the specified mailbox, with optional limit.
1424
+
*)
1019
1425
val get_messages_in_mailbox :
1020
1426
connection ->
1021
1427
account_id:Jmap.Types.id ->
···
1030
1436
@param email_id The email ID to retrieve
1031
1437
@return The email message if found
1032
1438
1033
-
TODO:claude *)
1439
+
Retrieves a single email message by its ID.
1440
+
*)
1034
1441
val get_email :
1035
1442
connection ->
1036
1443
account_id:Jmap.Types.id ->
···
1042
1449
@param keyword The message keyword to look for
1043
1450
@return true if the email has the keyword, false otherwise
1044
1451
1045
-
TODO:claude *)
1452
+
Tests whether an email has a particular keyword (flag) set.
1453
+
*)
1046
1454
val has_message_keyword :
1047
1455
Types.email ->
1048
1456
Types.message_keyword ->
···
1055
1463
@param keyword The message keyword to add
1056
1464
@return Success or error
1057
1465
1058
-
TODO:claude *)
1466
+
Adds a keyword (flag) to an email message.
1467
+
*)
1059
1468
val add_message_keyword :
1060
1469
connection ->
1061
1470
account_id:Jmap.Types.id ->
···
1070
1479
@param color The flag color to set
1071
1480
@return Success or error
1072
1481
1073
-
TODO:claude *)
1482
+
Sets a flag color on an email message by setting the appropriate bit flags.
1483
+
*)
1074
1484
val set_flag_color :
1075
1485
connection ->
1076
1486
account_id:Jmap.Types.id ->
···
1082
1492
@param email The email to analyze
1083
1493
@return List of message keywords
1084
1494
1085
-
TODO:claude *)
1495
+
Extracts all message keywords from an email's keyword list.
1496
+
*)
1086
1497
val get_message_keywords :
1087
1498
Types.email ->
1088
1499
Types.message_keyword list
···
1094
1505
@param limit Optional limit on number of emails to return
1095
1506
@return List of emails with the keyword if successful
1096
1507
1097
-
TODO:claude *)
1508
+
Retrieves all emails that have a specific keyword (flag) set.
1509
+
*)
1098
1510
val get_emails_with_keyword :
1099
1511
connection ->
1100
1512
account_id:Jmap.Types.id ->
···
1103
1515
unit ->
1104
1516
(Types.email list, Jmap.Api.error) result Lwt.t
1105
1517
1106
-
(** {1 Email Address Utilities} *)
1518
+
(** {1 Email Address Utilities}
1519
+
Utilities for working with email addresses
1520
+
*)
1107
1521
1108
1522
(** Check if an email address matches a filter string
1109
1523
@param email The email address to check
···
1122
1536
@param email The email object to check
1123
1537
@param pattern The sender filter pattern
1124
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.
1125
1541
*)
1126
1542
val email_matches_sender : Types.email -> string -> bool