(** 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
*)
module Capability : sig
  (** Mail capability URI as defined in RFC8621 Section 1.3
      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
  *)
  val mail_uri : string

  (** 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>
  *)
  type t =
    | 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
end

(** Types for the JMAP Mail extension as defined in RFC8621
    @see <https://datatracker.ietf.org/doc/html/rfc8621>
*)
module Types : sig
  open Jmap.Types

  (** {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>
  *)
  type mailbox_role =
    | 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>
  *)
  type mailbox = {
    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>
  *)
  and mailbox_rights = {
    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>
  *)
  and mailbox_creation = {
    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>
  *)
  and mailbox_update = {
    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>
  *)
  type thread = {
    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>
  *)
  type email_address = {
    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>
  *)
  type header = {
    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>
  *)
  type keyword =
    | 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>
  *)
  type email = {
    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>
  *)
  and email_body_part = {
    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>
  *)
  and email_creation = {
    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>
  *)
  and email_update = {
    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>
  *)
  and email_import = {
    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>
  *)
  and search_snippet = {
    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 *)
    undo_status : [
      | `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>
  *)
  and envelope = {
    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>
  *)
  type identity = {
    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>
  *)
  and identity_update = {
    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>
  *)
  type flag_color =
    | 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>
  *)
  type message_keyword =
    | Notify         (** Indicate a notification should be shown for this message *)
    | Muted          (** User is not interested in future replies to this thread *)
    | Followed       (** User is particularly interested in future replies to this thread *)
    | Memo           (** Message is a note-to-self about another message in the same thread *)
    | HasMemo        (** Message has an associated memo with the $memo keyword *)
    | HasAttachment  (** Message has an attachment *)
    | HasNoAttachment (** Message does not have an attachment *)
    | AutoSent       (** Message was sent automatically as a response due to a user rule *)
    | Unsubscribed   (** User has unsubscribed from the thread this message is in *)
    | CanUnsubscribe (** Message has an RFC8058-compliant List-Unsubscribe header *)
    | Imported       (** Message was imported from another mailbox *)
    | IsTrusted      (** Server has verified authenticity of the from name and email *)
    | MaskedEmail    (** Message was received via an alias created for an individual sender *)
    | New            (** Message should be made more prominent due to a recent action *)
    | MailFlagBit0   (** Bit 0 of the 3-bit flag color pattern *)
    | MailFlagBit1   (** Bit 1 of the 3-bit flag color pattern *)
    | 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>
  *)
  type mailbox_attribute =
    | 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
end

(** {1 JSON serialization}
    Functions for serializing and deserializing JMAP Mail objects to/from JSON
*)

module Json : sig
  open Types

  (** {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
      code and likely require additional understanding of the ezjsonm API.
      
      The interface would include functions like:
      
      val mailbox_to_json : mailbox -> Ezjsonm.value
      val mailbox_of_json : Ezjsonm.value -> mailbox result
      
      And similarly for all other types.
  *)
end

(** {1 API functions}
    High-level functions for interacting with JMAP Mail servers
*)

(** Authentication credentials for a JMAP server *)
type credentials = {
  username: string;  (** Username for authentication *)
  password: string;  (** Password for authentication *)
}

(** Connection to a JMAP mail server *)
type connection = {
  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.
*)
val login : 
  uri:string -> 
  credentials:credentials -> 
  (connection, Jmap.Api.error) result Lwt.t

(** Login to a JMAP server using an API token
    @param uri The URI of the JMAP server
    @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.
*)
val login_with_token : 
  uri:string -> 
  api_token:string -> 
  (connection, Jmap.Api.error) result Lwt.t

(** Get all mailboxes for an account
    @param conn The JMAP connection
    @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.
*)
val get_mailboxes : 
  connection -> 
  account_id:Jmap.Types.id -> 
  (Types.mailbox list, Jmap.Api.error) result Lwt.t

(** Get a specific mailbox by ID
    @param conn The JMAP connection
    @param account_id The account ID
    @param mailbox_id The mailbox ID to retrieve
    @return The mailbox if found
    
    Retrieves a single mailbox by its ID.
*)
val get_mailbox : 
  connection -> 
  account_id:Jmap.Types.id -> 
  mailbox_id:Jmap.Types.id -> 
  (Types.mailbox, Jmap.Api.error) result Lwt.t

(** Get messages in a mailbox
    @param conn The JMAP connection
    @param account_id The account ID
    @param mailbox_id The mailbox ID to get messages from
    @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 : 
  connection -> 
  account_id:Jmap.Types.id -> 
  mailbox_id:Jmap.Types.id -> 
  ?limit:int -> 
  unit -> 
  (Types.email list, Jmap.Api.error) result Lwt.t

(** Get a single email message by ID
    @param conn The JMAP connection
    @param account_id The account ID
    @param email_id The email ID to retrieve
    @return The email message if found
    
    Retrieves a single email message by its ID.
*)
val get_email : 
  connection -> 
  account_id:Jmap.Types.id -> 
  email_id:Jmap.Types.id -> 
  (Types.email, Jmap.Api.error) result Lwt.t
  
(** Check if an email has a specific message keyword
    @param email The email to check
    @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 :
  Types.email ->
  Types.message_keyword ->
  bool

(** Add a message keyword to an email
    @param conn The JMAP connection
    @param account_id The account ID
    @param email_id The email ID
    @param keyword The message keyword to add
    @return Success or error
    
    Adds a keyword (flag) to an email message.
*)
val add_message_keyword :
  connection ->
  account_id:Jmap.Types.id ->
  email_id:Jmap.Types.id ->
  keyword:Types.message_keyword ->
  (unit, Jmap.Api.error) result Lwt.t

(** Set a flag color for an email
    @param conn The JMAP connection
    @param account_id The account ID
    @param email_id The email ID
    @param color The flag color to set
    @return Success or error
    
    Sets a flag color on an email message by setting the appropriate bit flags.
*)
val set_flag_color :
  connection ->
  account_id:Jmap.Types.id ->
  email_id:Jmap.Types.id ->
  color:Types.flag_color ->
  (unit, Jmap.Api.error) result Lwt.t

(** Convert an email's keywords to typed message_keyword list
    @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.email ->
  Types.message_keyword list

(** Get emails with a specific message keyword
    @param conn The JMAP connection
    @param account_id The account ID
    @param keyword The message keyword to search for
    @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 :
  connection ->
  account_id:Jmap.Types.id ->
  keyword:Types.message_keyword ->
  ?limit:int ->
  unit ->
  (Types.email list, Jmap.Api.error) result Lwt.t

(** {1 Email Submission}
    Functions for sending emails
*)

(** Create a new email draft
    @param conn The JMAP connection
    @param account_id The account ID
    @param mailbox_id The mailbox ID to store the draft in (usually "drafts")
    @param from The sender's email address 
    @param to_addresses List of recipient email addresses
    @param subject The email subject line
    @param text_body Plain text message body
    @param html_body Optional HTML message body
    @return The created email ID if successful
    
    Creates a new email draft in the specified mailbox with the provided content.
*)
val create_email_draft :
  connection ->
  account_id:Jmap.Types.id ->
  mailbox_id:Jmap.Types.id ->
  from:string ->
  to_addresses:string list ->
  subject:string ->
  text_body:string ->
  ?html_body:string ->
  unit ->
  (Jmap.Types.id, Jmap.Api.error) result Lwt.t

(** Get all identities for an account
    @param conn The JMAP connection
    @param account_id The account ID
    @return A list of identities if successful
    
    Retrieves all identities (email addresses that can be used for sending) for an account.
*)
val get_identities :
  connection ->
  account_id:Jmap.Types.id ->
  (Types.identity list, Jmap.Api.error) result Lwt.t

(** Find a suitable identity by email address
    @param conn The JMAP connection
    @param account_id The account ID
    @param email The email address to match
    @return The identity if found, otherwise Error
    
    Finds an identity that matches the given email address, either exactly or
    via a wildcard pattern (e.g., *@domain.com).
*)
val find_identity_by_email :
  connection ->
  account_id:Jmap.Types.id ->
  email:string ->
  (Types.identity, Jmap.Api.error) result Lwt.t

(** Submit an email for delivery
    @param conn The JMAP connection
    @param account_id The account ID
    @param identity_id The identity ID to send from
    @param email_id The email ID to submit
    @param envelope Optional custom envelope
    @return The submission ID if successful
    
    Submits an existing email (usually a draft) for delivery using the specified identity.
*)
val submit_email :
  connection ->
  account_id:Jmap.Types.id ->
  identity_id:Jmap.Types.id ->
  email_id:Jmap.Types.id ->
  ?envelope:Types.envelope ->
  unit ->
  (Jmap.Types.id, Jmap.Api.error) result Lwt.t

(** Create and submit an email in one operation
    @param conn The JMAP connection
    @param account_id The account ID
    @param from The sender's email address 
    @param to_addresses List of recipient email addresses
    @param subject The email subject line
    @param text_body Plain text message body
    @param html_body Optional HTML message body
    @return The submission ID if successful
    
    Creates a new email and immediately submits it for delivery.
    This is a convenience function that combines create_email_draft and submit_email.
*)
val create_and_submit_email :
  connection ->
  account_id:Jmap.Types.id ->
  from:string ->
  to_addresses:string list ->
  subject:string ->
  text_body:string ->
  ?html_body:string ->
  unit ->
  (Jmap.Types.id, Jmap.Api.error) result Lwt.t

(** Get status of an email submission
    @param conn The JMAP connection
    @param account_id The account ID
    @param submission_id The email submission ID
    @return The submission status if successful
    
    Retrieves the current status of an email submission, including delivery status if available.
*)
val get_submission_status :
  connection ->
  account_id:Jmap.Types.id ->
  submission_id:Jmap.Types.id ->
  (Types.email_submission, 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 pattern The filter pattern to match against
    @return True if the email address matches the filter 
    
    The filter supports simple wildcards:
    - "*" matches any sequence of characters
    - "?" matches any single character
    - Case-insensitive matching is used
    - If no wildcards are present, substring matching is used
*)
val email_address_matches : string -> string -> bool

(** Check if an email matches a sender filter
    @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