···
+
(** Implementation of the JMAP Mail extension, as defined in RFC8621
+
@see <https://datatracker.ietf.org/doc/html/rfc8621> RFC8621
+
This module implements the JMAP Mail specification, providing types and
+
functions for working with emails, mailboxes, threads, and other mail-related
+
objects in the JMAP protocol.
+
(** Module for managing JMAP Mail-specific capability URIs as defined in RFC8621 Section 1.3
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3> RFC8621 Section 1.3
+
(** Mail capability URI as defined in RFC8621 Section 1.3
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+
(** Submission capability URI as defined in RFC8621 Section 1.3
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
val submission_uri : string
+
(** Vacation response capability URI as defined in RFC8621 Section 1.3
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
val vacation_response_uri : string
+
(** All mail extension capability types as defined in RFC8621 Section 1.3
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+
| Mail (** Mail capability for emails and mailboxes *)
+
| Submission (** Submission capability for sending emails *)
+
| VacationResponse (** Vacation response capability for auto-replies *)
+
| Extension of string (** Custom extension capabilities *)
+
(** Convert capability to URI string
+
@param capability The capability to convert
+
@return The full URI string for the capability
val to_string : t -> string
+
(** Parse a string to a capability
+
@param uri The capability URI string to parse
+
@return The parsed capability type
val of_string : string -> t
+
(** Check if a capability is a standard mail capability
+
@param capability The capability to check
+
@return True if the capability is a standard JMAP Mail capability
val is_standard : t -> bool
+
(** Check if a capability string is a standard mail capability
+
@param uri The capability URI string to check
+
@return True if the string represents a standard JMAP Mail capability
val is_standard_string : string -> bool
+
(** Create a list of capability strings
+
@param capabilities List of capability types
+
@return List of capability URI strings
val strings_of_capabilities : t list -> string list
+
(** Types for the JMAP Mail extension as defined in RFC8621
+
@see <https://datatracker.ietf.org/doc/html/rfc8621>
+
(** {1 Mail capabilities}
+
Capability URIs for JMAP Mail extension as defined in RFC8621 Section 1.3
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+
(** Capability URI for JMAP Mail as defined in RFC8621 Section 1.3
+
Identifies support for the Mail data model
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
val capability_mail : string
+
(** Capability URI for JMAP Submission as defined in RFC8621 Section 1.3
+
Identifies support for email submission
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
val capability_submission : string
+
(** Capability URI for JMAP Vacation Response as defined in RFC8621 Section 1.3
+
Identifies support for vacation auto-reply functionality
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
val capability_vacation_response : string
+
(** {1:mailbox Mailbox objects}
+
Mailbox types as defined in RFC8621 Section 2
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
+
(** A role for a mailbox as defined in RFC8621 Section 2.
+
Standardized roles for special mailboxes like Inbox, Sent, etc.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
+
| All (** All mail mailbox *)
+
| Archive (** Archived mail mailbox *)
+
| Drafts (** Draft messages mailbox *)
+
| Flagged (** Starred/flagged mail mailbox *)
+
| Important (** Important mail mailbox *)
+
| Inbox (** Primary inbox mailbox *)
+
| Junk (** Spam/Junk mail mailbox *)
+
| Sent (** Sent mail mailbox *)
+
| Trash (** Deleted/Trash mail mailbox *)
+
| Unknown of string (** Server-specific custom roles *)
+
(** A mailbox (folder) in a mail account as defined in RFC8621 Section 2.
+
Represents an email folder or label in the account.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
+
id : id; (** Server-assigned ID for the mailbox *)
+
name : string; (** User-visible name for the mailbox *)
+
parent_id : id option; (** ID of the parent mailbox, if any *)
+
role : mailbox_role option; (** The role of this mailbox, if it's a special mailbox *)
+
sort_order : unsigned_int; (** Position for mailbox in the UI *)
+
total_emails : unsigned_int; (** Total number of emails in the mailbox *)
+
unread_emails : unsigned_int; (** Number of unread emails in the mailbox *)
+
total_threads : unsigned_int; (** Total number of threads in the mailbox *)
+
unread_threads : unsigned_int; (** Number of threads with unread emails *)
+
is_subscribed : bool; (** Has the user subscribed to this mailbox *)
+
my_rights : mailbox_rights; (** Access rights for the user on this mailbox *)
+
(** Rights for a mailbox as defined in RFC8621 Section 2.
+
Determines the operations a user can perform on a mailbox.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
+
may_read_items : bool; (** Can the user read messages in this mailbox *)
+
may_add_items : bool; (** Can the user add messages to this mailbox *)
+
may_remove_items : bool; (** Can the user remove messages from this mailbox *)
+
may_set_seen : bool; (** Can the user mark messages as read/unread *)
+
may_set_keywords : bool; (** Can the user set keywords/flags on messages *)
+
may_create_child : bool; (** Can the user create child mailboxes *)
+
may_rename : bool; (** Can the user rename this mailbox *)
+
may_delete : bool; (** Can the user delete this mailbox *)
+
may_submit : bool; (** Can the user submit messages in this mailbox for delivery *)
+
(** Filter condition for mailbox queries as defined in RFC8621 Section 2.3.
+
Used to filter mailboxes in queries.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
type mailbox_filter_condition = {
+
parent_id : id option; (** Only include mailboxes with this parent *)
+
name : string option; (** Only include mailboxes with this name (case-insensitive substring match) *)
+
role : string option; (** Only include mailboxes with this role *)
+
has_any_role : bool option; (** If true, only include mailboxes with a role, if false those without *)
+
is_subscribed : bool option; (** If true, only include subscribed mailboxes, if false unsubscribed *)
+
(** Filter for mailbox queries as defined in RFC8621 Section 2.3.
+
Complex filter for Mailbox/query method.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
type mailbox_query_filter = [
+
| `And of mailbox_query_filter list (** Logical AND of filters *)
+
| `Or of mailbox_query_filter list (** Logical OR of filters *)
+
| `Not of mailbox_query_filter (** Logical NOT of a filter *)
+
| `Condition of mailbox_filter_condition (** Simple condition filter *)
+
(** Mailbox/get request arguments as defined in RFC8621 Section 2.1.
+
Used to fetch mailboxes by ID.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.1>
type mailbox_get_arguments = {
+
account_id : id; (** The account to fetch mailboxes from *)
+
ids : id list option; (** The IDs of mailboxes to fetch, null means all *)
+
properties : string list option; (** Properties to return, null means all *)
+
(** Mailbox/get response as defined in RFC8621 Section 2.1.
+
Contains requested mailboxes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.1>
type mailbox_get_response = {
+
account_id : id; (** The account from which mailboxes were fetched *)
+
state : string; (** A string representing the state on the server *)
+
list : mailbox list; (** The list of mailboxes requested *)
+
not_found : id list; (** IDs requested that could not be found *)
+
(** Mailbox/changes request arguments as defined in RFC8621 Section 2.2.
+
Used to get mailbox changes since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.2>
type mailbox_changes_arguments = {
+
account_id : id; (** The account to get changes for *)
+
since_state : string; (** The previous state to compare to *)
+
max_changes : unsigned_int option; (** Maximum number of changes to return *)
+
(** Mailbox/changes response as defined in RFC8621 Section 2.2.
+
Reports mailboxes that have changed since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.2>
type mailbox_changes_response = {
+
account_id : id; (** The account changes are for *)
+
old_state : string; (** The state provided in the request *)
+
new_state : string; (** The current state on the server *)
+
has_more_changes : bool; (** If true, more changes are available *)
+
created : id list; (** IDs of mailboxes created since old_state *)
+
updated : id list; (** IDs of mailboxes updated since old_state *)
+
destroyed : id list; (** IDs of mailboxes destroyed since old_state *)
+
(** Mailbox/query request arguments as defined in RFC8621 Section 2.3.
+
Used to query mailboxes based on filter criteria.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
type mailbox_query_arguments = {
+
account_id : id; (** The account to query *)
+
filter : mailbox_query_filter option; (** Filter to match mailboxes against *)
+
sort : [ `name | `role | `sort_order ] list option; (** Sort criteria *)
+
limit : unsigned_int option; (** Maximum number of results to return *)
+
(** Mailbox/query response as defined in RFC8621 Section 2.3.
+
Contains IDs of mailboxes matching the query.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
type mailbox_query_response = {
+
account_id : id; (** The account that was queried *)
+
query_state : string; (** State string for the query results *)
+
can_calculate_changes : bool; (** Whether queryChanges can be used with these results *)
+
position : unsigned_int; (** Zero-based index of the first result *)
+
ids : id list; (** IDs of mailboxes matching the query *)
+
total : unsigned_int option; (** Total number of matches if requested *)
+
(** Mailbox/queryChanges request arguments as defined in RFC8621 Section 2.4.
+
Used to get changes to mailbox query results.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
type mailbox_query_changes_arguments = {
+
account_id : id; (** The account to query *)
+
filter : mailbox_query_filter option; (** Same filter as the original query *)
+
sort : [ `name | `role | `sort_order ] list option; (** Same sort as the original query *)
+
since_query_state : string; (** The query_state from the previous result *)
+
max_changes : unsigned_int option; (** Maximum number of changes to return *)
+
up_to_id : id option; (** ID of the last mailbox to check for changes *)
+
(** Mailbox/queryChanges response as defined in RFC8621 Section 2.4.
+
Reports changes to a mailbox query since the previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
type mailbox_query_changes_response = {
+
account_id : id; (** The account that was queried *)
+
old_query_state : string; (** The query_state from the request *)
+
new_query_state : string; (** The current query_state on the server *)
+
total : unsigned_int option; (** Updated total number of matches, if requested *)
+
removed : id list; (** IDs that were in the old results but not the new *)
+
added : mailbox_query_changes_added list; (** IDs that are in the new results but not the old *)
+
(** Added item in mailbox query changes as defined in RFC8621 Section 2.4.
+
Represents a mailbox added to query results.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
and mailbox_query_changes_added = {
+
id : id; (** ID of the added mailbox *)
+
index : unsigned_int; (** Zero-based index of the added mailbox in the results *)
+
(** Mailbox/set request arguments as defined in RFC8621 Section 2.5.
+
Used to create, update, and destroy mailboxes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
type mailbox_set_arguments = {
+
account_id : id; (** The account to make changes in *)
+
if_in_state : string option; (** Only apply changes if in this state *)
+
create : (id * mailbox_creation) list option; (** Map of creation IDs to mailboxes to create *)
+
update : (id * mailbox_update) list option; (** Map of IDs to update properties *)
+
destroy : id list option; (** List of IDs to destroy *)
+
(** Properties for mailbox creation as defined in RFC8621 Section 2.5.
+
Used to create new mailboxes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
+
name : string; (** Name for the new mailbox *)
+
parent_id : id option; (** ID of the parent mailbox, if any *)
+
role : string option; (** Role for the mailbox, if it's a special-purpose mailbox *)
+
sort_order : unsigned_int option; (** Sort order, defaults to 0 *)
+
is_subscribed : bool option; (** Whether the mailbox is subscribed, defaults to true *)
+
(** Properties for mailbox update as defined in RFC8621 Section 2.5.
+
Used to update existing mailboxes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
+
name : string option; (** New name for the mailbox *)
+
parent_id : id option; (** New parent ID for the mailbox *)
+
role : string option; (** New role for the mailbox *)
+
sort_order : unsigned_int option; (** New sort order for the mailbox *)
+
is_subscribed : bool option; (** New subscription status for the mailbox *)
+
(** Mailbox/set response as defined in RFC8621 Section 2.5.
+
Reports the results of mailbox changes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
type mailbox_set_response = {
+
account_id : id; (** The account that was modified *)
+
old_state : string option; (** The state before processing, if changed *)
+
new_state : string; (** The current state on the server *)
+
created : (id * mailbox) list option; (** Map of creation IDs to created mailboxes *)
+
updated : id list option; (** List of IDs that were successfully updated *)
+
destroyed : id list option; (** List of IDs that were successfully destroyed *)
+
not_created : (id * set_error) list option; (** Map of IDs to errors for failed creates *)
+
not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
+
not_destroyed : (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
+
(** {1:thread Thread objects}
+
Thread types as defined in RFC8621 Section 3
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-3>
+
(** A thread in a mail account as defined in RFC8621 Section 3.
+
Represents a group of related email messages.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-3>
+
id : id; (** Server-assigned ID for the thread *)
+
email_ids : id list; (** IDs of emails in the thread *)
+
(** Thread/get request arguments as defined in RFC8621 Section 3.1.
+
Used to fetch threads by ID.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.1>
type thread_get_arguments = {
+
account_id : id; (** The account to fetch threads from *)
+
ids : id list option; (** The IDs of threads to fetch, null means all *)
+
properties : string list option; (** Properties to return, null means all *)
+
(** Thread/get response as defined in RFC8621 Section 3.1.
+
Contains requested threads.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.1>
type thread_get_response = {
+
account_id : id; (** The account from which threads were fetched *)
+
state : string; (** A string representing the state on the server *)
+
list : thread list; (** The list of threads requested *)
+
not_found : id list; (** IDs requested that could not be found *)
+
(** Thread/changes request arguments as defined in RFC8621 Section 3.2.
+
Used to get thread changes since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.2>
type thread_changes_arguments = {
+
account_id : id; (** The account to get changes for *)
+
since_state : string; (** The previous state to compare to *)
+
max_changes : unsigned_int option; (** Maximum number of changes to return *)
+
(** Thread/changes response as defined in RFC8621 Section 3.2.
+
Reports threads that have changed since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.2>
type thread_changes_response = {
+
account_id : id; (** The account changes are for *)
+
old_state : string; (** The state provided in the request *)
+
new_state : string; (** The current state on the server *)
+
has_more_changes : bool; (** If true, more changes are available *)
+
created : id list; (** IDs of threads created since old_state *)
+
updated : id list; (** IDs of threads updated since old_state *)
+
destroyed : id list; (** IDs of threads destroyed since old_state *)
+
(** {1:email Email objects}
+
Email types as defined in RFC8621 Section 4
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4>
+
(** Addressing (mailbox) information as defined in RFC8621 Section 4.1.1.
+
Represents an email address with optional display name.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.1>
+
name : string option; (** Display name of the mailbox (e.g., "John Doe") *)
+
email : string; (** The email address (e.g., "john@example.com") *)
+
parameters : (string * string) list; (** Additional parameters for the address *)
+
(** Message header field as defined in RFC8621 Section 4.1.2.
+
Represents an email header.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.2>
+
name : string; (** Name of the header field (e.g., "Subject") *)
+
value : string; (** Value of the header field *)
+
(** Email keyword (flag) as defined in RFC8621 Section 4.3.
+
Represents a flag or tag on an email message.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.3>
+
| Flagged (** Message is flagged/starred *)
+
| Answered (** Message has been replied to *)
+
| Draft (** Message is a draft *)
+
| Forwarded (** Message has been forwarded *)
+
| Phishing (** Message has been reported as phishing *)
+
| Junk (** Message is spam/junk *)
+
| NotJunk (** Message is explicitly not spam *)
+
| Seen (** Message has been read *)
+
| Unread (** Message is unread (inverse of $seen) *)
+
| Custom of string (** Custom/non-standard keywords *)
+
(** Email message as defined in RFC8621 Section 4.
+
Represents an email message in a mail account.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4>
+
id : id; (** Server-assigned ID for the message *)
+
blob_id : id; (** ID of the raw message content blob *)
+
thread_id : id; (** ID of the thread this message belongs to *)
+
mailbox_ids : (id * bool) list; (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
+
keywords : (keyword * bool) list; (** Map of keywords to boolean (whether message has keyword) *)
+
size : unsigned_int; (** Size of the message in octets *)
+
received_at : utc_date; (** When the message was received by the server *)
+
message_id : string list; (** Message-ID header values *)
+
in_reply_to : string list option; (** In-Reply-To header values *)
+
references : string list option; (** References header values *)
+
sender : email_address list option; (** Sender header addresses *)
+
from : email_address list option; (** From header addresses *)
+
to_ : email_address list option; (** To header addresses *)
+
cc : email_address list option; (** Cc header addresses *)
+
bcc : email_address list option; (** Bcc header addresses *)
+
reply_to : email_address list option; (** Reply-To header addresses *)
+
subject : string option; (** Subject header value *)
+
sent_at : utc_date option; (** Date header value as a date-time *)
+
has_attachment : bool option; (** Does the message have any attachments *)
+
preview : string option; (** Preview of the message (first bit of text) *)
+
body_values : (string * string) list option; (** Map of part IDs to text content *)
+
text_body : email_body_part list option; (** Plain text message body parts *)
+
html_body : email_body_part list option; (** HTML message body parts *)
+
attachments : email_body_part list option; (** Attachment parts in the message *)
+
headers : header list option; (** All headers in the message *)
+
(** Email body part as defined in RFC8621 Section 4.1.4.
+
Represents a MIME part in an email message.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.4>
+
part_id : string option; (** Server-assigned ID for the MIME part *)
+
blob_id : id option; (** ID of the raw content for this part *)
+
size : unsigned_int option; (** Size of the part in octets *)
+
headers : header list option; (** Headers for this MIME part *)
+
name : string option; (** Filename of this part, if any *)
+
type_ : string option; (** MIME type of the part *)
+
charset : string option; (** Character set of the part, if applicable *)
+
disposition : string option; (** Content-Disposition value *)
+
cid : string option; (** Content-ID value *)
+
language : string list option; (** Content-Language values *)
+
location : string option; (** Content-Location value *)
+
sub_parts : email_body_part list option; (** Child MIME parts for multipart types *)
+
header_parameter_name : string option; (** Header parameter name (for headers with parameters) *)
+
header_parameter_value : string option; (** Header parameter value (for headers with parameters) *)
+
(** Email query filter condition as defined in RFC8621 Section 4.4.
+
Specifies conditions for filtering emails in queries.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
type email_filter_condition = {
+
in_mailbox : id option; (** Only include emails in this mailbox *)
+
in_mailbox_other_than : id list option; (** Only include emails not in these mailboxes *)
+
min_size : unsigned_int option; (** Only include emails of at least this size in octets *)
+
max_size : unsigned_int option; (** Only include emails of at most this size in octets *)
+
before : utc_date option; (** Only include emails received before this date-time *)
+
after : utc_date option; (** Only include emails received after this date-time *)
+
header : (string * string) option; (** Only include emails with header matching value (name, value) *)
+
from : string option; (** Only include emails with From containing this text *)
+
to_ : string option; (** Only include emails with To containing this text *)
+
cc : string option; (** Only include emails with CC containing this text *)
+
bcc : string option; (** Only include emails with BCC containing this text *)
+
subject : string option; (** Only include emails with Subject containing this text *)
+
body : string option; (** Only include emails with body containing this text *)
+
has_keyword : string option; (** Only include emails with this keyword *)
+
not_keyword : string option; (** Only include emails without this keyword *)
+
has_attachment : bool option; (** If true, only include emails with attachments *)
+
text : string option; (** Only include emails with this text in headers or body *)
+
(** Filter for email queries as defined in RFC8621 Section 4.4.
+
Complex filter for Email/query method.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
type email_query_filter = [
+
| `And of email_query_filter list (** Logical AND of filters *)
+
| `Or of email_query_filter list (** Logical OR of filters *)
+
| `Not of email_query_filter (** Logical NOT of a filter *)
+
| `Condition of email_filter_condition (** Simple condition filter *)
+
(** Email/get request arguments as defined in RFC8621 Section 4.5.
+
Used to fetch emails by ID.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.5>
type email_get_arguments = {
+
account_id : id; (** The account to fetch emails from *)
+
ids : id list option; (** The IDs of emails to fetch, null means all *)
+
properties : string list option; (** Properties to return, null means all *)
+
body_properties : string list option; (** Properties to return on body parts *)
+
fetch_text_body_values : bool option; (** Whether to fetch text body content *)
+
fetch_html_body_values : bool option; (** Whether to fetch HTML body content *)
+
fetch_all_body_values : bool option; (** Whether to fetch all body content *)
+
max_body_value_bytes : unsigned_int option; (** Maximum size of body values to return *)
+
(** Email/get response as defined in RFC8621 Section 4.5.
+
Contains requested emails.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.5>
type email_get_response = {
+
account_id : id; (** The account from which emails were fetched *)
+
state : string; (** A string representing the state on the server *)
+
list : email list; (** The list of emails requested *)
+
not_found : id list; (** IDs requested that could not be found *)
+
(** Email/changes request arguments as defined in RFC8621 Section 4.6.
+
Used to get email changes since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.6>
type email_changes_arguments = {
+
account_id : id; (** The account to get changes for *)
+
since_state : string; (** The previous state to compare to *)
+
max_changes : unsigned_int option; (** Maximum number of changes to return *)
+
(** Email/changes response as defined in RFC8621 Section 4.6.
+
Reports emails that have changed since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.6>
type email_changes_response = {
+
account_id : id; (** The account changes are for *)
+
old_state : string; (** The state provided in the request *)
+
new_state : string; (** The current state on the server *)
+
has_more_changes : bool; (** If true, more changes are available *)
+
created : id list; (** IDs of emails created since old_state *)
+
updated : id list; (** IDs of emails updated since old_state *)
+
destroyed : id list; (** IDs of emails destroyed since old_state *)
+
(** Email/query request arguments as defined in RFC8621 Section 4.4.
+
Used to query emails based on filter criteria.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
type email_query_arguments = {
+
account_id : id; (** The account to query *)
+
filter : email_query_filter option; (** Filter to match emails against *)
+
sort : comparator list option; (** Sort criteria *)
+
collapse_threads : bool option; (** Whether to collapse threads in the results *)
+
position : unsigned_int option; (** Zero-based index of first result to return *)
+
anchor : id option; (** ID of email to use as reference point *)
+
anchor_offset : int_t option; (** Offset from anchor to start returning results *)
+
limit : unsigned_int option; (** Maximum number of results to return *)
+
calculate_total : bool option; (** Whether to calculate the total number of matching emails *)
+
(** Email/query response as defined in RFC8621 Section 4.4.
+
Contains IDs of emails matching the query.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
type email_query_response = {
+
account_id : id; (** The account that was queried *)
+
query_state : string; (** State string for the query results *)
+
can_calculate_changes : bool; (** Whether queryChanges can be used with these results *)
+
position : unsigned_int; (** Zero-based index of the first result *)
+
ids : id list; (** IDs of emails matching the query *)
+
total : unsigned_int option; (** Total number of matches if requested *)
+
thread_ids : id list option; (** IDs of threads if collapse_threads was true *)
+
(** Email/queryChanges request arguments as defined in RFC8621 Section 4.7.
+
Used to get changes to email query results.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
type email_query_changes_arguments = {
+
account_id : id; (** The account to query *)
+
filter : email_query_filter option; (** Same filter as the original query *)
+
sort : comparator list option; (** Same sort as the original query *)
+
collapse_threads : bool option; (** Same collapse_threads as the original query *)
+
since_query_state : string; (** The query_state from the previous result *)
+
max_changes : unsigned_int option; (** Maximum number of changes to return *)
+
up_to_id : id option; (** ID of the last email to check for changes *)
+
(** Email/queryChanges response as defined in RFC8621 Section 4.7.
+
Reports changes to an email query since the previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
type email_query_changes_response = {
+
account_id : id; (** The account that was queried *)
+
old_query_state : string; (** The query_state from the request *)
+
new_query_state : string; (** The current query_state on the server *)
+
total : unsigned_int option; (** Updated total number of matches, if requested *)
+
removed : id list; (** IDs that were in the old results but not the new *)
+
added : email_query_changes_added list; (** IDs that are in the new results but not the old *)
+
(** Added item in email query changes as defined in RFC8621 Section 4.7.
+
Represents an email added to query results.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
and email_query_changes_added = {
+
id : id; (** ID of the added email *)
+
index : unsigned_int; (** Zero-based index of the added email in the results *)
+
(** Email/set request arguments as defined in RFC8621 Section 4.8.
+
Used to create, update, and destroy emails.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
type email_set_arguments = {
+
account_id : id; (** The account to make changes in *)
+
if_in_state : string option; (** Only apply changes if in this state *)
+
create : (id * email_creation) list option; (** Map of creation IDs to emails to create *)
+
update : (id * email_update) list option; (** Map of IDs to update properties *)
+
destroy : id list option; (** List of IDs to destroy *)
+
(** Properties for email creation as defined in RFC8621 Section 4.8.
+
Used to create new emails.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
+
mailbox_ids : (id * bool) list; (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
+
keywords : (keyword * bool) list option; (** Map of keywords to boolean (whether message has keyword) *)
+
received_at : utc_date option; (** When the message was received by the server *)
+
message_id : string list option; (** Message-ID header values *)
+
in_reply_to : string list option; (** In-Reply-To header values *)
+
references : string list option; (** References header values *)
+
sender : email_address list option; (** Sender header addresses *)
+
from : email_address list option; (** From header addresses *)
+
to_ : email_address list option; (** To header addresses *)
+
cc : email_address list option; (** Cc header addresses *)
+
bcc : email_address list option; (** Bcc header addresses *)
+
reply_to : email_address list option; (** Reply-To header addresses *)
+
subject : string option; (** Subject header value *)
+
body_values : (string * string) list option; (** Map of part IDs to text content *)
+
text_body : email_body_part list option; (** Plain text message body parts *)
+
html_body : email_body_part list option; (** HTML message body parts *)
+
attachments : email_body_part list option; (** Attachment parts in the message *)
+
headers : header list option; (** All headers in the message *)
+
(** Properties for email update as defined in RFC8621 Section 4.8.
+
Used to update existing emails.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
+
keywords : (keyword * bool) list option; (** New keywords to set on the email *)
+
mailbox_ids : (id * bool) list option; (** New mailboxes to set for the email *)
+
(** Email/set response as defined in RFC8621 Section 4.8.
+
Reports the results of email changes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
type email_set_response = {
+
account_id : id; (** The account that was modified *)
+
old_state : string option; (** The state before processing, if changed *)
+
new_state : string; (** The current state on the server *)
+
created : (id * email) list option; (** Map of creation IDs to created emails *)
+
updated : id list option; (** List of IDs that were successfully updated *)
+
destroyed : id list option; (** List of IDs that were successfully destroyed *)
+
not_created : (id * set_error) list option; (** Map of IDs to errors for failed creates *)
+
not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
+
not_destroyed : (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
+
(** Email/copy request arguments as defined in RFC8621 Section 4.9.
+
Used to copy emails between accounts.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.9>
type email_copy_arguments = {
+
from_account_id : id; (** The account to copy emails from *)
+
account_id : id; (** The account to copy emails to *)
+
create : (id * email_creation) list; (** Map of creation IDs to email creation properties *)
+
on_success_destroy_original : bool option; (** Whether to destroy originals after copying *)
+
(** Email/copy response as defined in RFC8621 Section 4.9.
+
Reports the results of copying emails.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.9>
type email_copy_response = {
+
from_account_id : id; (** The account emails were copied from *)
+
account_id : id; (** The account emails were copied to *)
+
created : (id * email) list option; (** Map of creation IDs to created emails *)
+
not_created : (id * set_error) list option; (** Map of IDs to errors for failed copies *)
+
(** Email/import request arguments as defined in RFC8621 Section 4.10.
+
Used to import raw emails from blobs.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
type email_import_arguments = {
+
account_id : id; (** The account to import emails into *)
+
emails : (id * email_import) list; (** Map of creation IDs to import properties *)
+
(** Properties for email import as defined in RFC8621 Section 4.10.
+
Used to import raw emails from blobs.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
+
blob_id : id; (** ID of the blob containing the raw message *)
+
mailbox_ids : (id * bool) list; (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
+
keywords : (keyword * bool) list option; (** Map of keywords to boolean (whether message has keyword) *)
+
received_at : utc_date option; (** When the message was received, defaults to now *)
+
(** Email/import response as defined in RFC8621 Section 4.10.
+
Reports the results of importing emails.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
type email_import_response = {
+
account_id : id; (** The account emails were imported into *)
+
created : (id * email) list option; (** Map of creation IDs to created emails *)
+
not_created : (id * set_error) list option; (** Map of IDs to errors for failed imports *)
+
(** {1:search_snippet Search snippets}
+
Search snippet types as defined in RFC8621 Section 4.11
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
+
(** SearchSnippet/get request arguments as defined in RFC8621 Section 4.11.
+
Used to get highlighted snippets from emails matching a search.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
type search_snippet_get_arguments = {
+
account_id : id; (** The account to search in *)
+
email_ids : id list; (** The IDs of emails to get snippets for *)
+
filter : email_filter_condition; (** Filter containing the text to find and highlight *)
+
(** SearchSnippet/get response as defined in RFC8621 Section 4.11.
+
Contains search result snippets with highlighted text.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
type search_snippet_get_response = {
+
account_id : id; (** The account that was searched *)
+
list : (id * search_snippet) list; (** Map of email IDs to their search snippets *)
+
not_found : id list; (** IDs for which no snippet could be generated *)
+
(** Search snippet for an email as defined in RFC8621 Section 4.11.
+
Contains highlighted parts of emails matching a search.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
+
subject : string option; (** Subject with search terms highlighted *)
+
preview : string option; (** Email body preview with search terms highlighted *)
+
(** {1:submission EmailSubmission objects}
+
Email submission types as defined in RFC8621 Section 5
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5>
+
(** EmailSubmission address as defined in RFC8621 Section 5.1.
+
Represents an email address for mail submission.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
type submission_address = {
+
email : string; (** The email address (e.g., "john@example.com") *)
+
parameters : (string * string) list option; (** SMTP extension parameters *)
+
(** Email submission object as defined in RFC8621 Section 5.1.
+
Represents an email that has been or will be sent.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
type email_submission = {
+
id : id; (** Server-assigned ID for the submission *)
+
identity_id : id; (** ID of the identity used to send the email *)
+
email_id : id; (** ID of the email to send *)
+
thread_id : id; (** ID of the thread containing the message *)
+
envelope : envelope option; (** SMTP envelope for the message *)
+
send_at : utc_date option; (** When to send the email, null for immediate *)
+
| `pending (** Submission can still be canceled *)
+
| `final (** Submission can no longer be canceled *)
+
| `canceled (** Submission was canceled *)
+
] option; (** Current undo status of the submission *)
+
delivery_status : (string * submission_status) list option; (** Map of recipient to delivery status *)
+
dsn_blob_ids : (string * id) list option; (** Map of recipient to DSN blob ID *)
+
mdn_blob_ids : (string * id) list option; (** Map of recipient to MDN blob ID *)
+
(** Envelope for mail submission as defined in RFC8621 Section 5.1.
+
Represents the SMTP envelope for a message.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
+
mail_from : submission_address; (** Return path for the message *)
+
rcpt_to : submission_address list; (** Recipients for the message *)
+
(** Delivery status for submitted email as defined in RFC8621 Section 5.1.
+
Represents the SMTP status of a delivery attempt.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
and submission_status = {
+
smtp_reply : string; (** SMTP response from the server *)
+
delivered : string option; (** Timestamp when message was delivered, if successful *)
+
(** EmailSubmission/get request arguments as defined in RFC8621 Section 5.3.
+
Used to fetch email submissions by ID.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.3>
type email_submission_get_arguments = {
+
account_id : id; (** The account to fetch submissions from *)
+
ids : id list option; (** The IDs of submissions to fetch, null means all *)
+
properties : string list option; (** Properties to return, null means all *)
+
(** EmailSubmission/get response as defined in RFC8621 Section 5.3.
+
Contains requested email submissions.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.3>
type email_submission_get_response = {
+
account_id : id; (** The account from which submissions were fetched *)
+
state : string; (** A string representing the state on the server *)
+
list : email_submission list; (** The list of submissions requested *)
+
not_found : id list; (** IDs requested that could not be found *)
+
(** EmailSubmission/changes request arguments as defined in RFC8621 Section 5.4.
+
Used to get submission changes since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.4>
type email_submission_changes_arguments = {
+
account_id : id; (** The account to get changes for *)
+
since_state : string; (** The previous state to compare to *)
+
max_changes : unsigned_int option; (** Maximum number of changes to return *)
+
(** EmailSubmission/changes response as defined in RFC8621 Section 5.4.
+
Reports submissions that have changed since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.4>
type email_submission_changes_response = {
+
account_id : id; (** The account changes are for *)
+
old_state : string; (** The state provided in the request *)
+
new_state : string; (** The current state on the server *)
+
has_more_changes : bool; (** If true, more changes are available *)
+
created : id list; (** IDs of submissions created since old_state *)
+
updated : id list; (** IDs of submissions updated since old_state *)
+
destroyed : id list; (** IDs of submissions destroyed since old_state *)
+
(** EmailSubmission/query filter condition as defined in RFC8621 Section 5.5.
+
Specifies conditions for filtering email submissions in queries.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
type email_submission_filter_condition = {
+
identity_id : id option; (** Only include submissions with this identity *)
+
email_id : id option; (** Only include submissions for this email *)
+
thread_id : id option; (** Only include submissions for emails in this thread *)
+
before : utc_date option; (** Only include submissions created before this date-time *)
+
after : utc_date option; (** Only include submissions created after this date-time *)
+
subject : string option; (** Only include submissions with matching subjects *)
+
(** Filter for email submission queries as defined in RFC8621 Section 5.5.
+
Complex filter for EmailSubmission/query method.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
type email_submission_query_filter = [
+
| `And of email_submission_query_filter list (** Logical AND of filters *)
+
| `Or of email_submission_query_filter list (** Logical OR of filters *)
+
| `Not of email_submission_query_filter (** Logical NOT of a filter *)
+
| `Condition of email_submission_filter_condition (** Simple condition filter *)
+
(** EmailSubmission/query request arguments as defined in RFC8621 Section 5.5.
+
Used to query email submissions based on filter criteria.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
type email_submission_query_arguments = {
+
account_id : id; (** The account to query *)
+
filter : email_submission_query_filter option; (** Filter to match submissions against *)
+
sort : comparator list option; (** Sort criteria *)
+
position : unsigned_int option; (** Zero-based index of first result to return *)
+
anchor : id option; (** ID of submission to use as reference point *)
+
anchor_offset : int_t option; (** Offset from anchor to start returning results *)
+
limit : unsigned_int option; (** Maximum number of results to return *)
+
calculate_total : bool option; (** Whether to calculate the total number of matching submissions *)
+
(** EmailSubmission/query response as defined in RFC8621 Section 5.5.
+
Contains IDs of email submissions matching the query.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
type email_submission_query_response = {
+
account_id : id; (** The account that was queried *)
+
query_state : string; (** State string for the query results *)
+
can_calculate_changes : bool; (** Whether queryChanges can be used with these results *)
+
position : unsigned_int; (** Zero-based index of the first result *)
+
ids : id list; (** IDs of email submissions matching the query *)
+
total : unsigned_int option; (** Total number of matches if requested *)
+
(** EmailSubmission/set request arguments as defined in RFC8621 Section 5.6.
+
Used to create, update, and destroy email submissions.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
type email_submission_set_arguments = {
+
account_id : id; (** The account to make changes in *)
+
if_in_state : string option; (** Only apply changes if in this state *)
+
create : (id * email_submission_creation) list option; (** Map of creation IDs to submissions to create *)
+
update : (id * email_submission_update) list option; (** Map of IDs to update properties *)
+
destroy : id list option; (** List of IDs to destroy *)
+
on_success_update_email : (id * email_update) list option; (** Emails to update if submissions succeed *)
+
(** Properties for email submission creation as defined in RFC8621 Section 5.6.
+
Used to create new email submissions.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
and email_submission_creation = {
+
email_id : id; (** ID of the email to send *)
+
identity_id : id; (** ID of the identity to send from *)
+
envelope : envelope option; (** Custom envelope, if needed *)
+
send_at : utc_date option; (** When to send the email, defaults to now *)
+
(** Properties for email submission update as defined in RFC8621 Section 5.6.
+
Used to update existing email submissions.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
and email_submission_update = {
+
email_id : id option; (** New email ID to use for this submission *)
+
identity_id : id option; (** New identity ID to use for this submission *)
+
envelope : envelope option; (** New envelope to use for this submission *)
+
undo_status : [`canceled] option; (** Set to cancel a pending submission *)
+
(** EmailSubmission/set response as defined in RFC8621 Section 5.6.
+
Reports the results of email submission changes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
type email_submission_set_response = {
+
account_id : id; (** The account that was modified *)
+
old_state : string option; (** The state before processing, if changed *)
+
new_state : string; (** The current state on the server *)
+
created : (id * email_submission) list option; (** Map of creation IDs to created submissions *)
+
updated : id list option; (** List of IDs that were successfully updated *)
+
destroyed : id list option; (** List of IDs that were successfully destroyed *)
+
not_created : (id * set_error) list option; (** Map of IDs to errors for failed creates *)
+
not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
+
not_destroyed : (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
+
(** {1:identity Identity objects}
+
Identity types as defined in RFC8621 Section 6
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6>
+
(** Identity for sending mail as defined in RFC8621 Section 6.
+
Represents an email identity that can be used to send messages.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6>
+
id : id; (** Server-assigned ID for the identity *)
+
name : string; (** Display name for the identity *)
+
email : string; (** Email address for the identity *)
+
reply_to : email_address list option; (** Reply-To addresses to use when sending *)
+
bcc : email_address list option; (** BCC addresses to automatically include *)
+
text_signature : string option; (** Plain text signature for the identity *)
+
html_signature : string option; (** HTML signature for the identity *)
+
may_delete : bool; (** Whether this identity can be deleted *)
+
(** Identity/get request arguments as defined in RFC8621 Section 6.1.
+
Used to fetch identities by ID.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.1>
type identity_get_arguments = {
+
account_id : id; (** The account to fetch identities from *)
+
ids : id list option; (** The IDs of identities to fetch, null means all *)
+
properties : string list option; (** Properties to return, null means all *)
+
(** Identity/get response as defined in RFC8621 Section 6.1.
+
Contains requested identities.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.1>
type identity_get_response = {
+
account_id : id; (** The account from which identities were fetched *)
+
state : string; (** A string representing the state on the server *)
+
list : identity list; (** The list of identities requested *)
+
not_found : id list; (** IDs requested that could not be found *)
+
(** Identity/changes request arguments as defined in RFC8621 Section 6.2.
+
Used to get identity changes since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.2>
type identity_changes_arguments = {
+
account_id : id; (** The account to get changes for *)
+
since_state : string; (** The previous state to compare to *)
+
max_changes : unsigned_int option; (** Maximum number of changes to return *)
+
(** Identity/changes response as defined in RFC8621 Section 6.2.
+
Reports identities that have changed since a previous state.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.2>
type identity_changes_response = {
+
account_id : id; (** The account changes are for *)
+
old_state : string; (** The state provided in the request *)
+
new_state : string; (** The current state on the server *)
+
has_more_changes : bool; (** If true, more changes are available *)
+
created : id list; (** IDs of identities created since old_state *)
+
updated : id list; (** IDs of identities updated since old_state *)
+
destroyed : id list; (** IDs of identities destroyed since old_state *)
+
(** Identity/set request arguments as defined in RFC8621 Section 6.3.
+
Used to create, update, and destroy identities.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
type identity_set_arguments = {
+
account_id : id; (** The account to make changes in *)
+
if_in_state : string option; (** Only apply changes if in this state *)
+
create : (id * identity_creation) list option; (** Map of creation IDs to identities to create *)
+
update : (id * identity_update) list option; (** Map of IDs to update properties *)
+
destroy : id list option; (** List of IDs to destroy *)
+
(** Properties for identity creation as defined in RFC8621 Section 6.3.
+
Used to create new identities.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
and identity_creation = {
+
name : string; (** Display name for the identity *)
+
email : string; (** Email address for the identity *)
+
reply_to : email_address list option; (** Reply-To addresses to use when sending *)
+
bcc : email_address list option; (** BCC addresses to automatically include *)
+
text_signature : string option; (** Plain text signature for the identity *)
+
html_signature : string option; (** HTML signature for the identity *)
+
(** Properties for identity update as defined in RFC8621 Section 6.3.
+
Used to update existing identities.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
+
name : string option; (** New display name for the identity *)
+
email : string option; (** New email address for the identity *)
+
reply_to : email_address list option; (** New Reply-To addresses to use *)
+
bcc : email_address list option; (** New BCC addresses to automatically include *)
+
text_signature : string option; (** New plain text signature *)
+
html_signature : string option; (** New HTML signature *)
+
(** Identity/set response as defined in RFC8621 Section 6.3.
+
Reports the results of identity changes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
type identity_set_response = {
+
account_id : id; (** The account that was modified *)
+
old_state : string option; (** The state before processing, if changed *)
+
new_state : string; (** The current state on the server *)
+
created : (id * identity) list option; (** Map of creation IDs to created identities *)
+
updated : id list option; (** List of IDs that were successfully updated *)
+
destroyed : id list option; (** List of IDs that were successfully destroyed *)
+
not_created : (id * set_error) list option; (** Map of IDs to errors for failed creates *)
+
not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
+
not_destroyed : (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
+
(** {1:vacation_response VacationResponse objects}
+
Vacation response types as defined in RFC8621 Section 7
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-7>
+
(** Vacation auto-reply setting as defined in RFC8621 Section 7.
+
Represents an automatic vacation/out-of-office response.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-7>
type vacation_response = {
+
id : id; (** Server-assigned ID for the vacation response *)
+
is_enabled : bool; (** Whether the vacation response is active *)
+
from_date : utc_date option; (** Start date-time of the vacation period *)
+
to_date : utc_date option; (** End date-time of the vacation period *)
+
subject : string option; (** Subject line for the vacation response *)
+
text_body : string option; (** Plain text body for the vacation response *)
+
html_body : string option; (** HTML body for the vacation response *)
+
(** VacationResponse/get request arguments as defined in RFC8621 Section 7.2.
+
Used to fetch vacation responses by ID.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.2>
type vacation_response_get_arguments = {
+
account_id : id; (** The account to fetch vacation responses from *)
+
ids : id list option; (** The IDs of vacation responses to fetch, null means all *)
+
properties : string list option; (** Properties to return, null means all *)
+
(** VacationResponse/get response as defined in RFC8621 Section 7.2.
+
Contains requested vacation responses.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.2>
type vacation_response_get_response = {
+
account_id : id; (** The account from which vacation responses were fetched *)
+
state : string; (** A string representing the state on the server *)
+
list : vacation_response list; (** The list of vacation responses requested *)
+
not_found : id list; (** IDs requested that could not be found *)
+
(** VacationResponse/set request arguments as defined in RFC8621 Section 7.3.
+
Used to update vacation responses.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
type vacation_response_set_arguments = {
+
account_id : id; (** The account to make changes in *)
+
if_in_state : string option; (** Only apply changes if in this state *)
+
update : (id * vacation_response_update) list; (** Map of IDs to update properties *)
+
(** Properties for vacation response update as defined in RFC8621 Section 7.3.
+
Used to update existing vacation responses.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
and vacation_response_update = {
+
is_enabled : bool option; (** Whether the vacation response is active *)
+
from_date : utc_date option; (** Start date-time of the vacation period *)
+
to_date : utc_date option; (** End date-time of the vacation period *)
+
subject : string option; (** Subject line for the vacation response *)
+
text_body : string option; (** Plain text body for the vacation response *)
+
html_body : string option; (** HTML body for the vacation response *)
+
(** VacationResponse/set response as defined in RFC8621 Section 7.3.
+
Reports the results of vacation response changes.
+
@see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
type vacation_response_set_response = {
+
account_id : id; (** The account that was modified *)
+
old_state : string option; (** The state before processing, if changed *)
+
new_state : string; (** The current state on the server *)
+
updated : id list option; (** List of IDs that were successfully updated *)
+
not_updated : (id * set_error) list option; (** Map of IDs to errors for failed updates *)
+
(** {1:message_flags Message Flags and Mailbox Attributes}
+
Message flag types as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02
+
@see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute>
+
(** Flag color defined by the combination of MailFlagBit0, MailFlagBit1, and MailFlagBit2 keywords
+
as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 3.
+
@see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-3>
+
| Red (** Bit pattern 000 - default color *)
+
| Orange (** Bit pattern 100 - MailFlagBit2 set *)
+
| Yellow (** Bit pattern 010 - MailFlagBit1 set *)
+
| Green (** Bit pattern 111 - all bits set *)
+
| Blue (** Bit pattern 001 - MailFlagBit0 set *)
+
| Purple (** Bit pattern 101 - MailFlagBit2 and MailFlagBit0 set *)
+
| Gray (** Bit pattern 011 - MailFlagBit1 and MailFlagBit0 set *)
+
(** Standard message keywords as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 4.1.
+
These are standardized keywords that can be applied to email messages.
+
@see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-4.1>
| Notify (** Indicate a notification should be shown for this message *)
| Muted (** User is not interested in future replies to this thread *)
···
| MailFlagBit2 (** Bit 2 of the 3-bit flag color pattern *)
| OtherKeyword of string (** Other non-standard keywords *)
+
(** Special mailbox attribute names as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 4.2.
+
These are standardized attributes for special-purpose mailboxes.
+
@see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-4.2>
| Snoozed (** Mailbox containing messages that have been snoozed *)
| Scheduled (** Mailbox containing messages scheduled to be sent later *)
| Memos (** Mailbox containing messages with the $memo keyword *)
| OtherAttribute of string (** Other non-standard mailbox attributes *)
+
(** Convert bit values to a flag color
+
@param bit0 Value of bit 0 (least significant bit)
+
@param bit1 Value of bit 1
+
@param bit2 Value of bit 2 (most significant bit)
+
@return The corresponding flag color
val flag_color_of_bits : bool -> bool -> bool -> flag_color
+
(** Get the bit values for a flag color
+
@param color The flag color
+
@return Tuple of (bit2, bit1, bit0) values
val bits_of_flag_color : flag_color -> bool * bool * bool
+
(** Check if a message has a flag color based on its keywords
+
@param keywords The list of keywords for the message
+
@return True if the message has one or more flag color bits set
val has_flag_color : (keyword * bool) list -> bool
+
(** Get the flag color from a message's keywords, if present
+
@param keywords The list of keywords for the message
+
@return The flag color if all required bits are present, None otherwise
val get_flag_color : (keyword * bool) list -> flag_color option
+
(** Convert a message keyword to its string representation
+
@param keyword The message keyword
+
@return String representation with $ prefix (e.g., "$notify")
val string_of_message_keyword : message_keyword -> string
+
(** Parse a string into a message keyword
+
@param s The string to parse (with or without $ prefix)
+
@return The corresponding message keyword
val message_keyword_of_string : string -> message_keyword
+
(** Convert a mailbox attribute to its string representation
+
@param attr The mailbox attribute
+
@return String representation with $ prefix (e.g., "$snoozed")
val string_of_mailbox_attribute : mailbox_attribute -> string
+
(** Parse a string into a mailbox attribute
+
@param s The string to parse (with or without $ prefix)
+
@return The corresponding mailbox attribute
val mailbox_attribute_of_string : string -> mailbox_attribute
+
(** Get a human-readable representation of a flag color
+
@param color The flag color
+
@return Human-readable name of the color
val human_readable_flag_color : flag_color -> string
+
(** Get a human-readable representation of a message keyword
+
@param keyword The message keyword
+
@return Human-readable description of the keyword
val human_readable_message_keyword : message_keyword -> string
+
(** Format email keywords into a human-readable string representation
+
@param keywords The list of keywords and their values
+
@return Human-readable comma-separated list of keywords
val format_email_keywords : (keyword * bool) list -> string
+
(** {1 JSON serialization}
+
Functions for serializing and deserializing JMAP Mail objects to/from JSON
+
(** {2 Helper functions for serialization}
+
Utility functions for converting between OCaml types and JSON representation
+
(** Convert a mailbox role to its string representation
+
@param role The mailbox role
+
@return String representation (e.g., "inbox", "drafts", etc.)
val string_of_mailbox_role : mailbox_role -> string
+
(** Parse a string into a mailbox role
+
@param s The string to parse
+
@return The corresponding mailbox role, or Unknown if not recognized
val mailbox_role_of_string : string -> mailbox_role
+
(** Convert an email keyword to its string representation
+
@param keyword The email keyword
+
@return String representation with $ prefix (e.g., "$flagged")
val string_of_keyword : keyword -> string
+
(** Parse a string into an email keyword
+
@param s The string to parse (with or without $ prefix)
+
@return The corresponding email keyword
val keyword_of_string : string -> keyword
+
(** {2 Mailbox serialization}
+
Functions for serializing and deserializing mailbox objects
(** TODO:claude - Need to implement all JSON serialization functions
for each type we've defined. This would be a substantial amount of
···
+
High-level functions for interacting with JMAP Mail servers
(** Authentication credentials for a JMAP server *)
+
username: string; (** Username for authentication *)
+
password: string; (** Password for authentication *)
(** Connection to a JMAP mail server *)
+
session: Jmap.Types.session; (** Session information from the server *)
+
config: Jmap.Api.config; (** Configuration for API requests *)
(** Login to a JMAP server and establish a connection
@param uri The URI of the JMAP server
@param credentials Authentication credentials
+
@return A connection object if successful
+
Creates a new connection to a JMAP server using username/password authentication.
credentials:credentials ->
···
@param api_token The API token for authentication
@return A connection object if successful
+
Creates a new connection to a JMAP server using Bearer token authentication.
···
@param account_id The account ID to get mailboxes for
@return A list of mailboxes if successful
+
Retrieves all mailboxes (folders) in the specified account.
account_id:Jmap.Types.id ->
···
@param mailbox_id The mailbox ID to retrieve
@return The mailbox if found
+
Retrieves a single mailbox by its ID.
account_id:Jmap.Types.id ->
···
@param limit Optional limit on number of messages to return
@return The list of email messages if successful
+
Retrieves email messages in the specified mailbox, with optional limit.
val get_messages_in_mailbox :
account_id:Jmap.Types.id ->
···
@param email_id The email ID to retrieve
@return The email message if found
+
Retrieves a single email message by its ID.
account_id:Jmap.Types.id ->
···
@param keyword The message keyword to look for
@return true if the email has the keyword, false otherwise
+
Tests whether an email has a particular keyword (flag) set.
val has_message_keyword :
···
@param keyword The message keyword to add
+
Adds a keyword (flag) to an email message.
val add_message_keyword :
account_id:Jmap.Types.id ->
···
@param color The flag color to set
+
Sets a flag color on an email message by setting the appropriate bit flags.
account_id:Jmap.Types.id ->
···
@param email The email to analyze
@return List of message keywords
+
Extracts all message keywords from an email's keyword list.
val get_message_keywords :
Types.message_keyword list
···
@param limit Optional limit on number of emails to return
@return List of emails with the keyword if successful
+
Retrieves all emails that have a specific keyword (flag) set.
val get_emails_with_keyword :
account_id:Jmap.Types.id ->
···
(Types.email list, Jmap.Api.error) result Lwt.t
+
(** {1 Email Address Utilities}
+
Utilities for working with email addresses
(** Check if an email address matches a filter string
@param email The email address to check
···
@param email The email object to check
@param pattern The sender filter pattern
@return True if any sender address matches the filter
+
Tests whether any of an email's sender addresses match the provided pattern.
val email_matches_sender : Types.email -> string -> bool
anil.recoil.org