(** High-level email submission API for JMAP clients. Note: The 'context' type parameter should be Jmap_unix.context when using this module through the Jmap_unix interface. This module provides ergonomic functions for submitting emails via JMAP, including creating submissions, managing envelopes, and tracking delivery status. Inspired by the rust-jmap API design for familiarity and ease of use. Example usage: {[ (* Simple email submission *) let result = Email_submission.submit_email env ctx ~email_id ~identity_id in (* Submit with custom envelope *) let result = Email_submission.submit_email_with_envelope env ctx ~email_id ~identity_id ~mail_from:"sender@example.com" ~rcpt_to:["recipient@example.com"] in (* Cancel a pending submission *) let result = Email_submission.cancel_submission env ctx ~submission_id in ]} *) (** Result type alias for cleaner signatures *) type 'a result = ('a, Jmap.Error.error) Result.t (** {1 Email Submission Creation} *) (** Submit an email with minimal configuration. Creates an EmailSubmission for the specified email using the given identity. The email will be sent immediately unless the server applies scheduling rules. @param env Eio environment for network operations @param ctx Connection context @param email_id The ID of the email to submit @param identity_id The identity to use for sending @return The created EmailSubmission object or an error @see RFC 8621, Section 7.5 *) val submit_email : < net : 'a Eio.Net.t ; .. > -> 'context -> email_id:Jmap.Id.t -> identity_id:Jmap.Id.t -> Jmap_email.Submission.t result (** Submit an email with a custom SMTP envelope. Creates an EmailSubmission with explicit SMTP envelope addresses, overriding the addresses derived from the email headers. This is useful for scenarios like: - Sending to undisclosed recipients - Implementing mailing lists - Testing email delivery @param env Eio environment for network operations @param ctx Connection context @param email_id The ID of the email to submit @param identity_id The identity to use for sending @param mail_from SMTP MAIL FROM address @param rcpt_to List of SMTP RCPT TO addresses @return The created EmailSubmission object or an error @see RFC 8621, Section 7.5 *) val submit_email_with_envelope : < net : 'a Eio.Net.t ; .. > -> 'context -> email_id:Jmap.Id.t -> identity_id:Jmap.Id.t -> mail_from:string -> rcpt_to:string list -> Jmap_email.Submission.t result (** Submit an email and automatically destroy the draft. Creates an EmailSubmission and marks the original email for destruction upon successful submission. This is the typical workflow for sending draft emails, ensuring the draft is removed from the drafts folder after being sent. @param env Eio environment for network operations @param ctx Connection context @param email_id The ID of the draft email to submit and destroy @param identity_id The identity to use for sending @return The created EmailSubmission object or an error @see RFC 8621, Section 7.5 *) val submit_and_destroy_draft : < net : 'a Eio.Net.t ; .. > -> 'context -> email_id:Jmap.Id.t -> identity_id:Jmap.Id.t -> Jmap_email.Submission.t result (** {1 Submission Status Management} *) (** Cancel a pending email submission. Changes the undo status of a pending submission to 'canceled', preventing it from being sent. This operation only succeeds if: - The submission exists - The submission has undoStatus = 'pending' - The server still allows cancellation Common use cases: - User clicked "Undo Send" after submission - Batch processing found an error - User changed their mind before final delivery @param env Eio environment for network operations @param ctx Connection context @param submission_id The ID of the submission to cancel @return Unit on success or an error @see RFC 8621, Section 7.4 *) val cancel_submission : < net : 'a Eio.Net.t ; .. > -> 'context -> submission_id:Jmap.Id.t -> unit result (** {1 Submission Queries} *) (** Get an email submission by ID. Retrieves a single EmailSubmission object with all or specified properties. Use this to check the current status of a submission, including: - Undo status (pending/final/canceled) - Delivery status per recipient - DSN/MDN blob IDs for delivery/read receipts @param env Eio environment for network operations @param ctx Connection context @param submission_id The ID of the submission to retrieve @param properties Optional list of property names to fetch (None for all) @return Some submission if found, None if not found, or an error @see RFC 8621, Section 7.1 *) val get_submission : < net : 'a Eio.Net.t ; .. > -> 'context -> submission_id:Jmap.Id.t -> ?properties:string list -> unit -> Jmap_email.Submission.t option result (** Query email submissions with filters. Searches for EmailSubmission objects matching the specified criteria. This is useful for: - Finding all submissions in a date range - Listing submissions for specific emails - Monitoring submission queue status @param env Eio environment for network operations @param ctx Connection context @param filter Optional filter to apply (e.g., by status, email, date) @param sort Optional sort order (e.g., by sendAt date) @param limit Maximum number of results to return @return List of submission IDs matching the query @see RFC 8621, Section 7.3 *) val query_submissions : < net : 'a Eio.Net.t ; .. > -> 'context -> ?filter:Jmap.Methods.Filter.t -> ?sort:Jmap.Methods.Comparator.t list -> ?limit:Jmap.UInt.t -> unit -> Jmap.Id.t list result (** Query for pending submissions. Convenience function to find all submissions that can still be cancelled. This returns submissions with undoStatus = 'pending'. @param env Eio environment for network operations @param ctx Connection context @return List of pending submission IDs *) val query_pending_submissions : < net : 'a Eio.Net.t ; .. > -> 'context -> Jmap.Id.t list result (** Query submissions for a specific email. Finds all submissions associated with a particular email ID. Useful for tracking the submission history of an email. @param env Eio environment for network operations @param ctx Connection context @param email_id The email ID to search for @return List of submission IDs for the email *) val query_submissions_for_email : < net : 'a Eio.Net.t ; .. > -> 'context -> email_id:Jmap.Id.t -> Jmap.Id.t list result (** {1 Delivery Status} *) (** Check delivery status of a submission. Retrieves the current delivery status for all recipients of a submission. The returned hashtable maps recipient email addresses to their delivery status, including: - SMTP response from the receiving server - Delivery outcome (queued/yes/no/unknown) - Display status from MDN (yes/unknown) @param env Eio environment for network operations @param ctx Connection context @param submission_id The submission to check @return Some hashtable of recipient to status if submission exists, None otherwise @see RFC 8621, Section 7 *) val get_delivery_status : < net : 'a Eio.Net.t ; .. > -> 'context -> submission_id:Jmap.Id.t -> (string, Jmap_email.Submission.DeliveryStatus.t) Hashtbl.t option result (** {1 Batch Operations} *) (** Cancel all pending submissions. Queries for all pending submissions and attempts to cancel each one. This is useful for: - Emergency stop of outgoing mail - Cleanup during testing - Account suspension scenarios Note: Some submissions may fail to cancel if they've already transitioned to 'final' status between the query and cancel operations. @param env Eio environment for network operations @param ctx Connection context @return Number of submissions successfully cancelled @see RFC 8621, Section 7.4 *) val cancel_all_pending : < net : 'a Eio.Net.t ; .. > -> 'context -> int result