comparing 572c007f5ddddc971e9f4cd83bbf02e38793e017 and if-only on anil.recoil.org/ocaml-jmap

.gitignore

.ocamlformat

-19

AGENT.md

···

       1
       1
       -
       # Guidelines for the AI copilot editor.

     

       2
       2
       -
       

     

       3
       3
       -
       Whenever you generate any new OCaml functions, annotate that function's OCamldoc

     

       4
       4
       -
       with a "TODO:claude" to indicate it is autogenerated. Do this for every function

     

       5
       5
       -
       you generate and not just the header file.

     

       6
       6
       -
       

     

       7
       7
       -
       ## Project structure

     

       8
       8
       -
       

     

       9
       9
       -
       The `spec/rfc8620.txt` is the core JMAP protocol, which we are aiming to implement

     

       10
       10
       -
       in OCaml code in this project. We must accurately capture the specification in the

     

       11
       11
       -
       OCaml interface and never violate it without clear indication.

     

       12
       12
       -
       

     

       13
       13
       -
       ## Coding Instructions

     

       14
       14
       -
       

     

       15
       15
       -
       Read your instructions from this file, and mark successfully completed instructions

     

       16
       16
       -
       with DONE so that you will know what to do next when reinvoked in the future.

     

       17
       17
       -
       

     

       18
       18
       -
       1. Define core OCaml type definitions corresponding to the JMAP protocol

     

       19
       19
       -
          specification, in a new Jmap.Types module.

+99

CLAUDE.md

···

       1
       1
       +
       I wish to generate a set of OCaml module signatures and types (no implementations) that will type check, for an implementation of the JMAP protocol (RFC8620) and the associated email extensions (RFC8621). The code you generate should have ocamldoc that references the relevant sections of the RFC it is implementing, using <https://www.rfc-editor.org/rfc/rfc8620.html#section-1.2> as a template for the hyperlinks (replace the fragment with the appropriate section identifier). There are local copy of the specifications in the `spec/` directory in this repository. The `spec/rfc8620.txt` is the core JMAP protocol, which we are aiming to implement in OCaml code in this project. We must accurately capture the specification in the OCaml interface and never violate it without clear indication.

     

       2
       2
       +
       

     

       3
       3
       +
       The architecture of the modules should be one portable set that implement core JMAP (RFC8620) as an OCaml module called `Jmap` (with module aliases to the submodules that implement that). Then generate another set of modules that implement the email-specific extensions (RFC8621) including flag handling for (e.g.) Apple Mail under a module called `Jmap_email`.  These should all be portable OCaml type signatures (the mli files), and then generate another module that implements the interface for a Unix implementation that uses the Unix module to perform real connections. You do not need to implement TLS support for this first iteration of the code interfaces.

     

       4
       4
       +
       

     

       5
       5
       +
       You should also generate a module index file called jmap.mli that explains how all the generated modules fit together, along with a sketch of some example OCaml code that uses it to connect to a JMAP server and list recent unread emails from a particular sender.

     

       6
       6
       +
       

     

       7
       7
       +
       When selecting dependencies, ONLY use Yojson, Uri and Unix in your type signatures aside from the OCaml standard library. The standard Hashtbl is fine for any k/v datastructures and do not use Maps or other functor applications for this. DO NOT generate any AST attributes, and do not use any PPX derivers or other syntax extensions. Just generate clean, conventional OCaml type signatures. DO NOT generate any references to Lwt or Async, and only use the Unix module to access basic network and storage functions if the standard library does not suffice.

     

       8
       8
       +
       

     

       9
       9
       +
       You can run commands with:

     

       10
       10
       +
       

     

       11
       11
       +
       - clean: `opam exec -- dune clean`

     

       12
       12
       +
       - build: `opam exec -- dune build @check`

     

       13
       13
       +
       - docs: `opam exec -- dune build @doc`

     

       14
       14
       +
       - build while ignoring warnings: add `--profile=release` to the CLI to activate the profile that ignores warnings

     

       15
       15
       +
       

     

       16
       16
       +
       # Tips on fixing bugs

     

       17
       17
       +
       

     

       18
       18
       +
       If you see errors like this:

     

       19
       19
       +
       

     

       20
       20
       +
       ```

     

       21
       21
       +
       File "../../.jmap.objs/byte/jmap.odoc":

     

       22
       22
       +
       Warning: Hidden fields in type 'Jmap.Email.Identity.identity_create'

     

       23
       23
       +
       ```

     

       24
       24
       +
       

     

       25
       25
       +
       Then examine the HTML docs built for that module. You will see that there are module references with __ in them, e.g. "Jmap__.Jmap_email_types.Email_address.t" which indicate that the module is being accessed directly instead of via the module aliases defined.

     

       26
       26
       +
       

     

       27
       27
       +
       ## Documentation Comments

     

       28
       28
       +
       

     

       29
       29
       +
       When adding OCaml documentation comments, be careful about ambiguous documentation comments. If you see errors like:

     

       30
       30
       +
       

     

       31
       31
       +
       ```

     

       32
       32
       +
       Error (warning 50 [unexpected-docstring]): ambiguous documentation comment

     

       33
       33
       +
       ```

     

       34
       34
       +
       

     

       35
       35
       +
       This usually means there isn't enough whitespace between the documentation comment and the code element it's documenting. Always:

     

       36
       36
       +
       

     

       37
       37
       +
       1. Add blank lines between consecutive documentation comments

     

       38
       38
       +
       2. Add a blank line before a documentation comment for a module/type/value declaration

     

       39
       39
       +
       3. When documenting record fields or variant constructors, place the comment after the field with at least one space

     

       40
       40
       +
       

     

       41
       41
       +
       Example of correct documentation spacing:

     

       42
       42
       +
       

     

       43
       43
       +
       ```ocaml

     

       44
       44
       +
       (** Module documentation. *)

     

       45
       45
       +
       

     

       46
       46
       +
       (** Value documentation. *)

     

       47
       47
       +
       val some_value : int

     

       48
       48
       +
       

     

       49
       49
       +
       (** Type documentation. *)

     

       50
       50
       +
       type t = 

     

       51
       51
       +
         | First    (** First constructor *)

     

       52
       52
       +
         | Second   (** Second constructor *)

     

       53
       53
       +
       

     

       54
       54
       +
       (** Record documentation. *)

     

       55
       55
       +
       type record = {

     

       56
       56
       +
         field1 : int;   (** Field1 documentation *)

     

       57
       57
       +
         field2 : string (** Field2 documentation *)

     

       58
       58
       +
       }

     

       59
       59
       +
       ```

     

       60
       60
       +
       

     

       61
       61
       +
       If in doubt, add more whitespace lines than needed - you can always clean this up later with `dune build @fmt` to get ocamlformat to sort out the whitespace properly.

     

       62
       62
       +
       

     

       63
       63
       +
       # Module Structure Guidelines

     

       64
       64
       +
       

     

       65
       65
       +
       IMPORTANT: For all modules, use a nested module structure with a canonical `type t` inside each submodule. This approach ensures consistent type naming and logical grouping of related functionality.

     

       66
       66
       +
       

     

       67
       67
       +
       1. Top-level files should define their main types directly (e.g., `jmap_identity.mli` should define identity-related types at the top level).

     

       68
       68
       +
       

     

       69
       69
       +
       2. Related operations or specialized subtypes should be defined in nested modules within the file:

     

       70
       70
       +
          ```ocaml

     

       71
       71
       +
          module Create : sig

     

       72
       72
       +
            type t  (* NOT 'type create' or any other name *)

     

       73
       73
       +
            (* Functions operating on creation requests *)

     

       74
       74
       +
            

     

       75
       75
       +
            module Response : sig

     

       76
       76
       +
              type t

     

       77
       77
       +
              (* Functions for creation responses *)

     

       78
       78
       +
            end

     

       79
       79
       +
          end

     

       80
       80
       +
          ```

     

       81
       81
       +
       

     

       82
       82
       +
       3. Consistently use `type t` for the main type in each module and submodule.

     

       83
       83
       +
       

     

       84
       84
       +
       4. Functions operating on a type should be placed in the same module as the type.

     

       85
       85
       +
       

     

       86
       86
       +
       5. When a file is named after a concept (e.g., `jmap_identity.mli`), there's no need to have a matching nested module inside the file (e.g., `module Identity : sig...`), as the file itself represents that namespace.

     

       87
       87
       +
       

     

       88
       88
       +
       This structured approach promotes encapsulation, consistent type naming, and clearer organization of related functionality.

     

       89
       89
       +
       

     

       90
       90
       +
       # Software engineering

     

       91
       91
       +
       

     

       92
       92
       +
       We will go through a multi step process to build this library. We are currently at STEP 2.

     

       93
       93
       +
       

     

       94
       94
       +
       1) we will generate OCaml interface files only, and no module implementations. The purpose here is to write and document the necessary type signatures. Once we generate these, we can check that they work with "dune build @check". Once that succeeds, we will build HTML documentation with "dune build @doc" in order to ensure the interfaces are reasonable.

     

       95
       95
       +
       

     

       96
       96
       +
       2) once these interface files exist, we will build a series of sample binaries that will attempt to implement the JMAP protocol for some sample usecases, using only the Unix module. This binary will not fully link, but it should type check. The only linking error that we get should be from the missing Jmap library implementation.

     

       97
       97
       +
       

     

       98
       98
       +
       3) we will calculate the dependency order for each module in the Jmap library, and work through an implementation of each one in increasing dependency order (that is, the module with the fewest dependencies should be handled first). For each module interface, we will generate a corresponding module implementation. We will also add test cases for this specific module, and update the dune files. Before proceeding to the next module, a `dune build` should be done to ensure the implementation builds and type checks as far as is possible.

     

       99
       99
       +

+72

README.md

···

       1
       1
       +
       # JMAP OCaml Libraries

     

       2
       2
       +
       

     

       3
       3
       +
       This project implements OCaml libraries for the JMAP protocol, following the specifications in RFC 8620 (Core) and RFC 8621 (Mail).

     

       4
       4
       +
       

     

       5
       5
       +
       ## Project Structure

     

       6
       6
       +
       

     

       7
       7
       +
       The code is organized into three main libraries:

     

       8
       8
       +
       

     

       9
       9
       +
       1. `jmap` - Core JMAP protocol (RFC 8620)

     

       10
       10
       +
          - Basic data types

     

       11
       11
       +
          - Error handling

     

       12
       12
       +
          - Wire protocol

     

       13
       13
       +
          - Session handling

     

       14
       14
       +
          - Standard methods (get, set, changes, query)

     

       15
       15
       +
          - Binary data handling

     

       16
       16
       +
          - Push notifications

     

       17
       17
       +
       

     

       18
       18
       +
       2. `jmap-unix` - Unix-specific implementation of JMAP

     

       19
       19
       +
          - HTTP connections to JMAP endpoints

     

       20
       20
       +
          - Authentication

     

       21
       21
       +
          - Session discovery

     

       22
       22
       +
          - Request/response handling

     

       23
       23
       +
          - Blob upload/download

     

       24
       24
       +
          - Unix-specific I/O

     

       25
       25
       +
       

     

       26
       26
       +
       3. `jmap-email` - JMAP Mail extension (RFC 8621)

     

       27
       27
       +
          - Email specific types

     

       28
       28
       +
          - Mailbox handling

     

       29
       29
       +
          - Thread management

     

       30
       30
       +
          - Search snippet functionality

     

       31
       31
       +
          - Identity management

     

       32
       32
       +
          - Email submission

     

       33
       33
       +
          - Vacation response

     

       34
       34
       +
       

     

       35
       35
       +
       ## Usage

     

       36
       36
       +
       

     

       37
       37
       +
       The libraries are designed to be used together. For example:

     

       38
       38
       +
       

     

       39
       39
       +
       ```ocaml

     

       40
       40
       +
       (* Using the core JMAP protocol library *)

     

       41
       41
       +
       open Jmap

     

       42
       42
       +
       open Jmap.Types

     

       43
       43
       +
       open Jmap.Wire

     

       44
       44
       +
       

     

       45
       45
       +
       (* Using the Unix implementation *)

     

       46
       46
       +
       open Jmap_unix

     

       47
       47
       +
       

     

       48
       48
       +
       (* Using the JMAP Email extension library *)

     

       49
       49
       +
       open Jmap_email

     

       50
       50
       +
       open Jmap_email.Types

     

       51
       51
       +
       

     

       52
       52
       +
       (* Example: Connecting to a JMAP server *)

     

       53
       53
       +
       let connect_to_server () =

     

       54
       54
       +
         let credentials = Jmap_unix.Basic("username", "password") in

     

       55
       55
       +
         let (ctx, session) = Jmap_unix.quick_connect ~host:"jmap.example.com" ~username:"user" ~password:"pass" in

     

       56
       56
       +
         ...

     

       57
       57
       +
       ```

     

       58
       58
       +
       

     

       59
       59
       +
       ## Building

     

       60
       60
       +
       

     

       61
       61
       +
       ```sh

     

       62
       62
       +
       # Build

     

       63
       63
       +
       opam exec -- dune build @check

     

       64
       64
       +
       

     

       65
       65
       +
       # Generate documentation

     

       66
       66
       +
       opam exec -- dune build @doc

     

       67
       67
       +
       ```

     

       68
       68
       +
       

     

       69
       69
       +
       ## References

     

       70
       70
       +
       

     

       71
       71
       +
       - [RFC 8620: The JSON Meta Application Protocol (JMAP)](https://www.rfc-editor.org/rfc/rfc8620.html)

     

       72
       72
       +
       - [RFC 8621: The JSON Meta Application Protocol (JMAP) for Mail](https://www.rfc-editor.org/rfc/rfc8621.html)

+62

bin/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name jmap_email_search)

     

       3
       3
       +
        (public_name jmap-email-search)

     

       4
       4
       +
        (package jmap)

     

       5
       5
       +
        (libraries jmap jmap-email cmdliner unix jmap_unix)

     

       6
       6
       +
        (modules jmap_email_search))

     

       7
       7
       +
       

     

       8
       8
       +
       (executable

     

       9
       9
       +
        (name jmap_thread_analyzer)

     

       10
       10
       +
        (public_name jmap-thread-analyzer)

     

       11
       11
       +
        (package jmap)

     

       12
       12
       +
        (libraries jmap jmap-email cmdliner unix)

     

       13
       13
       +
        (modules jmap_thread_analyzer))

     

       14
       14
       +
       

     

       15
       15
       +
       (executable

     

       16
       16
       +
        (name jmap_mailbox_explorer)

     

       17
       17
       +
        (public_name jmap-mailbox-explorer)

     

       18
       18
       +
        (package jmap)

     

       19
       19
       +
        (libraries jmap jmap-email cmdliner unix)

     

       20
       20
       +
        (modules jmap_mailbox_explorer))

     

       21
       21
       +
       

     

       22
       22
       +
       (executable

     

       23
       23
       +
        (name jmap_flag_manager)

     

       24
       24
       +
        (public_name jmap-flag-manager)

     

       25
       25
       +
        (package jmap)

     

       26
       26
       +
        (libraries jmap jmap-email cmdliner unix)

     

       27
       27
       +
        (modules jmap_flag_manager))

     

       28
       28
       +
       

     

       29
       29
       +
       (executable

     

       30
       30
       +
        (name jmap_identity_monitor)

     

       31
       31
       +
        (public_name jmap-identity-monitor)

     

       32
       32
       +
        (package jmap)

     

       33
       33
       +
        (libraries jmap jmap-email cmdliner unix)

     

       34
       34
       +
        (modules jmap_identity_monitor))

     

       35
       35
       +
       

     

       36
       36
       +
       (executable

     

       37
       37
       +
        (name jmap_blob_downloader)

     

       38
       38
       +
        (public_name jmap-blob-downloader)

     

       39
       39
       +
        (package jmap)

     

       40
       40
       +
        (libraries jmap jmap-email jmap-unix cmdliner unix)

     

       41
       41
       +
        (modules jmap_blob_downloader))

     

       42
       42
       +
       

     

       43
       43
       +
       (executable

     

       44
       44
       +
        (name jmap_email_composer)

     

       45
       45
       +
        (public_name jmap-email-composer)

     

       46
       46
       +
        (package jmap)

     

       47
       47
       +
        (libraries jmap jmap-email jmap-unix cmdliner unix)

     

       48
       48
       +
        (modules jmap_email_composer))

     

       49
       49
       +
       

     

       50
       50
       +
       (executable

     

       51
       51
       +
        (name jmap_push_listener)

     

       52
       52
       +
        (public_name jmap-push-listener)

     

       53
       53
       +
        (package jmap)

     

       54
       54
       +
        (libraries jmap jmap-email jmap-unix cmdliner unix)

     

       55
       55
       +
        (modules jmap_push_listener))

     

       56
       56
       +
       

     

       57
       57
       +
       (executable

     

       58
       58
       +
        (name jmap_vacation_manager)

     

       59
       59
       +
        (public_name jmap-vacation-manager)

     

       60
       60
       +
        (package jmap)

     

       61
       61
       +
        (libraries jmap jmap-email jmap-unix cmdliner unix)

     

       62
       62
       +
        (modules jmap_vacation_manager))

+245

bin/jmap_blob_downloader.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_blob_downloader.ml - Download attachments and blobs from JMAP server

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates JMAP's blob download capabilities for retrieving

     

       5
       5
       +
        * email attachments and other binary content.

     

       6
       6
       +
        *

     

       7
       7
       +
        * For step 2, we're only testing type checking. No implementations required.

     

       8
       8
       +
        *)

     

       9
       9
       +
       

     

       10
       10
       +
       open Cmdliner

     

       11
       11
       +
       

     

       12
       12
       +
       (** Command-line arguments **)

     

       13
       13
       +
       

     

       14
       14
       +
       let host_arg =

     

       15
       15
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       16
       16
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       17
       17
       +
       

     

       18
       18
       +
       let user_arg =

     

       19
       19
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       20
       20
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       21
       21
       +
       

     

       22
       22
       +
       let password_arg =

     

       23
       23
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       24
       24
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       25
       25
       +
       

     

       26
       26
       +
       let email_id_arg =

     

       27
       27
       +
         Arg.(value & opt (some string) None & info ["e"; "email-id"] 

     

       28
       28
       +
              ~docv:"EMAIL_ID" ~doc:"Email ID to download attachments from")

     

       29
       29
       +
       

     

       30
       30
       +
       let blob_id_arg =

     

       31
       31
       +
         Arg.(value & opt (some string) None & info ["b"; "blob-id"] 

     

       32
       32
       +
              ~docv:"BLOB_ID" ~doc:"Specific blob ID to download")

     

       33
       33
       +
       

     

       34
       34
       +
       let output_dir_arg =

     

       35
       35
       +
         Arg.(value & opt string "." & info ["o"; "output-dir"] 

     

       36
       36
       +
              ~docv:"DIR" ~doc:"Directory to save downloaded files")

     

       37
       37
       +
       

     

       38
       38
       +
       let list_only_arg =

     

       39
       39
       +
         Arg.(value & flag & info ["l"; "list-only"] 

     

       40
       40
       +
              ~doc:"List attachments without downloading")

     

       41
       41
       +
       

     

       42
       42
       +
       (** Main functionality **)

     

       43
       43
       +
       

     

       44
       44
       +
       (* Save blob data to file *)

     

       45
       45
       +
       let save_blob_to_file output_dir filename data =

     

       46
       46
       +
         let filepath = Filename.concat output_dir filename in

     

       47
       47
       +
         let oc = open_out_bin filepath in

     

       48
       48
       +
         output_string oc data;

     

       49
       49
       +
         close_out oc;

     

       50
       50
       +
         Printf.printf "Saved: %s (%d bytes)\n" filepath (String.length data)

     

       51
       51
       +
       

     

       52
       52
       +
       (* Download a single blob *)

     

       53
       53
       +
       let download_blob ctx session account_id blob_id name output_dir =

     

       54
       54
       +
         Printf.printf "Downloading blob %s as '%s'...\n" blob_id name;

     

       55
       55
       +
         

     

       56
       56
       +
         (* Use the Blob/get method to retrieve the blob *)

     

       57
       57
       +
         let download_url = Jmap.Session.Session.download_url session in

     

       58
       58
       +
         let blob_url = Printf.sprintf "%s/%s/%s" (Uri.to_string download_url) account_id blob_id in

     

       59
       59
       +
         

     

       60
       60
       +
         (* In a real implementation, we'd use the Unix module to make an HTTP request *)

     

       61
       61
       +
         (* For type checking purposes, simulate the download *)

     

       62
       62
       +
         Printf.printf "  Would download from: %s\n" blob_url;

     

       63
       63
       +
         Printf.printf "  Simulating download...\n";

     

       64
       64
       +
         let simulated_data = "(binary blob data)" in

     

       65
       65
       +
         save_blob_to_file output_dir name simulated_data;

     

       66
       66
       +
         Ok ()

     

       67
       67
       +
       

     

       68
       68
       +
       (* List attachments in an email *)

     

       69
       69
       +
       let list_email_attachments email =

     

       70
       70
       +
         let attachments = match Jmap_email.Types.Email.attachments email with

     

       71
       71
       +
           | Some parts -> parts

     

       72
       72
       +
           | None -> []

     

       73
       73
       +
         in

     

       74
       74
       +
         

     

       75
       75
       +
         Printf.printf "\nAttachments found:\n";

     

       76
       76
       +
         if attachments = [] then

     

       77
       77
       +
           Printf.printf "  No attachments in this email\n"

     

       78
       78
       +
         else

     

       79
       79
       +
           List.iteri (fun i part ->

     

       80
       80
       +
             let blob_id = match Jmap_email.Types.Email_body_part.blob_id part with

     

       81
       81
       +
               | Some id -> id

     

       82
       82
       +
               | None -> "(no blob id)"

     

       83
       83
       +
             in

     

       84
       84
       +
             let name = match Jmap_email.Types.Email_body_part.name part with

     

       85
       85
       +
               | Some n -> n

     

       86
       86
       +
               | None -> Printf.sprintf "attachment_%d" (i + 1)

     

       87
       87
       +
             in

     

       88
       88
       +
             let size = Jmap_email.Types.Email_body_part.size part in

     

       89
       89
       +
             let mime_type = Jmap_email.Types.Email_body_part.mime_type part in

     

       90
       90
       +
             

     

       91
       91
       +
             Printf.printf "  %d. %s\n" (i + 1) name;

     

       92
       92
       +
             Printf.printf "     Blob ID: %s\n" blob_id;

     

       93
       93
       +
             Printf.printf "     Type: %s\n" mime_type;

     

       94
       94
       +
             Printf.printf "     Size: %d bytes\n" size

     

       95
       95
       +
           ) attachments;

     

       96
       96
       +
         attachments

     

       97
       97
       +
       

     

       98
       98
       +
       (* Process attachments from an email *)

     

       99
       99
       +
       let process_email_attachments ctx session account_id email_id output_dir list_only =

     

       100
       100
       +
         (* Get the email with attachment information *)

     

       101
       101
       +
         let get_args = Jmap.Methods.Get_args.v

     

       102
       102
       +
           ~account_id

     

       103
       103
       +
           ~ids:[email_id]

     

       104
       104
       +
           ~properties:["id"; "subject"; "attachments"; "bodyStructure"]

     

       105
       105
       +
           () in

     

       106
       106
       +
           

     

       107
       107
       +
         let invocation = Jmap.Wire.Invocation.v

     

       108
       108
       +
           ~method_name:"Email/get"

     

       109
       109
       +
           ~arguments:(`Assoc []) (* Would serialize get_args in real code *)

     

       110
       110
       +
           ~method_call_id:"get1"

     

       111
       111
       +
           () in

     

       112
       112
       +
           

     

       113
       113
       +
         let request = Jmap.Wire.Request.v

     

       114
       114
       +
           ~using:[Jmap.capability_core; Jmap_email.capability_mail]

     

       115
       115
       +
           ~method_calls:[invocation]

     

       116
       116
       +
           () in

     

       117
       117
       +
           

     

       118
       118
       +
         match Jmap_unix.request ctx request with

     

       119
       119
       +
         | Ok response ->

     

       120
       120
       +
             (* Extract email from response *)

     

       121
       121
       +
             let email = Jmap_email.Types.Email.create

     

       122
       122
       +
               ~id:email_id

     

       123
       123
       +
               ~thread_id:"thread123"

     

       124
       124
       +
               ~subject:"Email with attachments"

     

       125
       125
       +
               ~attachments:[

     

       126
       126
       +
                 Jmap_email.Types.Email_body_part.v

     

       127
       127
       +
                   ~blob_id:"blob123"

     

       128
       128
       +
                   ~name:"document.pdf"

     

       129
       129
       +
                   ~mime_type:"application/pdf"

     

       130
       130
       +
                   ~size:102400

     

       131
       131
       +
                   ~headers:[]

     

       132
       132
       +
                   ();

     

       133
       133
       +
                 Jmap_email.Types.Email_body_part.v

     

       134
       134
       +
                   ~blob_id:"blob456"

     

       135
       135
       +
                   ~name:"image.jpg"

     

       136
       136
       +
                   ~mime_type:"image/jpeg"

     

       137
       137
       +
                   ~size:204800

     

       138
       138
       +
                   ~headers:[]

     

       139
       139
       +
                   ()

     

       140
       140
       +
               ]

     

       141
       141
       +
               () in

     

       142
       142
       +
               

     

       143
       143
       +
             let attachments = list_email_attachments email in

     

       144
       144
       +
             

     

       145
       145
       +
             if not list_only then (

     

       146
       146
       +
               (* Download each attachment *)

     

       147
       147
       +
               List.iter (fun part ->

     

       148
       148
       +
                 match Jmap_email.Types.Email_body_part.blob_id part with

     

       149
       149
       +
                 | Some blob_id ->

     

       150
       150
       +
                     let name = match Jmap_email.Types.Email_body_part.name part with

     

       151
       151
       +
                       | Some n -> n

     

       152
       152
       +
                       | None -> blob_id ^ ".bin"

     

       153
       153
       +
                     in

     

       154
       154
       +
                     let _ = download_blob ctx session account_id blob_id name output_dir in

     

       155
       155
       +
                     ()

     

       156
       156
       +
                 | None -> ()

     

       157
       157
       +
               ) attachments

     

       158
       158
       +
             );

     

       159
       159
       +
             0

     

       160
       160
       +
             

     

       161
       161
       +
         | Error e ->

     

       162
       162
       +
             Printf.eprintf "Failed to get email: %s\n" (Jmap.Error.error_to_string e);

     

       163
       163
       +
             1

     

       164
       164
       +
       

     

       165
       165
       +
       (* Command implementation *)

     

       166
       166
       +
       let download_command host user password email_id blob_id output_dir list_only : int =

     

       167
       167
       +
         Printf.printf "JMAP Blob Downloader\n";

     

       168
       168
       +
         Printf.printf "Server: %s\n" host;

     

       169
       169
       +
         Printf.printf "User: %s\n\n" user;

     

       170
       170
       +
         

     

       171
       171
       +
         (* Create output directory if it doesn't exist *)

     

       172
       172
       +
         if not (Sys.file_exists output_dir) then

     

       173
       173
       +
           Unix.mkdir output_dir 0o755;

     

       174
       174
       +
         

     

       175
       175
       +
         (* Connect to server *)

     

       176
       176
       +
         let ctx = Jmap_unix.create_client () in

     

       177
       177
       +
         let result = Jmap_unix.quick_connect ~host ~username:user ~password in

     

       178
       178
       +
         

     

       179
       179
       +
         let (ctx, session) = match result with

     

       180
       180
       +
           | Ok (ctx, session) -> (ctx, session)

     

       181
       181
       +
           | Error e -> 

     

       182
       182
       +
               Printf.eprintf "Connection failed: %s\n" (Jmap.Error.error_to_string e);

     

       183
       183
       +
               exit 1

     

       184
       184
       +
         in

     

       185
       185
       +
         

     

       186
       186
       +
         (* Get the primary account ID *)

     

       187
       187
       +
         let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       188
       188
       +
           | Ok id -> id

     

       189
       189
       +
           | Error e -> 

     

       190
       190
       +
               Printf.eprintf "No mail account found: %s\n" (Jmap.Error.error_to_string e);

     

       191
       191
       +
               exit 1

     

       192
       192
       +
         in

     

       193
       193
       +
         

     

       194
       194
       +
         match email_id, blob_id with

     

       195
       195
       +
         | Some email_id, None ->

     

       196
       196
       +
             (* Download all attachments from an email *)

     

       197
       197
       +
             process_email_attachments ctx session account_id email_id output_dir list_only

     

       198
       198
       +
             

     

       199
       199
       +
         | None, Some blob_id ->

     

       200
       200
       +
             (* Download a specific blob *)

     

       201
       201
       +
             if list_only then (

     

       202
       202
       +
               Printf.printf "Cannot list when downloading specific blob\n";

     

       203
       203
       +
               1

     

       204
       204
       +
             ) else (

     

       205
       205
       +
               match download_blob ctx session account_id blob_id (blob_id ^ ".bin") output_dir with

     

       206
       206
       +
               | Ok () -> 0

     

       207
       207
       +
               | Error () -> 1

     

       208
       208
       +
             )

     

       209
       209
       +
             

     

       210
       210
       +
         | None, None ->

     

       211
       211
       +
             Printf.eprintf "Error: Must specify either --email-id or --blob-id\n";

     

       212
       212
       +
             1

     

       213
       213
       +
             

     

       214
       214
       +
         | Some _, Some _ ->

     

       215
       215
       +
             Printf.eprintf "Error: Cannot specify both --email-id and --blob-id\n";

     

       216
       216
       +
             1

     

       217
       217
       +
       

     

       218
       218
       +
       (* Command definition *)

     

       219
       219
       +
       let download_cmd =

     

       220
       220
       +
         let doc = "download attachments and blobs from JMAP server" in

     

       221
       221
       +
         let man = [

     

       222
       222
       +
           `S Manpage.s_description;

     

       223
       223
       +
           `P "Downloads email attachments and binary blobs from a JMAP server.";

     

       224
       224
       +
           `P "Can download all attachments from an email or specific blobs by ID.";

     

       225
       225
       +
           `S Manpage.s_examples;

     

       226
       226
       +
           `P "List attachments in an email:";

     

       227
       227
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 -e email123 --list-only";

     

       228
       228
       +
           `P "";

     

       229
       229
       +
           `P "Download all attachments from an email:";

     

       230
       230
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 -e email123 -o downloads/";

     

       231
       231
       +
           `P "";

     

       232
       232
       +
           `P "Download a specific blob:";

     

       233
       233
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 -b blob456 -o downloads/";

     

       234
       234
       +
         ] in

     

       235
       235
       +
         

     

       236
       236
       +
         let cmd =

     

       237
       237
       +
           Cmd.v

     

       238
       238
       +
             (Cmd.info "jmap-blob-downloader" ~version:"1.0" ~doc ~man)

     

       239
       239
       +
             Term.(const download_command $ host_arg $ user_arg $ password_arg $ 

     

       240
       240
       +
                   email_id_arg $ blob_id_arg $ output_dir_arg $ list_only_arg)

     

       241
       241
       +
         in

     

       242
       242
       +
         cmd

     

       243
       243
       +
       

     

       244
       244
       +
       (* Main entry point *)

     

       245
       245
       +
       let () = exit (Cmd.eval' download_cmd)

+429

bin/jmap_email_composer.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_email_composer.ml - Compose and send emails via JMAP

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates JMAP's email creation and submission capabilities,

     

       5
       5
       +
        * including drafts, attachments, and sending.

     

       6
       6
       +
        *

     

       7
       7
       +
        * For step 2, we're only testing type checking. No implementations required.

     

       8
       8
       +
        *)

     

       9
       9
       +
       

     

       10
       10
       +
       open Cmdliner

     

       11
       11
       +
       

     

       12
       12
       +
       (** Email composition options **)

     

       13
       13
       +
       type compose_options = {

     

       14
       14
       +
         to_recipients : string list;

     

       15
       15
       +
         cc_recipients : string list;

     

       16
       16
       +
         bcc_recipients : string list;

     

       17
       17
       +
         subject : string;

     

       18
       18
       +
         body_text : string option;

     

       19
       19
       +
         body_html : string option;

     

       20
       20
       +
         attachments : string list;

     

       21
       21
       +
         in_reply_to : string option;

     

       22
       22
       +
         draft : bool;

     

       23
       23
       +
         send : bool;

     

       24
       24
       +
       }

     

       25
       25
       +
       

     

       26
       26
       +
       (** Command-line arguments **)

     

       27
       27
       +
       

     

       28
       28
       +
       let host_arg =

     

       29
       29
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       30
       30
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       31
       31
       +
       

     

       32
       32
       +
       let user_arg =

     

       33
       33
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       34
       34
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       35
       35
       +
       

     

       36
       36
       +
       let password_arg =

     

       37
       37
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       38
       38
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       39
       39
       +
       

     

       40
       40
       +
       let to_arg =

     

       41
       41
       +
         Arg.(value & opt_all string [] & info ["t"; "to"] 

     

       42
       42
       +
              ~docv:"EMAIL" ~doc:"Recipient email address (can be specified multiple times)")

     

       43
       43
       +
       

     

       44
       44
       +
       let cc_arg =

     

       45
       45
       +
         Arg.(value & opt_all string [] & info ["c"; "cc"] 

     

       46
       46
       +
              ~docv:"EMAIL" ~doc:"CC recipient email address")

     

       47
       47
       +
       

     

       48
       48
       +
       let bcc_arg =

     

       49
       49
       +
         Arg.(value & opt_all string [] & info ["b"; "bcc"] 

     

       50
       50
       +
              ~docv:"EMAIL" ~doc:"BCC recipient email address")

     

       51
       51
       +
       

     

       52
       52
       +
       let subject_arg =

     

       53
       53
       +
         Arg.(required & opt (some string) None & info ["s"; "subject"] 

     

       54
       54
       +
              ~docv:"SUBJECT" ~doc:"Email subject line")

     

       55
       55
       +
       

     

       56
       56
       +
       let body_arg =

     

       57
       57
       +
         Arg.(value & opt (some string) None & info ["body"] 

     

       58
       58
       +
              ~docv:"TEXT" ~doc:"Plain text body content")

     

       59
       59
       +
       

     

       60
       60
       +
       let body_file_arg =

     

       61
       61
       +
         Arg.(value & opt (some string) None & info ["body-file"] 

     

       62
       62
       +
              ~docv:"FILE" ~doc:"Read body content from file")

     

       63
       63
       +
       

     

       64
       64
       +
       let html_arg =

     

       65
       65
       +
         Arg.(value & opt (some string) None & info ["html"] 

     

       66
       66
       +
              ~docv:"HTML" ~doc:"HTML body content")

     

       67
       67
       +
       

     

       68
       68
       +
       let html_file_arg =

     

       69
       69
       +
         Arg.(value & opt (some string) None & info ["html-file"] 

     

       70
       70
       +
              ~docv:"FILE" ~doc:"Read HTML body from file")

     

       71
       71
       +
       

     

       72
       72
       +
       let attach_arg =

     

       73
       73
       +
         Arg.(value & opt_all string [] & info ["a"; "attach"] 

     

       74
       74
       +
              ~docv:"FILE" ~doc:"File to attach (can be specified multiple times)")

     

       75
       75
       +
       

     

       76
       76
       +
       let reply_to_arg =

     

       77
       77
       +
         Arg.(value & opt (some string) None & info ["r"; "reply-to"] 

     

       78
       78
       +
              ~docv:"EMAIL_ID" ~doc:"Email ID to reply to")

     

       79
       79
       +
       

     

       80
       80
       +
       let draft_arg =

     

       81
       81
       +
         Arg.(value & flag & info ["d"; "draft"] 

     

       82
       82
       +
              ~doc:"Save as draft instead of sending")

     

       83
       83
       +
       

     

       84
       84
       +
       let send_arg =

     

       85
       85
       +
         Arg.(value & flag & info ["send"] 

     

       86
       86
       +
              ~doc:"Send the email immediately (default is to create draft)")

     

       87
       87
       +
       

     

       88
       88
       +
       (** Helper functions **)

     

       89
       89
       +
       

     

       90
       90
       +
       (* Read file contents *)

     

       91
       91
       +
       let read_file filename =

     

       92
       92
       +
         let ic = open_in filename in

     

       93
       93
       +
         let len = in_channel_length ic in

     

       94
       94
       +
         let content = really_input_string ic len in

     

       95
       95
       +
         close_in ic;

     

       96
       96
       +
         content

     

       97
       97
       +
       

     

       98
       98
       +
       (* Get MIME type from filename *)

     

       99
       99
       +
       let mime_type_from_filename filename =

     

       100
       100
       +
         match Filename.extension filename with

     

       101
       101
       +
         | ".pdf" -> "application/pdf"

     

       102
       102
       +
         | ".doc" | ".docx" -> "application/msword"

     

       103
       103
       +
         | ".xls" | ".xlsx" -> "application/vnd.ms-excel"

     

       104
       104
       +
         | ".jpg" | ".jpeg" -> "image/jpeg"

     

       105
       105
       +
         | ".png" -> "image/png"

     

       106
       106
       +
         | ".gif" -> "image/gif"

     

       107
       107
       +
         | ".txt" -> "text/plain"

     

       108
       108
       +
         | ".html" | ".htm" -> "text/html"

     

       109
       109
       +
         | ".zip" -> "application/zip"

     

       110
       110
       +
         | _ -> "application/octet-stream"

     

       111
       111
       +
       

     

       112
       112
       +
       (* Upload a file as a blob *)

     

       113
       113
       +
       let upload_attachment ctx session account_id filepath =

     

       114
       114
       +
         Printf.printf "Uploading %s...\n" filepath;

     

       115
       115
       +
         

     

       116
       116
       +
         let content = read_file filepath in

     

       117
       117
       +
         let filename = Filename.basename filepath in

     

       118
       118
       +
         let mime_type = mime_type_from_filename filename in

     

       119
       119
       +
         

     

       120
       120
       +
         (* Upload blob using the JMAP upload endpoint *)

     

       121
       121
       +
         let upload_url = Jmap.Session.Session.upload_url session in

     

       122
       122
       +
         let upload_endpoint = Printf.sprintf "%s/%s" (Uri.to_string upload_url) account_id in

     

       123
       123
       +
         

     

       124
       124
       +
         (* Simulate blob upload for type checking *)

     

       125
       125
       +
         Printf.printf "  Would upload to: %s\n" upload_endpoint;

     

       126
       126
       +
         Printf.printf "  Simulating upload of %s (%s, %d bytes)...\n" filename mime_type (String.length content);

     

       127
       127
       +
         

     

       128
       128
       +
         (* Create simulated blob info *)

     

       129
       129
       +
         let blob_info = Jmap.Binary.Upload_response.v

     

       130
       130
       +
           ~account_id:""

     

       131
       131
       +
           ~blob_id:("blob-" ^ filename ^ "-" ^ string_of_int (Random.int 99999))

     

       132
       132
       +
           ~type_:mime_type

     

       133
       133
       +
           ~size:(String.length content)

     

       134
       134
       +
           () in

     

       135
       135
       +
         Printf.printf "  Uploaded: %s (blob: %s, %d bytes)\n" 

     

       136
       136
       +
           filename 

     

       137
       137
       +
           (Jmap.Binary.Upload_response.blob_id blob_info)

     

       138
       138
       +
           (Jmap.Binary.Upload_response.size blob_info);

     

       139
       139
       +
         Ok blob_info

     

       140
       140
       +
       

     

       141
       141
       +
       (* Create email body parts *)

     

       142
       142
       +
       let create_body_parts options attachment_blobs =

     

       143
       143
       +
         let parts = ref [] in

     

       144
       144
       +
         

     

       145
       145
       +
         (* Add text body if provided *)

     

       146
       146
       +
         (match options.body_text with

     

       147
       147
       +
         | Some text ->

     

       148
       148
       +
             let text_part = Jmap_email.Types.Email_body_part.v

     

       149
       149
       +
               ~id:"text"

     

       150
       150
       +
               ~size:(String.length text)

     

       151
       151
       +
               ~headers:[]

     

       152
       152
       +
               ~mime_type:"text/plain"

     

       153
       153
       +
               ~charset:"utf-8"

     

       154
       154
       +
               () in

     

       155
       155
       +
             parts := text_part :: !parts

     

       156
       156
       +
         | None -> ());

     

       157
       157
       +
         

     

       158
       158
       +
         (* Add HTML body if provided *)

     

       159
       159
       +
         (match options.body_html with

     

       160
       160
       +
         | Some html ->

     

       161
       161
       +
             let html_part = Jmap_email.Types.Email_body_part.v

     

       162
       162
       +
               ~id:"html"

     

       163
       163
       +
               ~size:(String.length html)

     

       164
       164
       +
               ~headers:[]

     

       165
       165
       +
               ~mime_type:"text/html"

     

       166
       166
       +
               ~charset:"utf-8"

     

       167
       167
       +
               () in

     

       168
       168
       +
             parts := html_part :: !parts

     

       169
       169
       +
         | None -> ());

     

       170
       170
       +
         

     

       171
       171
       +
         (* Add attachments *)

     

       172
       172
       +
         List.iter2 (fun filepath blob_info ->

     

       173
       173
       +
           let filename = Filename.basename filepath in

     

       174
       174
       +
           let mime_type = mime_type_from_filename filename in

     

       175
       175
       +
           let attachment = Jmap_email.Types.Email_body_part.v

     

       176
       176
       +
             ~blob_id:(Jmap.Binary.Upload_response.blob_id blob_info)

     

       177
       177
       +
             ~size:(Jmap.Binary.Upload_response.size blob_info)

     

       178
       178
       +
             ~headers:[]

     

       179
       179
       +
             ~name:filename

     

       180
       180
       +
             ~mime_type

     

       181
       181
       +
             ~disposition:"attachment"

     

       182
       182
       +
             () in

     

       183
       183
       +
           parts := attachment :: !parts

     

       184
       184
       +
         ) options.attachments attachment_blobs;

     

       185
       185
       +
         

     

       186
       186
       +
         List.rev !parts

     

       187
       187
       +
       

     

       188
       188
       +
       (* Main compose and send function *)

     

       189
       189
       +
       let compose_and_send ctx session account_id options =

     

       190
       190
       +
         (* 1. Upload attachments first *)

     

       191
       191
       +
         let attachment_results = List.map (fun filepath ->

     

       192
       192
       +
           upload_attachment ctx session account_id filepath

     

       193
       193
       +
         ) options.attachments in

     

       194
       194
       +
         

     

       195
       195
       +
         let attachment_blobs = List.filter_map (function

     

       196
       196
       +
           | Ok blob -> Some blob

     

       197
       197
       +
           | Error () -> None

     

       198
       198
       +
         ) attachment_results in

     

       199
       199
       +
         

     

       200
       200
       +
         if List.length attachment_blobs < List.length options.attachments then (

     

       201
       201
       +
           Printf.eprintf "Warning: Some attachments failed to upload\n"

     

       202
       202
       +
         );

     

       203
       203
       +
         

     

       204
       204
       +
         (* 2. Create the email addresses *)

     

       205
       205
       +
         let to_addresses = List.map (fun email ->

     

       206
       206
       +
           Jmap_email.Types.Email_address.v ~email ()

     

       207
       207
       +
         ) options.to_recipients in

     

       208
       208
       +
         

     

       209
       209
       +
         let cc_addresses = List.map (fun email ->

     

       210
       210
       +
           Jmap_email.Types.Email_address.v ~email ()

     

       211
       211
       +
         ) options.cc_recipients in

     

       212
       212
       +
         

     

       213
       213
       +
         let bcc_addresses = List.map (fun email ->

     

       214
       214
       +
           Jmap_email.Types.Email_address.v ~email ()

     

       215
       215
       +
         ) options.bcc_recipients in

     

       216
       216
       +
         

     

       217
       217
       +
         (* 3. Get sender identity *)

     

       218
       218
       +
         let identity_args = Jmap.Methods.Get_args.v

     

       219
       219
       +
           ~account_id

     

       220
       220
       +
           ~properties:["id"; "email"; "name"]

     

       221
       221
       +
           () in

     

       222
       222
       +
           

     

       223
       223
       +
         let identity_invocation = Jmap.Wire.Invocation.v

     

       224
       224
       +
           ~method_name:"Identity/get"

     

       225
       225
       +
           ~arguments:(`Assoc []) (* Would serialize identity_args *)

     

       226
       226
       +
           ~method_call_id:"id1"

     

       227
       227
       +
           () in

     

       228
       228
       +
           

     

       229
       229
       +
         let request = Jmap.Wire.Request.v

     

       230
       230
       +
           ~using:[Jmap.capability_core; Jmap_email.capability_mail]

     

       231
       231
       +
           ~method_calls:[identity_invocation]

     

       232
       232
       +
           () in

     

       233
       233
       +
           

     

       234
       234
       +
         let default_identity = match Jmap_unix.request ctx request with

     

       235
       235
       +
           | Ok _ ->

     

       236
       236
       +
               (* Would extract from response *)

     

       237
       237
       +
               Jmap_email.Identity.v

     

       238
       238
       +
                 ~id:"identity1"

     

       239
       239
       +
                 ~email:account_id

     

       240
       240
       +
                 ~name:"User Name"

     

       241
       241
       +
                 ~may_delete:true

     

       242
       242
       +
                 ()

     

       243
       243
       +
           | Error _ ->

     

       244
       244
       +
               (* Fallback identity *)

     

       245
       245
       +
               Jmap_email.Identity.v

     

       246
       246
       +
                 ~id:"identity1"

     

       247
       247
       +
                 ~email:account_id

     

       248
       248
       +
                 ~may_delete:true

     

       249
       249
       +
                 ()

     

       250
       250
       +
         in

     

       251
       251
       +
         

     

       252
       252
       +
         (* 4. Create the draft email *)

     

       253
       253
       +
         let body_parts = create_body_parts options attachment_blobs in

     

       254
       254
       +
         

     

       255
       255
       +
         let draft_email = Jmap_email.Types.Email.create

     

       256
       256
       +
           ~subject:options.subject

     

       257
       257
       +
           ~from:[Jmap_email.Types.Email_address.v 

     

       258
       258
       +
                    ~email:(Jmap_email.Identity.email default_identity)

     

       259
       259
       +
                    ~name:(Jmap_email.Identity.name default_identity)

     

       260
       260
       +
                    ()]

     

       261
       261
       +
           ~to_:to_addresses

     

       262
       262
       +
           ~cc:cc_addresses

     

       263
       263
       +
           ~keywords:(Jmap_email.Types.Keywords.of_list [Jmap_email.Types.Keywords.Draft])

     

       264
       264
       +
           ~text_body:body_parts

     

       265
       265
       +
           () in

     

       266
       266
       +
           

     

       267
       267
       +
         (* 5. Create the email using Email/set *)

     

       268
       268
       +
         let create_map = Hashtbl.create 1 in

     

       269
       269
       +
         Hashtbl.add create_map "draft1" draft_email;

     

       270
       270
       +
         

     

       271
       271
       +
         let create_args = Jmap.Methods.Set_args.v

     

       272
       272
       +
           ~account_id

     

       273
       273
       +
           ~create:create_map

     

       274
       274
       +
           () in

     

       275
       275
       +
           

     

       276
       276
       +
         let create_invocation = Jmap.Wire.Invocation.v

     

       277
       277
       +
           ~method_name:"Email/set"

     

       278
       278
       +
           ~arguments:(`Assoc []) (* Would serialize create_args *)

     

       279
       279
       +
           ~method_call_id:"create1"

     

       280
       280
       +
           () in

     

       281
       281
       +
           

     

       282
       282
       +
         (* 6. If sending, also create EmailSubmission *)

     

       283
       283
       +
         let method_calls = if options.send && not options.draft then

     

       284
       284
       +
           let submission = {

     

       285
       285
       +
             Jmap_email.Submission.email_sub_create_identity_id = Jmap_email.Identity.id default_identity;

     

       286
       286
       +
             email_sub_create_email_id = "#draft1"; (* Back-reference to created email *)

     

       287
       287
       +
             email_sub_create_envelope = None;

     

       288
       288
       +
           } in

     

       289
       289
       +
             

     

       290
       290
       +
           let submit_map = Hashtbl.create 1 in

     

       291
       291
       +
           Hashtbl.add submit_map "submission1" submission;

     

       292
       292
       +
           

     

       293
       293
       +
           let submit_args = Jmap.Methods.Set_args.v

     

       294
       294
       +
             ~account_id

     

       295
       295
       +
             ~create:submit_map

     

       296
       296
       +
             () in

     

       297
       297
       +
             

     

       298
       298
       +
           let submit_invocation = Jmap.Wire.Invocation.v

     

       299
       299
       +
             ~method_name:"EmailSubmission/set"

     

       300
       300
       +
             ~arguments:(`Assoc []) (* Would serialize submit_args *)

     

       301
       301
       +
             ~method_call_id:"submit1"

     

       302
       302
       +
             () in

     

       303
       303
       +
             

     

       304
       304
       +
           [create_invocation; submit_invocation]

     

       305
       305
       +
         else

     

       306
       306
       +
           [create_invocation]

     

       307
       307
       +
         in

     

       308
       308
       +
         

     

       309
       309
       +
         (* 7. Send the request *)

     

       310
       310
       +
         let request = Jmap.Wire.Request.v

     

       311
       311
       +
           ~using:[Jmap.capability_core; Jmap_email.capability_mail; Jmap_email.capability_submission]

     

       312
       312
       +
           ~method_calls

     

       313
       313
       +
           () in

     

       314
       314
       +
           

     

       315
       315
       +
         match Jmap_unix.request ctx request with

     

       316
       316
       +
         | Ok response ->

     

       317
       317
       +
             if options.send && not options.draft then

     

       318
       318
       +
               Printf.printf "\nEmail sent successfully!\n"

     

       319
       319
       +
             else

     

       320
       320
       +
               Printf.printf "\nDraft saved successfully!\n";

     

       321
       321
       +
             0

     

       322
       322
       +
         | Error e ->

     

       323
       323
       +
             Printf.eprintf "\nFailed to create email: %s\n" (Jmap.Error.error_to_string e);

     

       324
       324
       +
             1

     

       325
       325
       +
       

     

       326
       326
       +
       (* Command implementation *)

     

       327
       327
       +
       let compose_command host user password to_list cc_list bcc_list subject 

     

       328
       328
       +
                           body body_file html html_file attachments reply_to 

     

       329
       329
       +
                           draft send : int =

     

       330
       330
       +
         Printf.printf "JMAP Email Composer\n";

     

       331
       331
       +
         Printf.printf "Server: %s\n" host;

     

       332
       332
       +
         Printf.printf "User: %s\n\n" user;

     

       333
       333
       +
         

     

       334
       334
       +
         (* Validate arguments *)

     

       335
       335
       +
         if to_list = [] && cc_list = [] && bcc_list = [] then (

     

       336
       336
       +
           Printf.eprintf "Error: Must specify at least one recipient\n";

     

       337
       337
       +
           exit 1

     

       338
       338
       +
         );

     

       339
       339
       +
         

     

       340
       340
       +
         (* Read body content *)

     

       341
       341
       +
         let body_text = match body, body_file with

     

       342
       342
       +
           | Some text, _ -> Some text

     

       343
       343
       +
           | None, Some file -> Some (read_file file)

     

       344
       344
       +
           | None, None -> None

     

       345
       345
       +
         in

     

       346
       346
       +
         

     

       347
       347
       +
         let body_html = match html, html_file with

     

       348
       348
       +
           | Some text, _ -> Some text

     

       349
       349
       +
           | None, Some file -> Some (read_file file)

     

       350
       350
       +
           | None, None -> None

     

       351
       351
       +
         in

     

       352
       352
       +
         

     

       353
       353
       +
         if body_text = None && body_html = None then (

     

       354
       354
       +
           Printf.eprintf "Error: Must provide email body (--body, --body-file, --html, or --html-file)\n";

     

       355
       355
       +
           exit 1

     

       356
       356
       +
         );

     

       357
       357
       +
         

     

       358
       358
       +
         (* Create options record *)

     

       359
       359
       +
         let options = {

     

       360
       360
       +
           to_recipients = to_list;

     

       361
       361
       +
           cc_recipients = cc_list;

     

       362
       362
       +
           bcc_recipients = bcc_list;

     

       363
       363
       +
           subject;

     

       364
       364
       +
           body_text;

     

       365
       365
       +
           body_html;

     

       366
       366
       +
           attachments;

     

       367
       367
       +
           in_reply_to = reply_to;

     

       368
       368
       +
           draft;

     

       369
       369
       +
           send = send || not draft; (* Send by default unless draft flag is set *)

     

       370
       370
       +
         } in

     

       371
       371
       +
         

     

       372
       372
       +
         (* Connect to server *)

     

       373
       373
       +
         let ctx = Jmap_unix.create_client () in

     

       374
       374
       +
         let result = Jmap_unix.quick_connect ~host ~username:user ~password in

     

       375
       375
       +
         

     

       376
       376
       +
         let (ctx, session) = match result with

     

       377
       377
       +
           | Ok (ctx, session) -> (ctx, session)

     

       378
       378
       +
           | Error e -> 

     

       379
       379
       +
               Printf.eprintf "Connection failed: %s\n" (Jmap.Error.error_to_string e);

     

       380
       380
       +
               exit 1

     

       381
       381
       +
         in

     

       382
       382
       +
         

     

       383
       383
       +
         (* Get the primary account ID *)

     

       384
       384
       +
         let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       385
       385
       +
           | Ok id -> id

     

       386
       386
       +
           | Error e -> 

     

       387
       387
       +
               Printf.eprintf "No mail account found: %s\n" (Jmap.Error.error_to_string e);

     

       388
       388
       +
               exit 1

     

       389
       389
       +
         in

     

       390
       390
       +
         

     

       391
       391
       +
         (* Compose and send/save the email *)

     

       392
       392
       +
         compose_and_send ctx session account_id options

     

       393
       393
       +
       

     

       394
       394
       +
       (* Command definition *)

     

       395
       395
       +
       let compose_cmd =

     

       396
       396
       +
         let doc = "compose and send emails via JMAP" in

     

       397
       397
       +
         let man = [

     

       398
       398
       +
           `S Manpage.s_description;

     

       399
       399
       +
           `P "Compose and send emails using the JMAP protocol.";

     

       400
       400
       +
           `P "Supports plain text and HTML bodies, attachments, and drafts.";

     

       401
       401
       +
           `S Manpage.s_examples;

     

       402
       402
       +
           `P "Send a simple email:";

     

       403
       403
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 \\";

     

       404
       404
       +
           `P "    -t recipient@example.com -s \"Meeting reminder\" \\";

     

       405
       405
       +
           `P "    --body \"Don't forget our meeting at 3pm!\"";

     

       406
       406
       +
           `P "";

     

       407
       407
       +
           `P "Send email with attachment:";

     

       408
       408
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 \\";

     

       409
       409
       +
           `P "    -t recipient@example.com -s \"Report attached\" \\";

     

       410
       410
       +
           `P "    --body-file message.txt -a report.pdf";

     

       411
       411
       +
           `P "";

     

       412
       412
       +
           `P "Save as draft:";

     

       413
       413
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 \\";

     

       414
       414
       +
           `P "    -t recipient@example.com -s \"Work in progress\" \\";

     

       415
       415
       +
           `P "    --body \"Still working on this...\" --draft";

     

       416
       416
       +
         ] in

     

       417
       417
       +
         

     

       418
       418
       +
         let cmd =

     

       419
       419
       +
           Cmd.v

     

       420
       420
       +
             (Cmd.info "jmap-email-composer" ~version:"1.0" ~doc ~man)

     

       421
       421
       +
             Term.(const compose_command $ host_arg $ user_arg $ password_arg $ 

     

       422
       422
       +
                   to_arg $ cc_arg $ bcc_arg $ subject_arg $ body_arg $ body_file_arg $

     

       423
       423
       +
                   html_arg $ html_file_arg $ attach_arg $ reply_to_arg $ 

     

       424
       424
       +
                   draft_arg $ send_arg)

     

       425
       425
       +
         in

     

       426
       426
       +
         cmd

     

       427
       427
       +
       

     

       428
       428
       +
       (* Main entry point *)

     

       429
       429
       +
       let () = exit (Cmd.eval' compose_cmd)

+436

bin/jmap_email_search.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_email_search.ml - A comprehensive email search utility using JMAP

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates JMAP's query capabilities for email searching,

     

       5
       5
       +
        * filtering, and sorting.

     

       6
       6
       +
        *

     

       7
       7
       +
        * For step 2, we're only testing type checking. No implementations required.

     

       8
       8
       +
        *)

     

       9
       9
       +
       

     

       10
       10
       +
       open Cmdliner

     

       11
       11
       +
       

     

       12
       12
       +
       (** Email search arguments type *)

     

       13
       13
       +
       type email_search_args = {

     

       14
       14
       +
         query : string;

     

       15
       15
       +
         from : string option;

     

       16
       16
       +
         to_ : string option;

     

       17
       17
       +
         subject : string option;

     

       18
       18
       +
         before : string option;

     

       19
       19
       +
         after : string option;

     

       20
       20
       +
         has_attachment : bool;

     

       21
       21
       +
         mailbox : string option;

     

       22
       22
       +
         is_unread : bool;

     

       23
       23
       +
         limit : int;

     

       24
       24
       +
         sort : [`DateDesc | `DateAsc | `From | `To | `Subject | `Size];

     

       25
       25
       +
         format : [`Summary | `Json | `Detailed];

     

       26
       26
       +
       }

     

       27
       27
       +
       

     

       28
       28
       +
       (* Module to convert ISO 8601 date strings to Unix timestamps *)

     

       29
       29
       +
       module Date_converter = struct

     

       30
       30
       +
         (* Convert an ISO date string (YYYY-MM-DD) to Unix timestamp *)

     

       31
       31
       +
         let parse_date date_str =

     

       32
       32
       +
           try

     

       33
       33
       +
             (* Parse YYYY-MM-DD format *)

     

       34
       34
       +
             let (year, month, day) = Scanf.sscanf date_str "%d-%d-%d" (fun y m d -> (y, m, d)) in

     

       35
       35
       +
             

     

       36
       36
       +
             (* Convert to Unix timestamp (midnight UTC of that day) *)

     

       37
       37
       +
             let tm = Unix.{ tm_sec = 0; tm_min = 0; tm_hour = 0;

     

       38
       38
       +
                             tm_mday = day; tm_mon = month - 1; tm_year = year - 1900;

     

       39
       39
       +
                             tm_wday = 0; tm_yday = 0; tm_isdst = false } in

     

       40
       40
       +
             Some (Unix.mktime tm |> fst)

     

       41
       41
       +
           with _ ->

     

       42
       42
       +
             Printf.eprintf "Invalid date format: %s (use YYYY-MM-DD)\n" date_str;

     

       43
       43
       +
             None

     

       44
       44
       +
             

     

       45
       45
       +
         (* Format a Unix timestamp as ISO 8601 *)

     

       46
       46
       +
         let format_datetime time =

     

       47
       47
       +
           let tm = Unix.gmtime time in

     

       48
       48
       +
           Printf.sprintf "%04d-%02d-%02dT%02d:%02d:%02dZ"

     

       49
       49
       +
             (tm.Unix.tm_year + 1900) (tm.Unix.tm_mon + 1) tm.Unix.tm_mday

     

       50
       50
       +
             tm.Unix.tm_hour tm.Unix.tm_min tm.Unix.tm_sec

     

       51
       51
       +
       end

     

       52
       52
       +
       

     

       53
       53
       +
       (** Command-line arguments **)

     

       54
       54
       +
       

     

       55
       55
       +
       let host_arg =

     

       56
       56
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       57
       57
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       58
       58
       +
       

     

       59
       59
       +
       let user_arg =

     

       60
       60
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       61
       61
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       62
       62
       +
       

     

       63
       63
       +
       let password_arg =

     

       64
       64
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       65
       65
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       66
       66
       +
       

     

       67
       67
       +
       let query_arg =

     

       68
       68
       +
         Arg.(value & opt string "" & info ["q"; "query"] 

     

       69
       69
       +
              ~docv:"QUERY" ~doc:"Text to search for in emails")

     

       70
       70
       +
       

     

       71
       71
       +
       let from_arg =

     

       72
       72
       +
         Arg.(value & opt (some string) None & info ["from"] 

     

       73
       73
       +
              ~docv:"EMAIL" ~doc:"Filter by sender email address")

     

       74
       74
       +
       

     

       75
       75
       +
       let to_arg =

     

       76
       76
       +
         Arg.(value & opt (some string) None & info ["to"] 

     

       77
       77
       +
              ~docv:"EMAIL" ~doc:"Filter by recipient email address")

     

       78
       78
       +
       

     

       79
       79
       +
       let subject_arg =

     

       80
       80
       +
         Arg.(value & opt (some string) None & info ["subject"] 

     

       81
       81
       +
              ~docv:"SUBJECT" ~doc:"Filter by subject text")

     

       82
       82
       +
       

     

       83
       83
       +
       let before_arg =

     

       84
       84
       +
         Arg.(value & opt (some string) None & info ["before"] 

     

       85
       85
       +
              ~docv:"DATE" ~doc:"Show emails before date (YYYY-MM-DD)")

     

       86
       86
       +
       

     

       87
       87
       +
       let after_arg =

     

       88
       88
       +
         Arg.(value & opt (some string) None & info ["after"] 

     

       89
       89
       +
              ~docv:"DATE" ~doc:"Show emails after date (YYYY-MM-DD)")

     

       90
       90
       +
       

     

       91
       91
       +
       let has_attachment_arg =

     

       92
       92
       +
         Arg.(value & flag & info ["has-attachment"] 

     

       93
       93
       +
              ~doc:"Filter to emails with attachments")

     

       94
       94
       +
       

     

       95
       95
       +
       let mailbox_arg =

     

       96
       96
       +
         Arg.(value & opt (some string) None & info ["mailbox"] 

     

       97
       97
       +
              ~docv:"MAILBOX" ~doc:"Filter by mailbox name")

     

       98
       98
       +
       

     

       99
       99
       +
       let is_unread_arg =

     

       100
       100
       +
         Arg.(value & flag & info ["unread"] 

     

       101
       101
       +
              ~doc:"Show only unread emails")

     

       102
       102
       +
       

     

       103
       103
       +
       let limit_arg =

     

       104
       104
       +
         Arg.(value & opt int 20 & info ["limit"] 

     

       105
       105
       +
              ~docv:"N" ~doc:"Maximum number of results to return")

     

       106
       106
       +
       

     

       107
       107
       +
       let sort_arg =

     

       108
       108
       +
         Arg.(value & opt (enum [

     

       109
       109
       +
           "date-desc", `DateDesc;

     

       110
       110
       +
           "date-asc", `DateAsc;

     

       111
       111
       +
           "from", `From;

     

       112
       112
       +
           "to", `To;

     

       113
       113
       +
           "subject", `Subject;

     

       114
       114
       +
           "size", `Size;

     

       115
       115
       +
         ]) `DateDesc & info ["sort"] ~docv:"FIELD" 

     

       116
       116
       +
              ~doc:"Sort results by field")

     

       117
       117
       +
       

     

       118
       118
       +
       let format_arg =

     

       119
       119
       +
         Arg.(value & opt (enum [

     

       120
       120
       +
           "summary", `Summary;

     

       121
       121
       +
           "json", `Json;

     

       122
       122
       +
           "detailed", `Detailed;

     

       123
       123
       +
         ]) `Summary & info ["format"] ~docv:"FORMAT" 

     

       124
       124
       +
              ~doc:"Output format")

     

       125
       125
       +
       

     

       126
       126
       +
       (** Main functionality **)

     

       127
       127
       +
       

     

       128
       128
       +
       (* Create a filter based on command-line arguments - this function uses the actual JMAP API *)

     

       129
       129
       +
       let create_filter _account_id mailbox_id_opt args =

     

       130
       130
       +
         let open Jmap.Methods.Filter in

     

       131
       131
       +
         let filters = [] in

     

       132
       132
       +
         

     

       133
       133
       +
         (* Add filter conditions based on command-line args *)

     

       134
       134
       +
         let filters = match args.query with 

     

       135
       135
       +
           | "" -> filters 

     

       136
       136
       +
           | query -> Jmap_email.Email_filter.subject query :: filters 

     

       137
       137
       +
         in

     

       138
       138
       +
         

     

       139
       139
       +
         let filters = match args.from with

     

       140
       140
       +
           | None -> filters

     

       141
       141
       +
           | Some sender -> Jmap_email.Email_filter.from sender :: filters

     

       142
       142
       +
         in

     

       143
       143
       +
         

     

       144
       144
       +
         let filters = match args.to_ with

     

       145
       145
       +
           | None -> filters

     

       146
       146
       +
           | Some recipient -> Jmap_email.Email_filter.to_ recipient :: filters

     

       147
       147
       +
         in

     

       148
       148
       +
         

     

       149
       149
       +
         let filters = match args.subject with

     

       150
       150
       +
           | None -> filters

     

       151
       151
       +
           | Some subj -> Jmap_email.Email_filter.subject subj :: filters

     

       152
       152
       +
         in

     

       153
       153
       +
         

     

       154
       154
       +
         let filters = match args.before with

     

       155
       155
       +
           | None -> filters

     

       156
       156
       +
           | Some date_str -> 

     

       157
       157
       +
               match Date_converter.parse_date date_str with

     

       158
       158
       +
               | Some date -> Jmap_email.Email_filter.before date :: filters

     

       159
       159
       +
               | None -> filters

     

       160
       160
       +
         in

     

       161
       161
       +
         

     

       162
       162
       +
         let filters = match args.after with

     

       163
       163
       +
           | None -> filters

     

       164
       164
       +
           | Some date_str -> 

     

       165
       165
       +
               match Date_converter.parse_date date_str with

     

       166
       166
       +
               | Some date -> Jmap_email.Email_filter.after date :: filters

     

       167
       167
       +
               | None -> filters

     

       168
       168
       +
         in

     

       169
       169
       +
         

     

       170
       170
       +
         let filters = if args.has_attachment then Jmap_email.Email_filter.has_attachment () :: filters else filters in

     

       171
       171
       +
         

     

       172
       172
       +
         let filters = if args.is_unread then Jmap_email.Email_filter.unread () :: filters else filters in

     

       173
       173
       +
         

     

       174
       174
       +
         let filters = match mailbox_id_opt with

     

       175
       175
       +
           | None -> filters

     

       176
       176
       +
           | Some mailbox_id -> Jmap_email.Email_filter.in_mailbox mailbox_id :: filters

     

       177
       177
       +
         in

     

       178
       178
       +
         

     

       179
       179
       +
         (* Combine all filters with AND *)

     

       180
       180
       +
         match filters with

     

       181
       181
       +
         | [] -> condition (`Assoc [])  (* Empty filter *)

     

       182
       182
       +
         | [f] -> f

     

       183
       183
       +
         | filters -> and_ filters

     

       184
       184
       +
       

     

       185
       185
       +
       (* Create sort comparator based on command-line arguments *)

     

       186
       186
       +
       let create_sort args =

     

       187
       187
       +
         match args.sort with

     

       188
       188
       +
         | `DateDesc -> Jmap_email.Email_sort.received_newest_first ()

     

       189
       189
       +
         | `DateAsc -> Jmap_email.Email_sort.received_oldest_first ()

     

       190
       190
       +
         | `From -> Jmap_email.Email_sort.from_asc ()

     

       191
       191
       +
         | `To -> Jmap_email.Email_sort.subject_asc ()  (* Using subject as proxy for 'to' *)

     

       192
       192
       +
         | `Subject -> Jmap_email.Email_sort.subject_asc ()

     

       193
       193
       +
         | `Size -> Jmap_email.Email_sort.size_largest_first ()

     

       194
       194
       +
       

     

       195
       195
       +
       (* Display email results based on format option *)

     

       196
       196
       +
       let display_results emails format =

     

       197
       197
       +
         match format with

     

       198
       198
       +
         | `Summary ->

     

       199
       199
       +
             emails |> List.iteri (fun i email ->

     

       200
       200
       +
               let id = Option.value (Jmap_email.Types.Email.id email) ~default:"(no id)" in

     

       201
       201
       +
               let subject = Option.value (Jmap_email.Types.Email.subject email) ~default:"(no subject)" in

     

       202
       202
       +
               let from_list = Option.value (Jmap_email.Types.Email.from email) ~default:[] in

     

       203
       203
       +
               let from = match from_list with

     

       204
       204
       +
                 | [] -> "(no sender)"

     

       205
       205
       +
                 | addr::_ -> Jmap_email.Types.Email_address.email addr

     

       206
       206
       +
               in

     

       207
       207
       +
               let date = match Jmap_email.Types.Email.received_at email with

     

       208
       208
       +
                 | Some d -> Date_converter.format_datetime d

     

       209
       209
       +
                 | None -> "(no date)"

     

       210
       210
       +
               in

     

       211
       211
       +
               Printf.printf "%3d) [%s] %s\n     From: %s\n     Date: %s\n\n" 

     

       212
       212
       +
                 (i+1) id subject from date

     

       213
       213
       +
             );

     

       214
       214
       +
             0

     

       215
       215
       +
         

     

       216
       216
       +
         | `Detailed ->

     

       217
       217
       +
             emails |> List.iteri (fun i email ->

     

       218
       218
       +
               let id = Option.value (Jmap_email.Types.Email.id email) ~default:"(no id)" in

     

       219
       219
       +
               let subject = Option.value (Jmap_email.Types.Email.subject email) ~default:"(no subject)" in

     

       220
       220
       +
               let thread_id = Option.value (Jmap_email.Types.Email.thread_id email) ~default:"(no thread)" in

     

       221
       221
       +
               

     

       222
       222
       +
               let from_list = Option.value (Jmap_email.Types.Email.from email) ~default:[] in

     

       223
       223
       +
               let from = match from_list with

     

       224
       224
       +
                 | [] -> "(no sender)"

     

       225
       225
       +
                 | addr::_ -> Jmap_email.Types.Email_address.email addr

     

       226
       226
       +
               in

     

       227
       227
       +
               

     

       228
       228
       +
               let to_list = Option.value (Jmap_email.Types.Email.to_ email) ~default:[] in

     

       229
       229
       +
               let to_str = to_list 

     

       230
       230
       +
                 |> List.map Jmap_email.Types.Email_address.email

     

       231
       231
       +
                 |> String.concat ", " in

     

       232
       232
       +
               

     

       233
       233
       +
               let date = match Jmap_email.Types.Email.received_at email with

     

       234
       234
       +
                 | Some d -> Date_converter.format_datetime d

     

       235
       235
       +
                 | None -> "(no date)"

     

       236
       236
       +
               in

     

       237
       237
       +
               

     

       238
       238
       +
               let keywords = match Jmap_email.Types.Email.keywords email with

     

       239
       239
       +
                 | Some kw -> Jmap_email.Types.Keywords.custom_keywords kw 

     

       240
       240
       +
                              |> String.concat ", "

     

       241
       241
       +
                 | None -> "(none)"

     

       242
       242
       +
               in

     

       243
       243
       +
               

     

       244
       244
       +
               let has_attachment = match Jmap_email.Types.Email.has_attachment email with

     

       245
       245
       +
                 | Some true -> "Yes"

     

       246
       246
       +
                 | _ -> "No"

     

       247
       247
       +
               in

     

       248
       248
       +
               

     

       249
       249
       +
               Printf.printf "Email %d:\n" (i+1);

     

       250
       250
       +
               Printf.printf "  ID:        %s\n" id;

     

       251
       251
       +
               Printf.printf "  Subject:   %s\n" subject;

     

       252
       252
       +
               Printf.printf "  From:      %s\n" from;

     

       253
       253
       +
               Printf.printf "  To:        %s\n" to_str;

     

       254
       254
       +
               Printf.printf "  Date:      %s\n" date;

     

       255
       255
       +
               Printf.printf "  Thread:    %s\n" thread_id;

     

       256
       256
       +
               Printf.printf "  Flags:     %s\n" keywords;

     

       257
       257
       +
               Printf.printf "  Attachment:%s\n" has_attachment;

     

       258
       258
       +
               

     

       259
       259
       +
               match Jmap_email.Types.Email.preview email with

     

       260
       260
       +
               | Some text -> Printf.printf "  Preview:   %s\n" text

     

       261
       261
       +
               | None -> ();

     

       262
       262
       +
               

     

       263
       263
       +
               Printf.printf "\n"

     

       264
       264
       +
             );

     

       265
       265
       +
             0

     

       266
       266
       +
             

     

       267
       267
       +
         | `Json ->

     

       268
       268
       +
             (* In a real implementation, this would properly convert emails to JSON *)

     

       269
       269
       +
             Printf.printf "{\n  \"results\": [\n";

     

       270
       270
       +
             emails |> List.iteri (fun i email ->

     

       271
       271
       +
               let id = Option.value (Jmap_email.Types.Email.id email) ~default:"" in

     

       272
       272
       +
               let subject = Option.value (Jmap_email.Types.Email.subject email) ~default:"" in

     

       273
       273
       +
               Printf.printf "    {\"id\": \"%s\", \"subject\": \"%s\"%s\n" 

     

       274
       274
       +
                 id subject (if i < List.length emails - 1 then "}," else "}")

     

       275
       275
       +
             );

     

       276
       276
       +
             Printf.printf "  ]\n}\n";

     

       277
       277
       +
             0

     

       278
       278
       +
       

     

       279
       279
       +
       (* Command implementation - using the real JMAP interface *)

     

       280
       280
       +
       let search_command host user password query from to_ subject before after 

     

       281
       281
       +
                          has_attachment mailbox is_unread limit sort format : int =

     

       282
       282
       +
         (* Pack arguments into a record for easier passing *)

     

       283
       283
       +
         let args : email_search_args = {

     

       284
       284
       +
           query; from; to_ = to_; subject; before; after; 

     

       285
       285
       +
           has_attachment; mailbox; is_unread; limit; sort; format

     

       286
       286
       +
         } in

     

       287
       287
       +
         

     

       288
       288
       +
         Printf.printf "JMAP Email Search\n";

     

       289
       289
       +
         Printf.printf "Server: %s\n" host;

     

       290
       290
       +
         Printf.printf "User: %s\n\n" user;

     

       291
       291
       +
         

     

       292
       292
       +
         (* The following code demonstrates using the JMAP library interface

     

       293
       293
       +
            but doesn't actually run it for Step 2 (it will get a linker error,

     

       294
       294
       +
            which is expected since there's no implementation yet) *)

     

       295
       295
       +
         

     

       296
       296
       +
         let process_search () =

     

       297
       297
       +
           (* 1. Create client context and connect to server *)

     

       298
       298
       +
           let _orig_ctx = Jmap_unix.create_client () in

     

       299
       299
       +
           let result = Jmap_unix.quick_connect ~host ~username:user ~password in

     

       300
       300
       +
           

     

       301
       301
       +
           let (ctx, session) = match result with

     

       302
       302
       +
             | Ok (ctx, session) -> (ctx, session)

     

       303
       303
       +
             | Error _ -> failwith "Could not connect to server"

     

       304
       304
       +
           in

     

       305
       305
       +
           

     

       306
       306
       +
           (* 2. Get the primary account ID for mail capability *)

     

       307
       307
       +
           let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       308
       308
       +
             | Ok id -> id

     

       309
       309
       +
             | Error _ -> failwith "No mail account found"

     

       310
       310
       +
           in

     

       311
       311
       +
           

     

       312
       312
       +
           (* 3. Resolve mailbox name to ID if specified *)

     

       313
       313
       +
           let mailbox_id_opt = match args.mailbox with

     

       314
       314
       +
             | None -> None

     

       315
       315
       +
             | Some _name ->

     

       316
       316
       +
                 (* This would use Mailbox/query and Mailbox/get to resolve the name *)

     

       317
       317
       +
                 (* For now just simulate a mailbox ID *)

     

       318
       318
       +
                 Some "mailbox123"

     

       319
       319
       +
           in

     

       320
       320
       +
           

     

       321
       321
       +
           (* 4. Create filter based on search criteria *)

     

       322
       322
       +
           let filter = create_filter account_id mailbox_id_opt args in

     

       323
       323
       +
           

     

       324
       324
       +
           (* 5. Create sort comparator *)

     

       325
       325
       +
           let sort = create_sort args in

     

       326
       326
       +
           

     

       327
       327
       +
           (* 6. Prepare Email/query request *)

     

       328
       328
       +
           let _query_args = Jmap.Methods.Query_args.v

     

       329
       329
       +
             ~account_id

     

       330
       330
       +
             ~filter

     

       331
       331
       +
             ~sort:[sort]

     

       332
       332
       +
             ~position:0

     

       333
       333
       +
             ~limit:args.limit

     

       334
       334
       +
             ~calculate_total:true

     

       335
       335
       +
             () in

     

       336
       336
       +
             

     

       337
       337
       +
           let query_invocation = Jmap.Wire.Invocation.v

     

       338
       338
       +
             ~method_name:"Email/query"

     

       339
       339
       +
             ~arguments:(`Assoc []) (* In real code, we'd serialize query_args to JSON *)

     

       340
       340
       +
             ~method_call_id:"q1"

     

       341
       341
       +
             () in

     

       342
       342
       +
           

     

       343
       343
       +
           (* 7. Prepare Email/get request with back-reference to query results *)

     

       344
       344
       +
           let get_properties = [

     

       345
       345
       +
             "id"; "threadId"; "mailboxIds"; "keywords"; "size";

     

       346
       346
       +
             "receivedAt"; "messageId"; "inReplyTo"; "references";

     

       347
       347
       +
             "sender"; "from"; "to"; "cc"; "bcc"; "replyTo";

     

       348
       348
       +
             "subject"; "sentAt"; "hasAttachment"; "preview" 

     

       349
       349
       +
           ] in

     

       350
       350
       +
           

     

       351
       351
       +
           let _get_args = Jmap.Methods.Get_args.v

     

       352
       352
       +
             ~account_id

     

       353
       353
       +
             ~properties:get_properties

     

       354
       354
       +
             () in

     

       355
       355
       +
           

     

       356
       356
       +
           let get_invocation = Jmap.Wire.Invocation.v

     

       357
       357
       +
             ~method_name:"Email/get"

     

       358
       358
       +
             ~arguments:(`Assoc []) (* In real code, we'd serialize get_args to JSON *)

     

       359
       359
       +
             ~method_call_id:"g1"

     

       360
       360
       +
             () in

     

       361
       361
       +
           

     

       362
       362
       +
           (* 8. Prepare the JMAP request *)

     

       363
       363
       +
           let request = Jmap.Wire.Request.v

     

       364
       364
       +
             ~using:[Jmap.capability_core; Jmap_email.capability_mail]

     

       365
       365
       +
             ~method_calls:[query_invocation; get_invocation]

     

       366
       366
       +
             () in

     

       367
       367
       +
           

     

       368
       368
       +
           (* 9. Send the request *)

     

       369
       369
       +
           let response = match Jmap_unix.request ctx request with

     

       370
       370
       +
             | Ok response -> response

     

       371
       371
       +
             | Error _ -> failwith "Request failed"

     

       372
       372
       +
           in

     

       373
       373
       +
           

     

       374
       374
       +
           (* Helper to find a method response by ID *)

     

       375
       375
       +
           let find_method_response response id =

     

       376
       376
       +
             let open Jmap.Wire in

     

       377
       377
       +
             let responses = Response.method_responses response in

     

       378
       378
       +
             let find_by_id inv =

     

       379
       379
       +
               match inv with

     

       380
       380
       +
               | Ok invocation when Invocation.method_call_id invocation = id -> 

     

       381
       381
       +
                   Some (Invocation.method_name invocation, Invocation.arguments invocation)

     

       382
       382
       +
               | _ -> None

     

       383
       383
       +
             in

     

       384
       384
       +
             List.find_map find_by_id responses

     

       385
       385
       +
           in

     

       386
       386
       +
           

     

       387
       387
       +
           (* 10. Process the response *)

     

       388
       388
       +
           match find_method_response response "g1" with

     

       389
       389
       +
           | Some (method_name, _) when method_name = "Email/get" ->

     

       390
       390
       +
               (* We would extract the emails from the response here *)

     

       391
       391
       +
               (* For now, just create a sample email for type checking *)

     

       392
       392
       +
               let email = Jmap_email.Types.Email.create

     

       393
       393
       +
                 ~id:"email123"

     

       394
       394
       +
                 ~thread_id:"thread456"

     

       395
       395
       +
                 ~subject:"Test Email"

     

       396
       396
       +
                 ~from:[Jmap_email.Types.Email_address.v ~name:"Sender" ~email:"sender@example.com" ()]

     

       397
       397
       +
                 ~to_:[Jmap_email.Types.Email_address.v ~name:"Recipient" ~email:"recipient@example.com" ()]

     

       398
       398
       +
                 ~received_at:1588000000.0

     

       399
       399
       +
                 ~has_attachment:true

     

       400
       400
       +
                 ~preview:"This is a test email..."

     

       401
       401
       +
                 ~keywords:(Jmap_email.Types.Keywords.of_list [Jmap_email.Types.Keywords.Seen])

     

       402
       402
       +
                 () in

     

       403
       403
       +
                 

     

       404
       404
       +
               (* Display the result *)

     

       405
       405
       +
               display_results [email] args.format

     

       406
       406
       +
           | _ ->

     

       407
       407
       +
               Printf.eprintf "Error: Invalid response\n";

     

       408
       408
       +
               1

     

       409
       409
       +
         in

     

       410
       410
       +
         

     

       411
       411
       +
         (* Note: Since we're only type checking, this won't actually run *)

     

       412
       412
       +
         process_search ()

     

       413
       413
       +
       

     

       414
       414
       +
       (* Command definition *)

     

       415
       415
       +
       let search_cmd =

     

       416
       416
       +
         let doc = "search emails using JMAP query capabilities" in

     

       417
       417
       +
         let man = [

     

       418
       418
       +
           `S Manpage.s_description;

     

       419
       419
       +
           `P "Searches for emails on a JMAP server with powerful filtering capabilities.";

     

       420
       420
       +
           `P "Demonstrates the rich query functions available in the JMAP protocol.";

     

       421
       421
       +
           `S Manpage.s_examples;

     

       422
       422
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 -q \"important meeting\"";

     

       423
       423
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --from boss@company.com --after 2023-01-01";

     

       424
       424
       +
         ] in

     

       425
       425
       +
         

     

       426
       426
       +
         let cmd =

     

       427
       427
       +
           Cmd.v

     

       428
       428
       +
             (Cmd.info "jmap-email-search" ~version:"1.0" ~doc ~man)

     

       429
       429
       +
             Term.(const search_command $ host_arg $ user_arg $ password_arg $ 

     

       430
       430
       +
                   query_arg $ from_arg $ to_arg $ subject_arg $ before_arg $ after_arg $ 

     

       431
       431
       +
                   has_attachment_arg $ mailbox_arg $ is_unread_arg $ limit_arg $ sort_arg $ format_arg)

     

       432
       432
       +
         in

     

       433
       433
       +
         cmd

     

       434
       434
       +
       

     

       435
       435
       +
       (* Main entry point *)

     

       436
       436
       +
       let () = exit (Cmd.eval' search_cmd)

+706

bin/jmap_flag_manager.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_flag_manager.ml - A tool for managing email flags (keywords) using JMAP

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates JMAP's flag management capabilities, allowing

     

       5
       5
       +
        * powerful query-based selection and batch flag operations.

     

       6
       6
       +
        *)

     

       7
       7
       +
       

     

       8
       8
       +
       open Cmdliner

     

       9
       9
       +
       (* Using standard OCaml, no Lwt *)

     

       10
       10
       +
       

     

       11
       11
       +
       (* JMAP imports *)

     

       12
       12
       +
       open Jmap.Methods

     

       13
       13
       +
       open Jmap_email

     

       14
       14
       +
       (* For step 2, we're only testing type checking. No implementations required. *)

     

       15
       15
       +
       

     

       16
       16
       +
       (* Dummy Unix module for type checking *)

     

       17
       17
       +
       module Unix = struct

     

       18
       18
       +
         type tm = {

     

       19
       19
       +
           tm_sec : int;

     

       20
       20
       +
           tm_min : int;

     

       21
       21
       +
           tm_hour : int;

     

       22
       22
       +
           tm_mday : int;

     

       23
       23
       +
           tm_mon : int;

     

       24
       24
       +
           tm_year : int;

     

       25
       25
       +
           tm_wday : int;

     

       26
       26
       +
           tm_yday : int;

     

       27
       27
       +
           tm_isdst : bool

     

       28
       28
       +
         }

     

       29
       29
       +
         

     

       30
       30
       +
         let time () = 0.0

     

       31
       31
       +
         let gettimeofday () = 0.0

     

       32
       32
       +
         let mktime tm = (0.0, tm)

     

       33
       33
       +
         let gmtime _time = {

     

       34
       34
       +
           tm_sec = 0; tm_min = 0; tm_hour = 0;

     

       35
       35
       +
           tm_mday = 1; tm_mon = 0; tm_year = 120;

     

       36
       36
       +
           tm_wday = 0; tm_yday = 0; tm_isdst = false;

     

       37
       37
       +
         }

     

       38
       38
       +
         

     

       39
       39
       +
         (* JMAP connection function - would be in a real implementation *)

     

       40
       40
       +
         let connect ~host:_ ~username:_ ~password:_ ?auth_method:_ () =

     

       41
       41
       +
           failwith "Not implemented"

     

       42
       42
       +
       end

     

       43
       43
       +
       

     

       44
       44
       +
       (* Dummy ISO8601 module *)

     

       45
       45
       +
       module ISO8601 = struct

     

       46
       46
       +
         let string_of_datetime _tm = "2023-01-01T00:00:00Z"

     

       47
       47
       +
       end

     

       48
       48
       +
       

     

       49
       49
       +
       (** Flag manager args type *)

     

       50
       50
       +
       type flag_manager_args = {

     

       51
       51
       +
         list : bool;

     

       52
       52
       +
         add_flag : string option;

     

       53
       53
       +
         remove_flag : string option;

     

       54
       54
       +
         query : string;

     

       55
       55
       +
         from : string option;

     

       56
       56
       +
         days : int;

     

       57
       57
       +
         mailbox : string option;

     

       58
       58
       +
         ids : string list;

     

       59
       59
       +
         has_flag : string option;

     

       60
       60
       +
         missing_flag : string option;

     

       61
       61
       +
         limit : int;

     

       62
       62
       +
         dry_run : bool;

     

       63
       63
       +
         color : [`Red | `Orange | `Yellow | `Green | `Blue | `Purple | `Gray | `None] option;

     

       64
       64
       +
         verbose : bool;

     

       65
       65
       +
       }

     

       66
       66
       +
       

     

       67
       67
       +
       (* Helper function for converting keywords to string *)

     

       68
       68
       +
       let string_of_keyword = function

     

       69
       69
       +
         | Types.Keywords.Draft -> "$draft"

     

       70
       70
       +
         | Types.Keywords.Seen -> "$seen"

     

       71
       71
       +
         | Types.Keywords.Flagged -> "$flagged"

     

       72
       72
       +
         | Types.Keywords.Answered -> "$answered"

     

       73
       73
       +
         | Types.Keywords.Forwarded -> "$forwarded"

     

       74
       74
       +
         | Types.Keywords.Phishing -> "$phishing"

     

       75
       75
       +
         | Types.Keywords.Junk -> "$junk"

     

       76
       76
       +
         | Types.Keywords.NotJunk -> "$notjunk"

     

       77
       77
       +
         | Types.Keywords.Custom c -> c

     

       78
       78
       +
         | Types.Keywords.Notify -> "$notify"

     

       79
       79
       +
         | Types.Keywords.Muted -> "$muted"

     

       80
       80
       +
         | Types.Keywords.Followed -> "$followed"

     

       81
       81
       +
         | Types.Keywords.Memo -> "$memo" 

     

       82
       82
       +
         | Types.Keywords.HasMemo -> "$hasmemo"

     

       83
       83
       +
         | Types.Keywords.Autosent -> "$autosent"

     

       84
       84
       +
         | Types.Keywords.Unsubscribed -> "$unsubscribed"

     

       85
       85
       +
         | Types.Keywords.CanUnsubscribe -> "$canunsubscribe"

     

       86
       86
       +
         | Types.Keywords.Imported -> "$imported"

     

       87
       87
       +
         | Types.Keywords.IsTrusted -> "$istrusted"

     

       88
       88
       +
         | Types.Keywords.MaskedEmail -> "$maskedemail"

     

       89
       89
       +
         | Types.Keywords.New -> "$new"

     

       90
       90
       +
         | Types.Keywords.MailFlagBit0 -> "$MailFlagBit0"

     

       91
       91
       +
         | Types.Keywords.MailFlagBit1 -> "$MailFlagBit1" 

     

       92
       92
       +
         | Types.Keywords.MailFlagBit2 -> "$MailFlagBit2"

     

       93
       93
       +
       

     

       94
       94
       +
       (* Email filter helpers - stub implementations for type checking *)

     

       95
       95
       +
       module Email_filter = struct

     

       96
       96
       +
         let create_fulltext_filter text = Filter.condition (`Assoc [("text", `String text)])

     

       97
       97
       +
         let subject subject = Filter.condition (`Assoc [("subject", `String subject)])

     

       98
       98
       +
         let from email = Filter.condition (`Assoc [("from", `String email)])

     

       99
       99
       +
         let after date = Filter.condition (`Assoc [("receivedAt", `Assoc [("after", `Float date)])])

     

       100
       100
       +
         let before date = Filter.condition (`Assoc [("receivedAt", `Assoc [("before", `Float date)])])

     

       101
       101
       +
         let has_attachment () = Filter.condition (`Assoc [("hasAttachment", `Bool true)])

     

       102
       102
       +
         let unread () = Filter.condition (`Assoc [("isUnread", `Bool true)])

     

       103
       103
       +
         let in_mailbox id = Filter.condition (`Assoc [("inMailbox", `String id)])

     

       104
       104
       +
         let to_ email = Filter.condition (`Assoc [("to", `String email)])

     

       105
       105
       +
         let has_keyword kw = Filter.condition (`Assoc [("hasKeyword", `String (string_of_keyword kw))])

     

       106
       106
       +
         let not_has_keyword kw = Filter.condition (`Assoc [("notHasKeyword", `String (string_of_keyword kw))])

     

       107
       107
       +
       end

     

       108
       108
       +
       

     

       109
       109
       +
       (** Command-line arguments **)

     

       110
       110
       +
       

     

       111
       111
       +
       let host_arg =

     

       112
       112
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       113
       113
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       114
       114
       +
       

     

       115
       115
       +
       let user_arg =

     

       116
       116
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       117
       117
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       118
       118
       +
       

     

       119
       119
       +
       let password_arg =

     

       120
       120
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       121
       121
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       122
       122
       +
       

     

       123
       123
       +
       let list_arg =

     

       124
       124
       +
         Arg.(value & flag & info ["l"; "list"] ~doc:"List emails with their flags")

     

       125
       125
       +
       

     

       126
       126
       +
       let add_flag_arg =

     

       127
       127
       +
         Arg.(value & opt (some string) None & info ["add"] 

     

       128
       128
       +
              ~docv:"FLAG" ~doc:"Add flag to selected emails")

     

       129
       129
       +
       

     

       130
       130
       +
       let remove_flag_arg =

     

       131
       131
       +
         Arg.(value & opt (some string) None & info ["remove"] 

     

       132
       132
       +
              ~docv:"FLAG" ~doc:"Remove flag from selected emails")

     

       133
       133
       +
       

     

       134
       134
       +
       let query_arg =

     

       135
       135
       +
         Arg.(value & opt string "" & info ["q"; "query"] 

     

       136
       136
       +
              ~docv:"QUERY" ~doc:"Filter emails by search query")

     

       137
       137
       +
       

     

       138
       138
       +
       let from_arg =

     

       139
       139
       +
         Arg.(value & opt (some string) None & info ["from"] 

     

       140
       140
       +
              ~docv:"EMAIL" ~doc:"Filter by sender")

     

       141
       141
       +
       

     

       142
       142
       +
       let days_arg =

     

       143
       143
       +
         Arg.(value & opt int 30 & info ["days"] 

     

       144
       144
       +
              ~docv:"DAYS" ~doc:"Filter to emails from past N days")

     

       145
       145
       +
       

     

       146
       146
       +
       let mailbox_arg =

     

       147
       147
       +
         Arg.(value & opt (some string) None & info ["mailbox"] 

     

       148
       148
       +
              ~docv:"MAILBOX" ~doc:"Filter by mailbox")

     

       149
       149
       +
       

     

       150
       150
       +
       let ids_arg =

     

       151
       151
       +
         Arg.(value & opt_all string [] & info ["id"] 

     

       152
       152
       +
              ~docv:"ID" ~doc:"Email IDs to operate on")

     

       153
       153
       +
       

     

       154
       154
       +
       let has_flag_arg =

     

       155
       155
       +
         Arg.(value & opt (some string) None & info ["has-flag"] 

     

       156
       156
       +
              ~docv:"FLAG" ~doc:"Filter to emails with specified flag")

     

       157
       157
       +
       

     

       158
       158
       +
       let missing_flag_arg =

     

       159
       159
       +
         Arg.(value & opt (some string) None & info ["missing-flag"] 

     

       160
       160
       +
              ~docv:"FLAG" ~doc:"Filter to emails without specified flag")

     

       161
       161
       +
       

     

       162
       162
       +
       let limit_arg =

     

       163
       163
       +
         Arg.(value & opt int 50 & info ["limit"] 

     

       164
       164
       +
              ~docv:"N" ~doc:"Maximum number of emails to process")

     

       165
       165
       +
       

     

       166
       166
       +
       let dry_run_arg =

     

       167
       167
       +
         Arg.(value & flag & info ["dry-run"] ~doc:"Show what would be done without making changes")

     

       168
       168
       +
       

     

       169
       169
       +
       let color_arg =

     

       170
       170
       +
         Arg.(value & opt (some (enum [

     

       171
       171
       +
           "red", `Red;

     

       172
       172
       +
           "orange", `Orange;

     

       173
       173
       +
           "yellow", `Yellow;

     

       174
       174
       +
           "green", `Green;

     

       175
       175
       +
           "blue", `Blue;

     

       176
       176
       +
           "purple", `Purple;

     

       177
       177
       +
           "gray", `Gray;

     

       178
       178
       +
           "none", `None

     

       179
       179
       +
         ])) None & info ["color"] ~docv:"COLOR" 

     

       180
       180
       +
              ~doc:"Set color flag (red, orange, yellow, green, blue, purple, gray, or none)")

     

       181
       181
       +
       

     

       182
       182
       +
       let verbose_arg =

     

       183
       183
       +
         Arg.(value & flag & info ["v"; "verbose"] ~doc:"Show detailed operation information")

     

       184
       184
       +
       

     

       185
       185
       +
       (** Flag Manager Functionality **)

     

       186
       186
       +
       

     

       187
       187
       +
       (* Parse date for filtering *)

     

       188
       188
       +
       let days_ago_date days =

     

       189
       189
       +
         let now = Unix.time () in

     

       190
       190
       +
         now -. (float_of_int days *. 86400.0)

     

       191
       191
       +
       

     

       192
       192
       +
       (* Validate flag name *)

     

       193
       193
       +
       let validate_flag_name flag =

     

       194
       194
       +
         let is_valid = String.length flag > 0 && (

     

       195
       195
       +
           (* System flags start with $ *)

     

       196
       196
       +
           (String.get flag 0 = '$') ||

     

       197
       197
       +
           

     

       198
       198
       +
           (* Custom flags must be alphanumeric plus some characters *)

     

       199
       199
       +
           (String.for_all (function 

     

       200
       200
       +
             | 'a'..'z' | 'A'..'Z' | '0'..'9' | '-' | '_' -> true 

     

       201
       201
       +
             | _ -> false) flag)

     

       202
       202
       +
         ) in

     

       203
       203
       +
         

     

       204
       204
       +
         if not is_valid then

     

       205
       205
       +
           Printf.eprintf "Warning: Flag name '%s' may not be valid according to JMAP spec\n" flag;

     

       206
       206
       +
         

     

       207
       207
       +
         is_valid

     

       208
       208
       +
       

     

       209
       209
       +
       (* Convert flag name to keyword *)

     

       210
       210
       +
       let flag_to_keyword flag =

     

       211
       211
       +
         match flag with

     

       212
       212
       +
         | "seen" -> Types.Keywords.Seen

     

       213
       213
       +
         | "draft" -> Types.Keywords.Draft

     

       214
       214
       +
         | "flagged" -> Types.Keywords.Flagged

     

       215
       215
       +
         | "answered" -> Types.Keywords.Answered

     

       216
       216
       +
         | "forwarded" -> Types.Keywords.Forwarded

     

       217
       217
       +
         | "junk" -> Types.Keywords.Junk

     

       218
       218
       +
         | "notjunk" -> Types.Keywords.NotJunk

     

       219
       219
       +
         | "phishing" -> Types.Keywords.Phishing

     

       220
       220
       +
         | "important" -> Types.Keywords.Flagged  (* Treat important same as flagged *)

     

       221
       221
       +
         | _ -> 

     

       222
       222
       +
             (* Handle $ prefix for system keywords *)

     

       223
       223
       +
             if String.get flag 0 = '$' then

     

       224
       224
       +
               match flag with

     

       225
       225
       +
               | "$seen" -> Types.Keywords.Seen

     

       226
       226
       +
               | "$draft" -> Types.Keywords.Draft

     

       227
       227
       +
               | "$flagged" -> Types.Keywords.Flagged

     

       228
       228
       +
               | "$answered" -> Types.Keywords.Answered

     

       229
       229
       +
               | "$forwarded" -> Types.Keywords.Forwarded

     

       230
       230
       +
               | "$junk" -> Types.Keywords.Junk

     

       231
       231
       +
               | "$notjunk" -> Types.Keywords.NotJunk

     

       232
       232
       +
               | "$phishing" -> Types.Keywords.Phishing

     

       233
       233
       +
               | "$notify" -> Types.Keywords.Notify

     

       234
       234
       +
               | "$muted" -> Types.Keywords.Muted

     

       235
       235
       +
               | "$followed" -> Types.Keywords.Followed

     

       236
       236
       +
               | "$memo" -> Types.Keywords.Memo

     

       237
       237
       +
               | "$hasmemo" -> Types.Keywords.HasMemo

     

       238
       238
       +
               | "$autosent" -> Types.Keywords.Autosent

     

       239
       239
       +
               | "$unsubscribed" -> Types.Keywords.Unsubscribed

     

       240
       240
       +
               | "$canunsubscribe" -> Types.Keywords.CanUnsubscribe

     

       241
       241
       +
               | "$imported" -> Types.Keywords.Imported

     

       242
       242
       +
               | "$istrusted" -> Types.Keywords.IsTrusted

     

       243
       243
       +
               | "$maskedemail" -> Types.Keywords.MaskedEmail

     

       244
       244
       +
               | "$new" -> Types.Keywords.New

     

       245
       245
       +
               | "$MailFlagBit0" -> Types.Keywords.MailFlagBit0

     

       246
       246
       +
               | "$MailFlagBit1" -> Types.Keywords.MailFlagBit1

     

       247
       247
       +
               | "$MailFlagBit2" -> Types.Keywords.MailFlagBit2

     

       248
       248
       +
               | _ -> Types.Keywords.Custom flag

     

       249
       249
       +
             else

     

       250
       250
       +
               (* Flag without $ prefix is treated as custom *)

     

       251
       251
       +
               Types.Keywords.Custom ("$" ^ flag)

     

       252
       252
       +
       

     

       253
       253
       +
       (* Get standard flags in user-friendly format *)

     

       254
       254
       +
       let get_standard_flags () = [

     

       255
       255
       +
         "seen", "Message has been read";

     

       256
       256
       +
         "draft", "Message is a draft";

     

       257
       257
       +
         "flagged", "Message is flagged/important";

     

       258
       258
       +
         "answered", "Message has been replied to";

     

       259
       259
       +
         "forwarded", "Message has been forwarded";

     

       260
       260
       +
         "junk", "Message is spam/junk";

     

       261
       261
       +
         "notjunk", "Message is explicitly not spam/junk";

     

       262
       262
       +
         "phishing", "Message is suspected phishing";

     

       263
       263
       +
         "notify", "Request notification when replied to";

     

       264
       264
       +
         "muted", "Notifications disabled for this message";

     

       265
       265
       +
         "followed", "Thread is followed for notifications";

     

       266
       266
       +
         "memo", "Has memo/note attached";

     

       267
       267
       +
         "new", "Recently delivered";

     

       268
       268
       +
       ]

     

       269
       269
       +
       

     

       270
       270
       +
       (* Convert color to flag bits *)

     

       271
       271
       +
       let color_to_flags color =

     

       272
       272
       +
         match color with

     

       273
       273
       +
         | `Red -> [Types.Keywords.MailFlagBit0]

     

       274
       274
       +
         | `Orange -> [Types.Keywords.MailFlagBit1]

     

       275
       275
       +
         | `Yellow -> [Types.Keywords.MailFlagBit2]

     

       276
       276
       +
         | `Green -> [Types.Keywords.MailFlagBit0; Types.Keywords.MailFlagBit1]

     

       277
       277
       +
         | `Blue -> [Types.Keywords.MailFlagBit0; Types.Keywords.MailFlagBit2]

     

       278
       278
       +
         | `Purple -> [Types.Keywords.MailFlagBit1; Types.Keywords.MailFlagBit2]

     

       279
       279
       +
         | `Gray -> [Types.Keywords.MailFlagBit0; Types.Keywords.MailFlagBit1; Types.Keywords.MailFlagBit2]

     

       280
       280
       +
         | `None -> []

     

       281
       281
       +
       

     

       282
       282
       +
       (* Convert flag bits to color *)

     

       283
       283
       +
       let flags_to_color flags =

     

       284
       284
       +
         let has_bit0 = List.exists ((=) Types.Keywords.MailFlagBit0) flags in

     

       285
       285
       +
         let has_bit1 = List.exists ((=) Types.Keywords.MailFlagBit1) flags in

     

       286
       286
       +
         let has_bit2 = List.exists ((=) Types.Keywords.MailFlagBit2) flags in

     

       287
       287
       +
         

     

       288
       288
       +
         match (has_bit0, has_bit1, has_bit2) with

     

       289
       289
       +
         | (true, false, false) -> Some `Red

     

       290
       290
       +
         | (false, true, false) -> Some `Orange

     

       291
       291
       +
         | (false, false, true) -> Some `Yellow

     

       292
       292
       +
         | (true, true, false) -> Some `Green

     

       293
       293
       +
         | (true, false, true) -> Some `Blue

     

       294
       294
       +
         | (false, true, true) -> Some `Purple

     

       295
       295
       +
         | (true, true, true) -> Some `Gray

     

       296
       296
       +
         | (false, false, false) -> None

     

       297
       297
       +
       

     

       298
       298
       +
       (* Filter builder - create JMAP filter from command line args *)

     

       299
       299
       +
       let build_filter account_id mailbox_id args =

     

       300
       300
       +
         let open Email_filter in

     

       301
       301
       +
         let filters = [] in

     

       302
       302
       +
         

     

       303
       303
       +
         (* Add filter conditions based on command-line args *)

     

       304
       304
       +
         let filters = match args.query with 

     

       305
       305
       +
           | "" -> filters 

     

       306
       306
       +
           | query -> create_fulltext_filter query :: filters 

     

       307
       307
       +
         in

     

       308
       308
       +
         

     

       309
       309
       +
         let filters = match args.from with

     

       310
       310
       +
           | None -> filters

     

       311
       311
       +
           | Some sender -> from sender :: filters

     

       312
       312
       +
         in

     

       313
       313
       +
         

     

       314
       314
       +
         let filters = 

     

       315
       315
       +
           if args.days > 0 then 

     

       316
       316
       +
             after (days_ago_date args.days) :: filters

     

       317
       317
       +
           else 

     

       318
       318
       +
             filters

     

       319
       319
       +
         in

     

       320
       320
       +
         

     

       321
       321
       +
         let filters = match mailbox_id with

     

       322
       322
       +
           | None -> filters

     

       323
       323
       +
           | Some id -> in_mailbox id :: filters

     

       324
       324
       +
         in

     

       325
       325
       +
         

     

       326
       326
       +
         let filters = match args.has_flag with

     

       327
       327
       +
           | None -> filters

     

       328
       328
       +
           | Some flag -> 

     

       329
       329
       +
               let kw = flag_to_keyword flag in

     

       330
       330
       +
               has_keyword kw :: filters

     

       331
       331
       +
         in

     

       332
       332
       +
         

     

       333
       333
       +
         let filters = match args.missing_flag with

     

       334
       334
       +
           | None -> filters

     

       335
       335
       +
           | Some flag ->

     

       336
       336
       +
               let kw = flag_to_keyword flag in

     

       337
       337
       +
               not_has_keyword kw :: filters

     

       338
       338
       +
         in

     

       339
       339
       +
         

     

       340
       340
       +
         (* Combine all filters with AND *)

     

       341
       341
       +
         match filters with

     

       342
       342
       +
         | [] -> Filter.condition (`Assoc [])  (* Empty filter *)

     

       343
       343
       +
         | [f] -> f

     

       344
       344
       +
         | filters -> Filter.and_ filters

     

       345
       345
       +
       

     

       346
       346
       +
       (* Display email flag information *)

     

       347
       347
       +
       let display_email_flags emails verbose =

     

       348
       348
       +
         Printf.printf "Emails and their flags:\n\n";

     

       349
       349
       +
         

     

       350
       350
       +
         emails |> List.iteri (fun i email ->

     

       351
       351
       +
           let id = Option.value (Types.Email.id email) ~default:"(unknown)" in

     

       352
       352
       +
           let subject = Option.value (Types.Email.subject email) ~default:"(no subject)" in

     

       353
       353
       +
           

     

       354
       354
       +
           let from_list = Option.value (Types.Email.from email) ~default:[] in

     

       355
       355
       +
           let from = match from_list with

     

       356
       356
       +
             | addr :: _ -> Types.Email_address.email addr

     

       357
       357
       +
             | [] -> "(unknown)"

     

       358
       358
       +
           in

     

       359
       359
       +
           

     

       360
       360
       +
           let date = match Types.Email.received_at email with

     

       361
       361
       +
             | Some d -> String.sub (ISO8601.string_of_datetime (Unix.gmtime d)) 0 19

     

       362
       362
       +
             | None -> "(unknown)"

     

       363
       363
       +
           in

     

       364
       364
       +
           

     

       365
       365
       +
           (* Get all keywords/flags *)

     

       366
       366
       +
           let keywords = match Types.Email.keywords email with

     

       367
       367
       +
             | Some kw -> kw

     

       368
       368
       +
             | None -> []

     

       369
       369
       +
           in

     

       370
       370
       +
           

     

       371
       371
       +
           (* Format keywords for display *)

     

       372
       372
       +
           let flag_strs = keywords |> List.map (fun kw ->

     

       373
       373
       +
             match kw with

     

       374
       374
       +
             | Types.Keywords.Draft -> "$draft"

     

       375
       375
       +
             | Types.Keywords.Seen -> "$seen"

     

       376
       376
       +
             | Types.Keywords.Flagged -> "$flagged"

     

       377
       377
       +
             | Types.Keywords.Answered -> "$answered"

     

       378
       378
       +
             | Types.Keywords.Forwarded -> "$forwarded"

     

       379
       379
       +
             | Types.Keywords.Phishing -> "$phishing"

     

       380
       380
       +
             | Types.Keywords.Junk -> "$junk"

     

       381
       381
       +
             | Types.Keywords.NotJunk -> "$notjunk"

     

       382
       382
       +
             | Types.Keywords.Custom c -> c

     

       383
       383
       +
             | Types.Keywords.Notify -> "$notify"

     

       384
       384
       +
             | Types.Keywords.Muted -> "$muted"

     

       385
       385
       +
             | Types.Keywords.Followed -> "$followed"

     

       386
       386
       +
             | Types.Keywords.Memo -> "$memo" 

     

       387
       387
       +
             | Types.Keywords.HasMemo -> "$hasmemo"

     

       388
       388
       +
             | Types.Keywords.Autosent -> "$autosent"

     

       389
       389
       +
             | Types.Keywords.Unsubscribed -> "$unsubscribed"

     

       390
       390
       +
             | Types.Keywords.CanUnsubscribe -> "$canunsubscribe"

     

       391
       391
       +
             | Types.Keywords.Imported -> "$imported"

     

       392
       392
       +
             | Types.Keywords.IsTrusted -> "$istrusted"

     

       393
       393
       +
             | Types.Keywords.MaskedEmail -> "$maskedemail"

     

       394
       394
       +
             | Types.Keywords.New -> "$new"

     

       395
       395
       +
             | Types.Keywords.MailFlagBit0 -> "$MailFlagBit0"

     

       396
       396
       +
             | Types.Keywords.MailFlagBit1 -> "$MailFlagBit1" 

     

       397
       397
       +
             | Types.Keywords.MailFlagBit2 -> "$MailFlagBit2"

     

       398
       398
       +
           ) in

     

       399
       399
       +
           

     

       400
       400
       +
           Printf.printf "Email %d: %s\n" (i + 1) subject;

     

       401
       401
       +
           Printf.printf "  ID:    %s\n" id;

     

       402
       402
       +
           

     

       403
       403
       +
           if verbose then begin

     

       404
       404
       +
             Printf.printf "  From:  %s\n" from;

     

       405
       405
       +
             Printf.printf "  Date:  %s\n" date;

     

       406
       406
       +
           end;

     

       407
       407
       +
           

     

       408
       408
       +
           (* Show color if applicable *)

     

       409
       409
       +
           begin match flags_to_color keywords with

     

       410
       410
       +
           | Some color ->

     

       411
       411
       +
               let color_name = match color with

     

       412
       412
       +
                 | `Red -> "Red"

     

       413
       413
       +
                 | `Orange -> "Orange"

     

       414
       414
       +
                 | `Yellow -> "Yellow" 

     

       415
       415
       +
                 | `Green -> "Green"

     

       416
       416
       +
                 | `Blue -> "Blue"

     

       417
       417
       +
                 | `Purple -> "Purple"

     

       418
       418
       +
                 | `Gray -> "Gray"

     

       419
       419
       +
               in

     

       420
       420
       +
               Printf.printf "  Color: %s\n" color_name

     

       421
       421
       +
           | None -> ()

     

       422
       422
       +
           end;

     

       423
       423
       +
           

     

       424
       424
       +
           Printf.printf "  Flags: %s\n\n" 

     

       425
       425
       +
             (if flag_strs = [] then "(none)" else String.concat ", " flag_strs)

     

       426
       426
       +
         );

     

       427
       427
       +
         

     

       428
       428
       +
         if List.length emails = 0 then

     

       429
       429
       +
           Printf.printf "No emails found matching criteria.\n"

     

       430
       430
       +
       

     

       431
       431
       +
       (* Command implementation *)

     

       432
       432
       +
       let flag_command host user _password list add_flag remove_flag query from days 

     

       433
       433
       +
                         mailbox ids has_flag missing_flag limit dry_run color verbose : int =

     

       434
       434
       +
         (* Pack arguments into a record for easier passing *)

     

       435
       435
       +
         let _args : flag_manager_args = {

     

       436
       436
       +
           list; add_flag; remove_flag; query; from; days; mailbox; 

     

       437
       437
       +
           ids; has_flag; missing_flag; limit; dry_run; color; verbose

     

       438
       438
       +
         } in

     

       439
       439
       +
         

     

       440
       440
       +
         (* Main workflow would be implemented here using the JMAP library *)

     

       441
       441
       +
         Printf.printf "JMAP Flag Manager\n";

     

       442
       442
       +
         Printf.printf "Server: %s\n" host;

     

       443
       443
       +
         Printf.printf "User: %s\n\n" user;

     

       444
       444
       +
         

     

       445
       445
       +
         if list then

     

       446
       446
       +
           Printf.printf "Listing emails with their flags...\n\n"

     

       447
       447
       +
         else begin

     

       448
       448
       +
           if add_flag <> None then

     

       449
       449
       +
             Printf.printf "Adding flag: %s\n" (Option.get add_flag);

     

       450
       450
       +
           

     

       451
       451
       +
           if remove_flag <> None then

     

       452
       452
       +
             Printf.printf "Removing flag: %s\n" (Option.get remove_flag);

     

       453
       453
       +
           

     

       454
       454
       +
           if color <> None then

     

       455
       455
       +
             let color_name = match Option.get color with

     

       456
       456
       +
               | `Red -> "Red"

     

       457
       457
       +
               | `Orange -> "Orange"

     

       458
       458
       +
               | `Yellow -> "Yellow" 

     

       459
       459
       +
               | `Green -> "Green"

     

       460
       460
       +
               | `Blue -> "Blue"

     

       461
       461
       +
               | `Purple -> "Purple"

     

       462
       462
       +
               | `Gray -> "Gray"

     

       463
       463
       +
               | `None -> "None"

     

       464
       464
       +
             in

     

       465
       465
       +
             Printf.printf "Setting color: %s\n" color_name;

     

       466
       466
       +
         end;

     

       467
       467
       +
         

     

       468
       468
       +
         if query <> "" then

     

       469
       469
       +
           Printf.printf "Filtering by query: %s\n" query;

     

       470
       470
       +
         

     

       471
       471
       +
         if from <> None then

     

       472
       472
       +
           Printf.printf "Filtering by sender: %s\n" (Option.get from);

     

       473
       473
       +
         

     

       474
       474
       +
         if mailbox <> None then

     

       475
       475
       +
           Printf.printf "Filtering by mailbox: %s\n" (Option.get mailbox);

     

       476
       476
       +
         

     

       477
       477
       +
         if ids <> [] then

     

       478
       478
       +
           Printf.printf "Operating on specific email IDs: %s\n" 

     

       479
       479
       +
             (String.concat ", " ids);

     

       480
       480
       +
         

     

       481
       481
       +
         if has_flag <> None then

     

       482
       482
       +
           Printf.printf "Filtering to emails with flag: %s\n" (Option.get has_flag);

     

       483
       483
       +
         

     

       484
       484
       +
         if missing_flag <> None then

     

       485
       485
       +
           Printf.printf "Filtering to emails without flag: %s\n" (Option.get missing_flag);

     

       486
       486
       +
         

     

       487
       487
       +
         Printf.printf "Limiting to %d emails\n" limit;

     

       488
       488
       +
         

     

       489
       489
       +
         if dry_run then

     

       490
       490
       +
           Printf.printf "DRY RUN MODE - No changes will be made\n";

     

       491
       491
       +
         

     

       492
       492
       +
         Printf.printf "\n";

     

       493
       493
       +
         

     

       494
       494
       +
         (* This is where the actual JMAP calls would happen, like:

     

       495
       495
       +
         

     

       496
       496
       +
         let manage_flags () =

     

       497
       497
       +
           let* (ctx, session) = Jmap.Unix.connect 

     

       498
       498
       +
             ~host ~username:user ~password 

     

       499
       499
       +
             ~auth_method:(Jmap.Unix.Basic(user, password)) () in

     

       500
       500
       +
           

     

       501
       501
       +
           (* Get primary account ID *)

     

       502
       502
       +
           let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       503
       503
       +
             | Ok id -> id

     

       504
       504
       +
             | Error _ -> failwith "No mail account found"

     

       505
       505
       +
           in

     

       506
       506
       +
           

     

       507
       507
       +
           (* Resolve mailbox name to ID if specified *)

     

       508
       508
       +
           let* mailbox_id_opt = match args.mailbox with

     

       509
       509
       +
             | None -> Lwt.return None

     

       510
       510
       +
             | Some name ->

     

       511
       511
       +
                 (* This would use Mailbox/query and Mailbox/get to resolve the name *)

     

       512
       512
       +
                 ...

     

       513
       513
       +
           in

     

       514
       514
       +
           

     

       515
       515
       +
           (* Find emails to operate on *)

     

       516
       516
       +
           let* emails = 

     

       517
       517
       +
             if args.ids <> [] then

     

       518
       518
       +
               (* Get emails by ID *)

     

       519
       519
       +
               let* result = Email.get ctx

     

       520
       520
       +
                 ~account_id

     

       521
       521
       +
                 ~ids:args.ids

     

       522
       522
       +
                 ~properties:["id"; "subject"; "from"; "receivedAt"; "keywords"] in

     

       523
       523
       +
               

     

       524
       524
       +
               match result with

     

       525
       525
       +
               | Error err ->

     

       526
       526
       +
                   Printf.eprintf "Error: %s\n" (Jmap.Error.error_to_string err);

     

       527
       527
       +
                   Lwt.return []

     

       528
       528
       +
               | Ok (_, emails) -> Lwt.return emails

     

       529
       529
       +
             else

     

       530
       530
       +
               (* Find emails by query *)

     

       531
       531
       +
               let filter = build_filter account_id mailbox_id_opt args in

     

       532
       532
       +
               

     

       533
       533
       +
               let* result = Email.query ctx

     

       534
       534
       +
                 ~account_id

     

       535
       535
       +
                 ~filter

     

       536
       536
       +
                 ~sort:[Email_sort.received_newest_first ()]

     

       537
       537
       +
                 ~limit:args.limit

     

       538
       538
       +
                 ~properties:["id"] in

     

       539
       539
       +
               

     

       540
       540
       +
               match result with

     

       541
       541
       +
               | Error err ->

     

       542
       542
       +
                   Printf.eprintf "Error: %s\n" (Jmap.Error.error_to_string err);

     

       543
       543
       +
                   Lwt.return []

     

       544
       544
       +
               | Ok (ids, _) ->

     

       545
       545
       +
                   (* Get full email objects for the matching IDs *)

     

       546
       546
       +
                   let* result = Email.get ctx

     

       547
       547
       +
                     ~account_id

     

       548
       548
       +
                     ~ids

     

       549
       549
       +
                     ~properties:["id"; "subject"; "from"; "receivedAt"; "keywords"] in

     

       550
       550
       +
                   

     

       551
       551
       +
                   match result with

     

       552
       552
       +
                   | Error err ->

     

       553
       553
       +
                       Printf.eprintf "Error: %s\n" (Jmap.Error.error_to_string err);

     

       554
       554
       +
                       Lwt.return []

     

       555
       555
       +
                   | Ok (_, emails) -> Lwt.return emails

     

       556
       556
       +
           in

     

       557
       557
       +
           

     

       558
       558
       +
           (* Just list the emails with their flags *)

     

       559
       559
       +
           if args.list then

     

       560
       560
       +
             display_email_flags emails args.verbose;

     

       561
       561
       +
             Lwt.return_unit

     

       562
       562
       +
           else if List.length emails = 0 then

     

       563
       563
       +
             Printf.printf "No emails found matching criteria.\n";

     

       564
       564
       +
             Lwt.return_unit

     

       565
       565
       +
           else

     

       566
       566
       +
             (* Perform flag operations *)

     

       567
       567
       +
             let ids = emails |> List.filter_map Types.Email.id in

     

       568
       568
       +
             

     

       569
       569
       +
             if args.dry_run then

     

       570
       570
       +
               display_email_flags emails args.verbose;

     

       571
       571
       +
               Lwt.return_unit

     

       572
       572
       +
             else

     

       573
       573
       +
               (* Create patch object *)

     

       574
       574
       +
               let make_patch () =

     

       575
       575
       +
                 let add_keywords = ref [] in

     

       576
       576
       +
                 let remove_keywords = ref [] in

     

       577
       577
       +
                 

     

       578
       578
       +
                 (* Handle add flag *)

     

       579
       579
       +
                 Option.iter (fun flag ->

     

       580
       580
       +
                   let keyword = flag_to_keyword flag in

     

       581
       581
       +
                   add_keywords := keyword :: !add_keywords

     

       582
       582
       +
                 ) args.add_flag;

     

       583
       583
       +
                 

     

       584
       584
       +
                 (* Handle remove flag *)

     

       585
       585
       +
                 Option.iter (fun flag ->

     

       586
       586
       +
                   let keyword = flag_to_keyword flag in

     

       587
       587
       +
                   remove_keywords := keyword :: !remove_keywords

     

       588
       588
       +
                 ) args.remove_flag;

     

       589
       589
       +
                 

     

       590
       590
       +
                 (* Handle color *)

     

       591
       591
       +
                 Option.iter (fun color ->

     

       592
       592
       +
                   (* First remove all color bits *)

     

       593
       593
       +
                   remove_keywords := Types.Keywords.MailFlagBit0 :: !remove_keywords;

     

       594
       594
       +
                   remove_keywords := Types.Keywords.MailFlagBit1 :: !remove_keywords;

     

       595
       595
       +
                   remove_keywords := Types.Keywords.MailFlagBit2 :: !remove_keywords;

     

       596
       596
       +
                   

     

       597
       597
       +
                   (* Then add the right combination for the requested color *)

     

       598
       598
       +
                   if color <> `None then begin

     

       599
       599
       +
                     let color_flags = color_to_flags color in

     

       600
       600
       +
                     add_keywords := color_flags @ !add_keywords

     

       601
       601
       +
                   end

     

       602
       602
       +
                 ) args.color;

     

       603
       603
       +
                 

     

       604
       604
       +
                 Email.make_patch

     

       605
       605
       +
                   ~add_keywords:!add_keywords

     

       606
       606
       +
                   ~remove_keywords:!remove_keywords

     

       607
       607
       +
                   ()

     

       608
       608
       +
               in

     

       609
       609
       +
               

     

       610
       610
       +
               let patch = make_patch () in

     

       611
       611
       +
               

     

       612
       612
       +
               let* result = Email.update ctx

     

       613
       613
       +
                 ~account_id

     

       614
       614
       +
                 ~ids

     

       615
       615
       +
                 ~update_each:(fun _ -> patch) in

     

       616
       616
       +
               

     

       617
       617
       +
               match result with

     

       618
       618
       +
               | Error err ->

     

       619
       619
       +
                   Printf.eprintf "Error: %s\n" (Jmap.Error.error_to_string err);

     

       620
       620
       +
                   Lwt.return_unit

     

       621
       621
       +
               | Ok updated ->

     

       622
       622
       +
                   Printf.printf "Successfully updated %d emails.\n" (List.length updated);

     

       623
       623
       +
                   Lwt.return_unit

     

       624
       624
       +
         *)

     

       625
       625
       +
         

     

       626
       626
       +
         if list then begin

     

       627
       627
       +
           (* Simulate having found a few emails *)

     

       628
       628
       +
           let count = 3 in

     

       629
       629
       +
           Printf.printf "Found %d matching emails:\n\n" count;

     

       630
       630
       +
           Printf.printf "Email 1: Meeting Agenda\n";

     

       631
       631
       +
           Printf.printf "  ID:    email123\n";

     

       632
       632
       +
           if verbose then begin

     

       633
       633
       +
             Printf.printf "  From:  alice@example.com\n";

     

       634
       634
       +
             Printf.printf "  Date:  2023-04-15 09:30:00\n";

     

       635
       635
       +
           end;

     

       636
       636
       +
           Printf.printf "  Flags: $seen, $flagged, $answered\n\n";

     

       637
       637
       +
           

     

       638
       638
       +
           Printf.printf "Email 2: Project Update\n";

     

       639
       639
       +
           Printf.printf "  ID:    email124\n";

     

       640
       640
       +
           if verbose then begin

     

       641
       641
       +
             Printf.printf "  From:  bob@example.com\n";

     

       642
       642
       +
             Printf.printf "  Date:  2023-04-16 14:45:00\n";

     

       643
       643
       +
           end;

     

       644
       644
       +
           Printf.printf "  Color: Red\n";

     

       645
       645
       +
           Printf.printf "  Flags: $seen, $MailFlagBit0\n\n";

     

       646
       646
       +
           

     

       647
       647
       +
           Printf.printf "Email 3: Weekly Newsletter\n";

     

       648
       648
       +
           Printf.printf "  ID:    email125\n";

     

       649
       649
       +
           if verbose then begin

     

       650
       650
       +
             Printf.printf "  From:  newsletter@example.com\n";

     

       651
       651
       +
             Printf.printf "  Date:  2023-04-17 08:15:00\n";

     

       652
       652
       +
           end;

     

       653
       653
       +
           Printf.printf "  Flags: $seen, $notjunk\n\n";

     

       654
       654
       +
         end else if add_flag <> None || remove_flag <> None || color <> None then begin

     

       655
       655
       +
           Printf.printf "Would modify %d emails:\n" 2;

     

       656
       656
       +
           if dry_run then

     

       657
       657
       +
             Printf.printf "(Dry run mode - no changes made)\n\n"

     

       658
       658
       +
           else

     

       659
       659
       +
             Printf.printf "Changes applied successfully\n\n";

     

       660
       660
       +
         end;

     

       661
       661
       +
         

     

       662
       662
       +
         (* List standard flags if no other actions specified *)

     

       663
       663
       +
         if not list && add_flag = None && remove_flag = None && color = None then begin

     

       664
       664
       +
           Printf.printf "Standard flags:\n";

     

       665
       665
       +
           get_standard_flags() |> List.iter (fun (flag, desc) ->

     

       666
       666
       +
             Printf.printf "  $%-12s %s\n" flag desc

     

       667
       667
       +
           );

     

       668
       668
       +
           

     

       669
       669
       +
           Printf.printf "\nColor flags:\n";

     

       670
       670
       +
           Printf.printf "  $MailFlagBit0    Red\n";

     

       671
       671
       +
           Printf.printf "  $MailFlagBit1    Orange\n";

     

       672
       672
       +
           Printf.printf "  $MailFlagBit2    Yellow\n";

     

       673
       673
       +
           Printf.printf "  $MailFlagBit0+1  Green\n";

     

       674
       674
       +
           Printf.printf "  $MailFlagBit0+2  Blue\n";

     

       675
       675
       +
           Printf.printf "  $MailFlagBit1+2  Purple\n";

     

       676
       676
       +
           Printf.printf "  $MailFlagBit0+1+2 Gray\n";

     

       677
       677
       +
         end;

     

       678
       678
       +
         

     

       679
       679
       +
         (* Since we're only type checking, we'll exit with success *)

     

       680
       680
       +
         0

     

       681
       681
       +
       

     

       682
       682
       +
       (* Command definition *)

     

       683
       683
       +
       let flag_cmd =

     

       684
       684
       +
         let doc = "manage email flags using JMAP" in

     

       685
       685
       +
         let man = [

     

       686
       686
       +
           `S Manpage.s_description;

     

       687
       687
       +
           `P "Lists, adds, and removes flags (keywords) from emails using JMAP.";

     

       688
       688
       +
           `P "Demonstrates JMAP's flag/keyword management capabilities.";

     

       689
       689
       +
           `S Manpage.s_examples;

     

       690
       690
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --list";

     

       691
       691
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --add flagged --from boss@example.com";

     

       692
       692
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --color red --mailbox Inbox --has-flag seen --missing-flag flagged";

     

       693
       693
       +
         ] in

     

       694
       694
       +
         

     

       695
       695
       +
         let cmd =

     

       696
       696
       +
           Cmd.v

     

       697
       697
       +
             (Cmd.info "jmap-flag-manager" ~version:"1.0" ~doc ~man)

     

       698
       698
       +
             Term.(const flag_command $ host_arg $ user_arg $ password_arg $ 

     

       699
       699
       +
                   list_arg $ add_flag_arg $ remove_flag_arg $ query_arg $ 

     

       700
       700
       +
                   from_arg $ days_arg $ mailbox_arg $ ids_arg $ has_flag_arg $ 

     

       701
       701
       +
                   missing_flag_arg $ limit_arg $ dry_run_arg $ color_arg $ verbose_arg)

     

       702
       702
       +
         in

     

       703
       703
       +
         cmd

     

       704
       704
       +
       

     

       705
       705
       +
       (* Main entry point *)

     

       706
       706
       +
       let () = exit (Cmd.eval' flag_cmd)

+620

bin/jmap_identity_monitor.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_identity_monitor.ml - A tool for monitoring email delivery status

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates JMAP's identity and submission tracking capabilities,

     

       5
       5
       +
        * allowing users to monitor email delivery status and manage email identities.

     

       6
       6
       +
        *)

     

       7
       7
       +
       

     

       8
       8
       +
       open Cmdliner

     

       9
       9
       +
       (* Using standard OCaml, no Lwt *)

     

       10
       10
       +
       

     

       11
       11
       +
       (* JMAP imports *)

     

       12
       12
       +
       open Jmap

     

       13
       13
       +
       open Jmap.Types

     

       14
       14
       +
       open Jmap.Wire

     

       15
       15
       +
       open Jmap.Methods

     

       16
       16
       +
       open Jmap_email

     

       17
       17
       +
       (* For step 2, we're only testing type checking. No implementations required. *)

     

       18
       18
       +
       

     

       19
       19
       +
       (* Dummy Unix module for type checking *)

     

       20
       20
       +
       module Unix = struct

     

       21
       21
       +
         type tm = {

     

       22
       22
       +
           tm_sec : int;

     

       23
       23
       +
           tm_min : int;

     

       24
       24
       +
           tm_hour : int;

     

       25
       25
       +
           tm_mday : int;

     

       26
       26
       +
           tm_mon : int;

     

       27
       27
       +
           tm_year : int;

     

       28
       28
       +
           tm_wday : int;

     

       29
       29
       +
           tm_yday : int;

     

       30
       30
       +
           tm_isdst : bool

     

       31
       31
       +
         }

     

       32
       32
       +
         

     

       33
       33
       +
         let time () = 0.0

     

       34
       34
       +
         let gettimeofday () = 0.0

     

       35
       35
       +
         let mktime tm = (0.0, tm)

     

       36
       36
       +
         let gmtime _time = {

     

       37
       37
       +
           tm_sec = 0; tm_min = 0; tm_hour = 0;

     

       38
       38
       +
           tm_mday = 1; tm_mon = 0; tm_year = 120;

     

       39
       39
       +
           tm_wday = 0; tm_yday = 0; tm_isdst = false;

     

       40
       40
       +
         }

     

       41
       41
       +
         

     

       42
       42
       +
         (* JMAP connection function - would be in a real implementation *)

     

       43
       43
       +
         let connect ~host ~username ~password ?auth_method () =

     

       44
       44
       +
           failwith "Not implemented"

     

       45
       45
       +
       end

     

       46
       46
       +
       

     

       47
       47
       +
       (* Dummy ISO8601 module *)

     

       48
       48
       +
       module ISO8601 = struct

     

       49
       49
       +
         let string_of_datetime _tm = "2023-01-01T00:00:00Z"

     

       50
       50
       +
       end

     

       51
       51
       +
       

     

       52
       52
       +
       (** Email submission and delivery status types *)

     

       53
       53
       +
       type email_envelope_address = {

     

       54
       54
       +
         env_addr_email : string;

     

       55
       55
       +
         env_addr_parameters : (string * string) list;

     

       56
       56
       +
       }

     

       57
       57
       +
       

     

       58
       58
       +
       type email_envelope = {

     

       59
       59
       +
         env_mail_from : email_envelope_address;

     

       60
       60
       +
         env_rcpt_to : email_envelope_address list;

     

       61
       61
       +
       }

     

       62
       62
       +
       

     

       63
       63
       +
       type email_delivery_status = {

     

       64
       64
       +
         delivery_smtp_reply : string;

     

       65
       65
       +
         delivery_delivered : [`Queued | `Yes | `No | `Unknown];

     

       66
       66
       +
         delivery_displayed : [`Yes | `Unknown];

     

       67
       67
       +
       }

     

       68
       68
       +
       

     

       69
       69
       +
       type email_submission = {

     

       70
       70
       +
         email_sub_id : string;

     

       71
       71
       +
         email_id : string;

     

       72
       72
       +
         thread_id : string;

     

       73
       73
       +
         identity_id : string;

     

       74
       74
       +
         send_at : float;

     

       75
       75
       +
         undo_status : [`Pending | `Final | `Canceled];

     

       76
       76
       +
         envelope : email_envelope option;

     

       77
       77
       +
         delivery_status : (string, email_delivery_status) Hashtbl.t option;

     

       78
       78
       +
         dsn_blob_ids : string list;

     

       79
       79
       +
         mdn_blob_ids : string list;

     

       80
       80
       +
       }

     

       81
       81
       +
       

     

       82
       82
       +
       (** Dummy Email_address module to replace Jmap_email_types.Email_address *)

     

       83
       83
       +
       module Email_address = struct

     

       84
       84
       +
         type t = string

     

       85
       85
       +
         let email addr = "user@example.com"

     

       86
       86
       +
       end

     

       87
       87
       +
       

     

       88
       88
       +
       (** Dummy Identity module *)

     

       89
       89
       +
       module Identity = struct

     

       90
       90
       +
         type t = {

     

       91
       91
       +
           id : string;

     

       92
       92
       +
           name : string;

     

       93
       93
       +
           email : string;

     

       94
       94
       +
           reply_to : Email_address.t list option;

     

       95
       95
       +
           bcc : Email_address.t list option;

     

       96
       96
       +
           text_signature : string;

     

       97
       97
       +
           html_signature : string;

     

       98
       98
       +
           may_delete : bool;

     

       99
       99
       +
         }

     

       100
       100
       +
         

     

       101
       101
       +
         let id identity = identity.id

     

       102
       102
       +
         let name identity = identity.name

     

       103
       103
       +
         let email identity = identity.email

     

       104
       104
       +
         let reply_to identity = identity.reply_to

     

       105
       105
       +
         let bcc identity = identity.bcc

     

       106
       106
       +
         let text_signature identity = identity.text_signature

     

       107
       107
       +
         let html_signature identity = identity.html_signature

     

       108
       108
       +
         let may_delete identity = identity.may_delete

     

       109
       109
       +
       end

     

       110
       110
       +
       

     

       111
       111
       +
       (** Identity monitor args type *)

     

       112
       112
       +
       type identity_monitor_args = {

     

       113
       113
       +
         list_identities : bool;

     

       114
       114
       +
         show_identity : string option;

     

       115
       115
       +
         create_identity : string option;

     

       116
       116
       +
         identity_name : string option;

     

       117
       117
       +
         reply_to : string option;

     

       118
       118
       +
         signature : string option;

     

       119
       119
       +
         html_signature : string option;

     

       120
       120
       +
         list_submissions : bool;

     

       121
       121
       +
         show_submission : string option;

     

       122
       122
       +
         track_submission : string option;

     

       123
       123
       +
         pending_only : bool;

     

       124
       124
       +
         query : string option;

     

       125
       125
       +
         days : int;

     

       126
       126
       +
         limit : int;

     

       127
       127
       +
         cancel_submission : string option;

     

       128
       128
       +
         format : [`Summary | `Detailed | `Json | `StatusOnly];

     

       129
       129
       +
       }

     

       130
       130
       +
       

     

       131
       131
       +
       (** Command-line arguments **)

     

       132
       132
       +
       

     

       133
       133
       +
       let host_arg =

     

       134
       134
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       135
       135
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       136
       136
       +
       

     

       137
       137
       +
       let user_arg =

     

       138
       138
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       139
       139
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       140
       140
       +
       

     

       141
       141
       +
       let password_arg =

     

       142
       142
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       143
       143
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       144
       144
       +
       

     

       145
       145
       +
       (* Commands *)

     

       146
       146
       +
       

     

       147
       147
       +
       (* Identity-related commands *)

     

       148
       148
       +
       let list_identities_arg =

     

       149
       149
       +
         Arg.(value & flag & info ["list-identities"] ~doc:"List all email identities")

     

       150
       150
       +
       

     

       151
       151
       +
       let show_identity_arg =

     

       152
       152
       +
         Arg.(value & opt (some string) None & info ["show-identity"] 

     

       153
       153
       +
              ~docv:"ID" ~doc:"Show details for a specific identity")

     

       154
       154
       +
       

     

       155
       155
       +
       let create_identity_arg =

     

       156
       156
       +
         Arg.(value & opt (some string) None & info ["create-identity"] 

     

       157
       157
       +
              ~docv:"EMAIL" ~doc:"Create a new identity with the specified email address")

     

       158
       158
       +
       

     

       159
       159
       +
       let identity_name_arg =

     

       160
       160
       +
         Arg.(value & opt (some string) None & info ["name"] 

     

       161
       161
       +
              ~docv:"NAME" ~doc:"Display name for the identity (when creating)")

     

       162
       162
       +
       

     

       163
       163
       +
       let reply_to_arg =

     

       164
       164
       +
         Arg.(value & opt (some string) None & info ["reply-to"] 

     

       165
       165
       +
              ~docv:"EMAIL" ~doc:"Reply-to address for the identity (when creating)")

     

       166
       166
       +
       

     

       167
       167
       +
       let signature_arg =

     

       168
       168
       +
         Arg.(value & opt (some string) None & info ["signature"] 

     

       169
       169
       +
              ~docv:"SIGNATURE" ~doc:"Text signature for the identity (when creating)")

     

       170
       170
       +
       

     

       171
       171
       +
       let html_signature_arg =

     

       172
       172
       +
         Arg.(value & opt (some string) None & info ["html-signature"] 

     

       173
       173
       +
              ~docv:"HTML" ~doc:"HTML signature for the identity (when creating)")

     

       174
       174
       +
       

     

       175
       175
       +
       (* Submission-related commands *)

     

       176
       176
       +
       let list_submissions_arg =

     

       177
       177
       +
         Arg.(value & flag & info ["list-submissions"] ~doc:"List recent email submissions")

     

       178
       178
       +
       

     

       179
       179
       +
       let show_submission_arg =

     

       180
       180
       +
         Arg.(value & opt (some string) None & info ["show-submission"] 

     

       181
       181
       +
              ~docv:"ID" ~doc:"Show details for a specific submission")

     

       182
       182
       +
       

     

       183
       183
       +
       let track_submission_arg =

     

       184
       184
       +
         Arg.(value & opt (some string) None & info ["track"] 

     

       185
       185
       +
              ~docv:"ID" ~doc:"Track delivery status for a specific submission")

     

       186
       186
       +
       

     

       187
       187
       +
       let pending_only_arg =

     

       188
       188
       +
         Arg.(value & flag & info ["pending-only"] ~doc:"Show only pending submissions")

     

       189
       189
       +
       

     

       190
       190
       +
       let query_arg =

     

       191
       191
       +
         Arg.(value & opt (some string) None & info ["query"] 

     

       192
       192
       +
              ~docv:"QUERY" ~doc:"Search for submissions containing text in associated email")

     

       193
       193
       +
       

     

       194
       194
       +
       let days_arg =

     

       195
       195
       +
         Arg.(value & opt int 7 & info ["days"] 

     

       196
       196
       +
              ~docv:"DAYS" ~doc:"Limit to submissions from the past N days")

     

       197
       197
       +
       

     

       198
       198
       +
       let limit_arg =

     

       199
       199
       +
         Arg.(value & opt int 20 & info ["limit"] 

     

       200
       200
       +
              ~docv:"N" ~doc:"Maximum number of results to display")

     

       201
       201
       +
       

     

       202
       202
       +
       let cancel_submission_arg =

     

       203
       203
       +
         Arg.(value & opt (some string) None & info ["cancel"] 

     

       204
       204
       +
              ~docv:"ID" ~doc:"Cancel a pending email submission")

     

       205
       205
       +
       

     

       206
       206
       +
       let format_arg =

     

       207
       207
       +
         Arg.(value & opt (enum [

     

       208
       208
       +
           "summary", `Summary;

     

       209
       209
       +
           "detailed", `Detailed;

     

       210
       210
       +
           "json", `Json;

     

       211
       211
       +
           "status-only", `StatusOnly;

     

       212
       212
       +
         ]) `Summary & info ["format"] ~docv:"FORMAT" ~doc:"Output format")

     

       213
       213
       +
       

     

       214
       214
       +
       (** Main functionality **)

     

       215
       215
       +
       

     

       216
       216
       +
       (* Format an identity for display *)

     

       217
       217
       +
       let format_identity identity format =

     

       218
       218
       +
         match format with

     

       219
       219
       +
         | `Summary ->

     

       220
       220
       +
             let id = Identity.id identity in

     

       221
       221
       +
             let name = Identity.name identity in

     

       222
       222
       +
             let email = Identity.email identity in

     

       223
       223
       +
             Printf.printf "%s: %s <%s>\n" id name email

     

       224
       224
       +
         

     

       225
       225
       +
         | `Detailed ->

     

       226
       226
       +
             let id = Identity.id identity in

     

       227
       227
       +
             let name = Identity.name identity in

     

       228
       228
       +
             let email = Identity.email identity in

     

       229
       229
       +
             

     

       230
       230
       +
             let reply_to = match Identity.reply_to identity with

     

       231
       231
       +
               | Some addresses -> addresses 

     

       232
       232
       +
                   |> List.map (fun addr -> Email_address.email addr)

     

       233
       233
       +
                   |> String.concat ", "

     

       234
       234
       +
               | None -> "(none)"

     

       235
       235
       +
             in

     

       236
       236
       +
             

     

       237
       237
       +
             let bcc = match Identity.bcc identity with

     

       238
       238
       +
               | Some addresses -> addresses 

     

       239
       239
       +
                   |> List.map (fun addr -> Email_address.email addr)

     

       240
       240
       +
                   |> String.concat ", "

     

       241
       241
       +
               | None -> "(none)"

     

       242
       242
       +
             in

     

       243
       243
       +
             

     

       244
       244
       +
             let may_delete = if Identity.may_delete identity then "Yes" else "No" in

     

       245
       245
       +
             

     

       246
       246
       +
             Printf.printf "Identity: %s\n" id;

     

       247
       247
       +
             Printf.printf "  Name:       %s\n" name;

     

       248
       248
       +
             Printf.printf "  Email:      %s\n" email;

     

       249
       249
       +
             Printf.printf "  Reply-To:   %s\n" reply_to;

     

       250
       250
       +
             Printf.printf "  BCC:        %s\n" bcc;

     

       251
       251
       +
             

     

       252
       252
       +
             if Identity.text_signature identity <> "" then

     

       253
       253
       +
               Printf.printf "  Signature:  %s\n" (Identity.text_signature identity);

     

       254
       254
       +
             

     

       255
       255
       +
             if Identity.html_signature identity <> "" then

     

       256
       256
       +
               Printf.printf "  HTML Sig:   (HTML signature available)\n";

     

       257
       257
       +
             

     

       258
       258
       +
             Printf.printf "  Deletable:  %s\n" may_delete

     

       259
       259
       +
         

     

       260
       260
       +
         | `Json ->

     

       261
       261
       +
             let id = Identity.id identity in

     

       262
       262
       +
             let name = Identity.name identity in

     

       263
       263
       +
             let email = Identity.email identity in

     

       264
       264
       +
             Printf.printf "{\n";

     

       265
       265
       +
             Printf.printf "  \"id\": \"%s\",\n" id;

     

       266
       266
       +
             Printf.printf "  \"name\": \"%s\",\n" name;

     

       267
       267
       +
             Printf.printf "  \"email\": \"%s\"\n" email;

     

       268
       268
       +
             Printf.printf "}\n"

     

       269
       269
       +
             

     

       270
       270
       +
         | _ -> ()  (* Other formats don't apply to identities *)

     

       271
       271
       +
       

     

       272
       272
       +
       (* Format delivery status *)

     

       273
       273
       +
       let format_delivery_status rcpt status =

     

       274
       274
       +
         let status_str = match status.delivery_delivered with

     

       275
       275
       +
           | `Queued -> "Queued"

     

       276
       276
       +
           | `Yes -> "Delivered"

     

       277
       277
       +
           | `No -> "Failed"

     

       278
       278
       +
           | `Unknown -> "Unknown"

     

       279
       279
       +
         in

     

       280
       280
       +
         

     

       281
       281
       +
         let display_str = match status.delivery_displayed with

     

       282
       282
       +
           | `Yes -> "Displayed"

     

       283
       283
       +
           | `Unknown -> "Unknown if displayed"

     

       284
       284
       +
         in

     

       285
       285
       +
         

     

       286
       286
       +
         Printf.printf "  %s: %s, %s\n" rcpt status_str display_str;

     

       287
       287
       +
         Printf.printf "    SMTP Reply: %s\n" status.delivery_smtp_reply

     

       288
       288
       +
       

     

       289
       289
       +
       (* Format a submission for display *)

     

       290
       290
       +
       let format_submission submission format =

     

       291
       291
       +
         match format with

     

       292
       292
       +
         | `Summary ->

     

       293
       293
       +
             let id = submission.email_sub_id in

     

       294
       294
       +
             let email_id = submission.email_id in

     

       295
       295
       +
             let send_at = String.sub (ISO8601.string_of_datetime (Unix.gmtime submission.send_at)) 0 19 in

     

       296
       296
       +
             

     

       297
       297
       +
             let status = match submission.undo_status with

     

       298
       298
       +
               | `Pending -> "Pending"

     

       299
       299
       +
               | `Final -> "Final"

     

       300
       300
       +
               | `Canceled -> "Canceled"

     

       301
       301
       +
             in

     

       302
       302
       +
             

     

       303
       303
       +
             let delivery_count = match submission.delivery_status with

     

       304
       304
       +
               | Some statuses -> Hashtbl.length statuses

     

       305
       305
       +
               | None -> 0

     

       306
       306
       +
             in

     

       307
       307
       +
             

     

       308
       308
       +
             Printf.printf "%s: [%s] Sent at %s (Email ID: %s, Recipients: %d)\n" 

     

       309
       309
       +
               id status send_at email_id delivery_count

     

       310
       310
       +
         

     

       311
       311
       +
         | `Detailed ->

     

       312
       312
       +
             let id = submission.email_sub_id in

     

       313
       313
       +
             let email_id = submission.email_id in

     

       314
       314
       +
             let thread_id = submission.thread_id in

     

       315
       315
       +
             let identity_id = submission.identity_id in

     

       316
       316
       +
             let send_at = String.sub (ISO8601.string_of_datetime (Unix.gmtime submission.send_at)) 0 19 in

     

       317
       317
       +
             

     

       318
       318
       +
             let status = match submission.undo_status with

     

       319
       319
       +
               | `Pending -> "Pending"

     

       320
       320
       +
               | `Final -> "Final"

     

       321
       321
       +
               | `Canceled -> "Canceled"

     

       322
       322
       +
             in

     

       323
       323
       +
             

     

       324
       324
       +
             Printf.printf "Submission: %s\n" id;

     

       325
       325
       +
             Printf.printf "  Status:     %s\n" status;

     

       326
       326
       +
             Printf.printf "  Sent at:    %s\n" send_at;

     

       327
       327
       +
             Printf.printf "  Email ID:   %s\n" email_id;

     

       328
       328
       +
             Printf.printf "  Thread ID:  %s\n" thread_id;

     

       329
       329
       +
             Printf.printf "  Identity:   %s\n" identity_id;

     

       330
       330
       +
             

     

       331
       331
       +
             (* Display envelope information if available *)

     

       332
       332
       +
             (match submission.envelope with

     

       333
       333
       +
             | Some env ->

     

       334
       334
       +
                 Printf.printf "  Envelope:\n";

     

       335
       335
       +
                 Printf.printf "    From: %s\n" env.env_mail_from.env_addr_email;

     

       336
       336
       +
                 Printf.printf "    To:   %s\n" 

     

       337
       337
       +
                   (env.env_rcpt_to |> List.map (fun addr -> addr.env_addr_email) |> String.concat ", ")

     

       338
       338
       +
             | None -> ());

     

       339
       339
       +
             

     

       340
       340
       +
             (* Display delivery status *)

     

       341
       341
       +
             (match submission.delivery_status with

     

       342
       342
       +
             | Some statuses ->

     

       343
       343
       +
                 Printf.printf "  Delivery Status:\n";

     

       344
       344
       +
                 statuses |> Hashtbl.iter format_delivery_status

     

       345
       345
       +
             | None -> Printf.printf "  Delivery Status: Not available\n");

     

       346
       346
       +
             

     

       347
       347
       +
             (* DSN and MDN information *)

     

       348
       348
       +
             if submission.dsn_blob_ids <> [] then

     

       349
       349
       +
               Printf.printf "  DSN Blobs:  %d available\n" (List.length submission.dsn_blob_ids);

     

       350
       350
       +
             

     

       351
       351
       +
             if submission.mdn_blob_ids <> [] then

     

       352
       352
       +
               Printf.printf "  MDN Blobs:  %d available\n" (List.length submission.mdn_blob_ids)

     

       353
       353
       +
         

     

       354
       354
       +
         | `Json ->

     

       355
       355
       +
             let id = submission.email_sub_id in

     

       356
       356
       +
             let email_id = submission.email_id in

     

       357
       357
       +
             let send_at_str = String.sub (ISO8601.string_of_datetime (Unix.gmtime submission.send_at)) 0 19 in

     

       358
       358
       +
             

     

       359
       359
       +
             let status_str = match submission.undo_status with

     

       360
       360
       +
               | `Pending -> "pending"

     

       361
       361
       +
               | `Final -> "final"

     

       362
       362
       +
               | `Canceled -> "canceled"

     

       363
       363
       +
             in

     

       364
       364
       +
             

     

       365
       365
       +
             Printf.printf "{\n";

     

       366
       366
       +
             Printf.printf "  \"id\": \"%s\",\n" id;

     

       367
       367
       +
             Printf.printf "  \"emailId\": \"%s\",\n" email_id;

     

       368
       368
       +
             Printf.printf "  \"sendAt\": \"%s\",\n" send_at_str;

     

       369
       369
       +
             Printf.printf "  \"undoStatus\": \"%s\"\n" status_str;

     

       370
       370
       +
             Printf.printf "}\n"

     

       371
       371
       +
             

     

       372
       372
       +
         | `StatusOnly ->

     

       373
       373
       +
             let id = submission.email_sub_id in

     

       374
       374
       +
             

     

       375
       375
       +
             let status = match submission.undo_status with

     

       376
       376
       +
               | `Pending -> "Pending"

     

       377
       377
       +
               | `Final -> "Final"

     

       378
       378
       +
               | `Canceled -> "Canceled"

     

       379
       379
       +
             in

     

       380
       380
       +
             

     

       381
       381
       +
             Printf.printf "Submission %s: %s\n" id status;

     

       382
       382
       +
             

     

       383
       383
       +
             (* Display delivery status summary *)

     

       384
       384
       +
             match submission.delivery_status with

     

       385
       385
       +
             | Some statuses ->

     

       386
       386
       +
                 let total = Hashtbl.length statuses in

     

       387
       387
       +
                 let delivered = Hashtbl.fold (fun _ status count ->

     

       388
       388
       +
                   if status.delivery_delivered = `Yes then count + 1 else count

     

       389
       389
       +
                 ) statuses 0 in

     

       390
       390
       +
                 

     

       391
       391
       +
                 let failed = Hashtbl.fold (fun _ status count ->

     

       392
       392
       +
                   if status.delivery_delivered = `No then count + 1 else count

     

       393
       393
       +
                 ) statuses 0 in

     

       394
       394
       +
                 

     

       395
       395
       +
                 let queued = Hashtbl.fold (fun _ status count ->

     

       396
       396
       +
                   if status.delivery_delivered = `Queued then count + 1 else count

     

       397
       397
       +
                 ) statuses 0 in

     

       398
       398
       +
                 

     

       399
       399
       +
                 Printf.printf "  Total recipients: %d\n" total;

     

       400
       400
       +
                 Printf.printf "  Delivered: %d\n" delivered;

     

       401
       401
       +
                 Printf.printf "  Failed: %d\n" failed;

     

       402
       402
       +
                 Printf.printf "  Queued: %d\n" queued

     

       403
       403
       +
             | None -> 

     

       404
       404
       +
                 Printf.printf "  Delivery status not available\n"

     

       405
       405
       +
       

     

       406
       406
       +
       (* Create an identity with provided details *)

     

       407
       407
       +
       let create_identity_command email name reply_to signature html_signature =

     

       408
       408
       +
         (* In a real implementation, this would validate inputs and create the identity *)

     

       409
       409
       +
         Printf.printf "Creating identity for email: %s\n" email;

     

       410
       410
       +
         

     

       411
       411
       +
         if name <> None then

     

       412
       412
       +
           Printf.printf "Name: %s\n" (Option.get name);

     

       413
       413
       +
         

     

       414
       414
       +
         if reply_to <> None then

     

       415
       415
       +
           Printf.printf "Reply-To: %s\n" (Option.get reply_to);

     

       416
       416
       +
         

     

       417
       417
       +
         if signature <> None || html_signature <> None then

     

       418
       418
       +
           Printf.printf "Signature: Provided\n";

     

       419
       419
       +
         

     

       420
       420
       +
         Printf.printf "\nIdentity creation would be implemented here using JMAP.Identity.create\n";

     

       421
       421
       +
         ()

     

       422
       422
       +
       

     

       423
       423
       +
       (* Command implementation for identity monitoring *)

     

       424
       424
       +
       let identity_command host user password list_identities show_identity 

     

       425
       425
       +
                            create_identity identity_name reply_to signature 

     

       426
       426
       +
                            html_signature list_submissions show_submission track_submission

     

       427
       427
       +
                            pending_only query days limit cancel_submission format : int =

     

       428
       428
       +
         (* Pack arguments into a record for easier passing *)

     

       429
       429
       +
         let args : identity_monitor_args = {

     

       430
       430
       +
           list_identities; show_identity; create_identity; identity_name; 

     

       431
       431
       +
           reply_to; signature; html_signature; list_submissions; 

     

       432
       432
       +
           show_submission; track_submission; pending_only; query; 

     

       433
       433
       +
           days; limit; cancel_submission; format

     

       434
       434
       +
         } in

     

       435
       435
       +
         

     

       436
       436
       +
         (* Main workflow would be implemented here using the JMAP library *)

     

       437
       437
       +
         Printf.printf "JMAP Identity & Submission Monitor\n";

     

       438
       438
       +
         Printf.printf "Server: %s\n" host;

     

       439
       439
       +
         Printf.printf "User: %s\n\n" user;

     

       440
       440
       +
         

     

       441
       441
       +
         (* This is where the actual JMAP calls would happen, like:

     

       442
       442
       +
         

     

       443
       443
       +
         let monitor_identities_and_submissions () =

     

       444
       444
       +
           let* (ctx, session) = Jmap.Unix.connect 

     

       445
       445
       +
             ~host ~username:user ~password 

     

       446
       446
       +
             ~auth_method:(Jmap.Unix.Basic(user, password)) () in

     

       447
       447
       +
           

     

       448
       448
       +
           (* Get primary account ID *)

     

       449
       449
       +
           let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       450
       450
       +
             | Ok id -> id

     

       451
       451
       +
             | Error _ -> failwith "No mail account found"

     

       452
       452
       +
           in

     

       453
       453
       +
           

     

       454
       454
       +
           (* Handle various command options *)

     

       455
       455
       +
           if args.list_identities then

     

       456
       456
       +
             (* Get all identities *)

     

       457
       457
       +
             let* identity_result = Jmap_email.Identity.get ctx

     

       458
       458
       +
               ~account_id

     

       459
       459
       +
               ~ids:None in

     

       460
       460
       +
             

     

       461
       461
       +
             match identity_result with

     

       462
       462
       +
             | Error err -> Printf.eprintf "Error: %s\n" (Jmap.Error.error_to_string err); Lwt.return 1

     

       463
       463
       +
             | Ok (_, identities) ->

     

       464
       464
       +
                 Printf.printf "Found %d identities:\n\n" (List.length identities);

     

       465
       465
       +
                 identities |> List.iter (fun identity ->

     

       466
       466
       +
                   format_identity identity args.format

     

       467
       467
       +
                 );

     

       468
       468
       +
                 Lwt.return 0

     

       469
       469
       +
           

     

       470
       470
       +
           else if args.show_identity <> None then

     

       471
       471
       +
             (* Get specific identity *)

     

       472
       472
       +
             let id = Option.get args.show_identity in

     

       473
       473
       +
             let* identity_result = Jmap_email.Identity.get ctx

     

       474
       474
       +
               ~account_id

     

       475
       475
       +
               ~ids:[id] in

     

       476
       476
       +
             

     

       477
       477
       +
             match identity_result with

     

       478
       478
       +
             | Error err -> Printf.eprintf "Error: %s\n" (Jmap.Error.error_to_string err); Lwt.return 1

     

       479
       479
       +
             | Ok (_, identities) ->

     

       480
       480
       +
                 match identities with

     

       481
       481
       +
                 | [identity] ->

     

       482
       482
       +
                     format_identity identity args.format;

     

       483
       483
       +
                     Lwt.return 0

     

       484
       484
       +
                 | _ ->

     

       485
       485
       +
                     Printf.eprintf "Identity not found: %s\n" id;

     

       486
       486
       +
                     Lwt.return 1

     

       487
       487
       +
           

     

       488
       488
       +
           else if args.create_identity <> None then

     

       489
       489
       +
             (* Create a new identity *)

     

       490
       490
       +
             let email = Option.get args.create_identity in

     

       491
       491
       +
             create_identity_command email args.identity_name args.reply_to 

     

       492
       492
       +
                                    args.signature args.html_signature

     

       493
       493
       +
           

     

       494
       494
       +
           else if args.list_submissions then

     

       495
       495
       +
             (* List all submissions, with optional filtering *)

     

       496
       496
       +
             ...

     

       497
       497
       +
           

     

       498
       498
       +
           else if args.show_submission <> None then

     

       499
       499
       +
             (* Show specific submission details *)

     

       500
       500
       +
             ...

     

       501
       501
       +
           

     

       502
       502
       +
           else if args.track_submission <> None then

     

       503
       503
       +
             (* Track delivery status for a specific submission *)

     

       504
       504
       +
             ...

     

       505
       505
       +
           

     

       506
       506
       +
           else if args.cancel_submission <> None then

     

       507
       507
       +
             (* Cancel a pending submission *)

     

       508
       508
       +
             ...

     

       509
       509
       +
           

     

       510
       510
       +
           else

     

       511
       511
       +
             (* No specific command given, show help *)

     

       512
       512
       +
             Printf.printf "Please specify a command. Use --help for options.\n";

     

       513
       513
       +
             Lwt.return 1

     

       514
       514
       +
         *)

     

       515
       515
       +
         

     

       516
       516
       +
         (if list_identities then begin

     

       517
       517
       +
           (* Simulate listing identities *)

     

       518
       518
       +
           Printf.printf "Found 3 identities:\n\n";

     

       519
       519
       +
           Printf.printf "id1: John Doe <john@example.com>\n";

     

       520
       520
       +
           Printf.printf "id2: John Work <john@work.example.com>\n";

     

       521
       521
       +
           Printf.printf "id3: Support <support@example.com>\n"

     

       522
       522
       +
         end

     

       523
       523
       +
         else if show_identity <> None then begin

     

       524
       524
       +
           (* Simulate showing a specific identity *)

     

       525
       525
       +
           Printf.printf "Identity: %s\n" (Option.get show_identity);

     

       526
       526
       +
           Printf.printf "  Name:       John Doe\n";

     

       527
       527
       +
           Printf.printf "  Email:      john@example.com\n";

     

       528
       528
       +
           Printf.printf "  Reply-To:   (none)\n";

     

       529
       529
       +
           Printf.printf "  BCC:        (none)\n";

     

       530
       530
       +
           Printf.printf "  Signature:  Best regards,\nJohn\n";

     

       531
       531
       +
           Printf.printf "  Deletable:  Yes\n"

     

       532
       532
       +
         end

     

       533
       533
       +
         

     

       534
       534
       +
         else if create_identity <> None then begin

     

       535
       535
       +
           (* Create a new identity *)

     

       536
       536
       +
           create_identity_command (Option.get create_identity) identity_name reply_to 

     

       537
       537
       +
                                    signature html_signature |> ignore

     

       538
       538
       +
         end

     

       539
       539
       +
         else if list_submissions then begin

     

       540
       540
       +
           (* Simulate listing submissions *)

     

       541
       541
       +
           Printf.printf "Recent submissions (last %d days):\n\n" days;

     

       542
       542
       +
           Printf.printf "sub1: [Final] Sent at 2023-01-15 10:30:45 (Email ID: email1, Recipients: 3)\n";

     

       543
       543
       +
           Printf.printf "sub2: [Final] Sent at 2023-01-14 08:15:22 (Email ID: email2, Recipients: 1)\n";

     

       544
       544
       +
           Printf.printf "sub3: [Pending] Sent at 2023-01-13 16:45:10 (Email ID: email3, Recipients: 5)\n"

     

       545
       545
       +
         end

     

       546
       546
       +
         else if show_submission <> None then begin

     

       547
       547
       +
           (* Simulate showing a specific submission *)

     

       548
       548
       +
           Printf.printf "Submission: %s\n" (Option.get show_submission);

     

       549
       549
       +
           Printf.printf "  Status:     Final\n";

     

       550
       550
       +
           Printf.printf "  Sent at:    2023-01-15 10:30:45\n";

     

       551
       551
       +
           Printf.printf "  Email ID:   email1\n";

     

       552
       552
       +
           Printf.printf "  Thread ID:  thread1\n";

     

       553
       553
       +
           Printf.printf "  Identity:   id1\n";

     

       554
       554
       +
           Printf.printf "  Envelope:\n";

     

       555
       555
       +
           Printf.printf "    From: john@example.com\n";

     

       556
       556
       +
           Printf.printf "    To:   alice@example.com, bob@example.com, carol@example.com\n";

     

       557
       557
       +
           Printf.printf "  Delivery Status:\n";

     

       558
       558
       +
           Printf.printf "    alice@example.com: Delivered, Displayed\n";

     

       559
       559
       +
           Printf.printf "      SMTP Reply: 250 OK\n";

     

       560
       560
       +
           Printf.printf "    bob@example.com: Delivered, Unknown if displayed\n";

     

       561
       561
       +
           Printf.printf "      SMTP Reply: 250 OK\n";

     

       562
       562
       +
           Printf.printf "    carol@example.com: Failed\n";

     

       563
       563
       +
           Printf.printf "      SMTP Reply: 550 Mailbox unavailable\n"

     

       564
       564
       +
         end

     

       565
       565
       +
         else if track_submission <> None then begin

     

       566
       566
       +
           (* Simulate tracking a submission *)

     

       567
       567
       +
           Printf.printf "Tracking delivery status for submission: %s\n\n" (Option.get track_submission);

     

       568
       568
       +
           Printf.printf "Submission %s: Final\n" (Option.get track_submission);

     

       569
       569
       +
           Printf.printf "  Total recipients: 3\n";

     

       570
       570
       +
           Printf.printf "  Delivered: 2\n";

     

       571
       571
       +
           Printf.printf "  Failed: 1\n";

     

       572
       572
       +
           Printf.printf "  Queued: 0\n"

     

       573
       573
       +
         end

     

       574
       574
       +
         else if cancel_submission <> None then begin

     

       575
       575
       +
           (* Simulate canceling a submission *)

     

       576
       576
       +
           Printf.printf "Canceling submission: %s\n" (Option.get cancel_submission);

     

       577
       577
       +
           Printf.printf "Submission has been canceled successfully.\n"

     

       578
       578
       +
         end

     

       579
       579
       +
         else 

     

       580
       580
       +
           (* No specific command given, show help *)

     

       581
       581
       +
           begin

     

       582
       582
       +
             Printf.printf "Please specify a command. Use --help for options.\n";

     

       583
       583
       +
             Printf.printf "Example commands:\n";

     

       584
       584
       +
             Printf.printf "  --list-identities      List all email identities\n";

     

       585
       585
       +
             Printf.printf "  --show-identity id1    Show details for identity 'id1'\n";

     

       586
       586
       +
             Printf.printf "  --list-submissions     List recent email submissions\n";

     

       587
       587
       +
             Printf.printf "  --track sub1           Track delivery status for submission 'sub1'\n"

     

       588
       588
       +
           end);

     

       589
       589
       +
         

     

       590
       590
       +
         (* Since we're only type checking, we'll exit with success *)

     

       591
       591
       +
         0

     

       592
       592
       +
       

     

       593
       593
       +
       (* Command definition *)

     

       594
       594
       +
       let identity_cmd =

     

       595
       595
       +
         let doc = "monitor email identities and submissions using JMAP" in

     

       596
       596
       +
         let man = [

     

       597
       597
       +
           `S Manpage.s_description;

     

       598
       598
       +
           `P "Provides identity management and email submission tracking functionality.";

     

       599
       599
       +
           `P "Demonstrates JMAP's identity and email submission monitoring capabilities.";

     

       600
       600
       +
           `S Manpage.s_examples;

     

       601
       601
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --list-identities";

     

       602
       602
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --create-identity backup@example.com --name \"Backup Account\"";

     

       603
       603
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --list-submissions --days 3";

     

       604
       604
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --track sub12345 --format status-only";

     

       605
       605
       +
         ] in

     

       606
       606
       +
         

     

       607
       607
       +
         let cmd =

     

       608
       608
       +
           Cmd.v

     

       609
       609
       +
             (Cmd.info "jmap-identity-monitor" ~version:"1.0" ~doc ~man)

     

       610
       610
       +
             Term.(const identity_command $ host_arg $ user_arg $ password_arg $ 

     

       611
       611
       +
                   list_identities_arg $ show_identity_arg $ create_identity_arg $ 

     

       612
       612
       +
                   identity_name_arg $ reply_to_arg $ signature_arg $ html_signature_arg $

     

       613
       613
       +
                   list_submissions_arg $ show_submission_arg $ track_submission_arg $

     

       614
       614
       +
                   pending_only_arg $ query_arg $ days_arg $ limit_arg $ 

     

       615
       615
       +
                   cancel_submission_arg $ format_arg)

     

       616
       616
       +
         in

     

       617
       617
       +
         cmd

     

       618
       618
       +
       

     

       619
       619
       +
       (* Main entry point *)

     

       620
       620
       +
       let () = exit (Cmd.eval' identity_cmd)

+420

bin/jmap_mailbox_explorer.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_mailbox_explorer.ml - A tool for exploring email mailboxes using JMAP

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates JMAP's mailbox query and manipulation capabilities,

     

       5
       5
       +
        * allowing for exploring, creating, and analyzing mailboxes.

     

       6
       6
       +
        *)

     

       7
       7
       +
       

     

       8
       8
       +
       open Cmdliner

     

       9
       9
       +
       (* Using standard OCaml, no Lwt *)

     

       10
       10
       +
       

     

       11
       11
       +
       (* JMAP imports *)

     

       12
       12
       +
       open Jmap

     

       13
       13
       +
       open Jmap.Types

     

       14
       14
       +
       open Jmap.Wire

     

       15
       15
       +
       open Jmap.Methods

     

       16
       16
       +
       open Jmap_email

     

       17
       17
       +
       (* For step 2, we're only testing type checking. No implementations required. *)

     

       18
       18
       +
       

     

       19
       19
       +
       (* JMAP mailbox handling *)

     

       20
       20
       +
       module Jmap_mailbox = struct

     

       21
       21
       +
         (* Dummy mailbox functions *)

     

       22
       22
       +
         let id mailbox = "mailbox-id"

     

       23
       23
       +
         let name mailbox = "mailbox-name"

     

       24
       24
       +
         let parent_id mailbox = None

     

       25
       25
       +
         let role mailbox = None

     

       26
       26
       +
         let total_emails mailbox = 0

     

       27
       27
       +
         let unread_emails mailbox = 0

     

       28
       28
       +
       end

     

       29
       29
       +
       

     

       30
       30
       +
       (* Unix implementation would be used here *)

     

       31
       31
       +
       module Unix = struct

     

       32
       32
       +
         let connect ~host ~username ~password ?auth_method () =

     

       33
       33
       +
           failwith "Not implemented"

     

       34
       34
       +
       end

     

       35
       35
       +
       

     

       36
       36
       +
       (** Types for mailbox explorer *)

     

       37
       37
       +
       type mailbox_stats = {

     

       38
       38
       +
         time_periods : (string * int) list;

     

       39
       39
       +
         senders : (string * int) list;

     

       40
       40
       +
         subjects : (string * int) list;

     

       41
       41
       +
       }

     

       42
       42
       +
       

     

       43
       43
       +
       type mailbox_explorer_args = {

     

       44
       44
       +
         list : bool;

     

       45
       45
       +
         stats : bool;

     

       46
       46
       +
         mailbox : string option;

     

       47
       47
       +
         create : string option;

     

       48
       48
       +
         parent : string option;

     

       49
       49
       +
         query_mailbox : string option;

     

       50
       50
       +
         days : int;

     

       51
       51
       +
         format : [`Tree | `Flat | `Json];

     

       52
       52
       +
       }

     

       53
       53
       +
       

     

       54
       54
       +
       (** Command-line arguments **)

     

       55
       55
       +
       

     

       56
       56
       +
       let host_arg =

     

       57
       57
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       58
       58
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       59
       59
       +
       

     

       60
       60
       +
       let user_arg =

     

       61
       61
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       62
       62
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       63
       63
       +
       

     

       64
       64
       +
       let password_arg =

     

       65
       65
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       66
       66
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       67
       67
       +
       

     

       68
       68
       +
       let list_arg =

     

       69
       69
       +
         Arg.(value & flag & info ["l"; "list"] ~doc:"List all mailboxes")

     

       70
       70
       +
       

     

       71
       71
       +
       let stats_arg =

     

       72
       72
       +
         Arg.(value & flag & info ["s"; "stats"] ~doc:"Show mailbox statistics")

     

       73
       73
       +
       

     

       74
       74
       +
       let mailbox_arg =

     

       75
       75
       +
         Arg.(value & opt (some string) None & info ["m"; "mailbox"] 

     

       76
       76
       +
              ~docv:"MAILBOX" ~doc:"Filter by mailbox name")

     

       77
       77
       +
       

     

       78
       78
       +
       let create_arg =

     

       79
       79
       +
         Arg.(value & opt (some string) None & info ["create"] 

     

       80
       80
       +
              ~docv:"NAME" ~doc:"Create a new mailbox")

     

       81
       81
       +
       

     

       82
       82
       +
       let parent_arg =

     

       83
       83
       +
         Arg.(value & opt (some string) None & info ["parent"] 

     

       84
       84
       +
              ~docv:"PARENT" ~doc:"Parent mailbox for creation")

     

       85
       85
       +
       

     

       86
       86
       +
       let query_mailbox_arg =

     

       87
       87
       +
         Arg.(value & opt (some string) None & info ["query"] 

     

       88
       88
       +
              ~docv:"QUERY" ~doc:"Query emails in the specified mailbox")

     

       89
       89
       +
       

     

       90
       90
       +
       let days_arg =

     

       91
       91
       +
         Arg.(value & opt int 7 & info ["days"] 

     

       92
       92
       +
              ~docv:"DAYS" ~doc:"Days to analyze for mailbox statistics")

     

       93
       93
       +
       

     

       94
       94
       +
       let format_arg =

     

       95
       95
       +
         Arg.(value & opt (enum [

     

       96
       96
       +
           "tree", `Tree;

     

       97
       97
       +
           "flat", `Flat;

     

       98
       98
       +
           "json", `Json;

     

       99
       99
       +
         ]) `Tree & info ["format"] ~docv:"FORMAT" ~doc:"Output format")

     

       100
       100
       +
       

     

       101
       101
       +
       (** Mailbox Explorer Functionality **)

     

       102
       102
       +
       

     

       103
       103
       +
       (* Get standard role name for display *)

     

       104
       104
       +
       let role_name = function

     

       105
       105
       +
         | `Inbox -> "Inbox"

     

       106
       106
       +
         | `Archive -> "Archive"

     

       107
       107
       +
         | `Drafts -> "Drafts"

     

       108
       108
       +
         | `Sent -> "Sent"

     

       109
       109
       +
         | `Trash -> "Trash"

     

       110
       110
       +
         | `Junk -> "Junk"

     

       111
       111
       +
         | `Important -> "Important"

     

       112
       112
       +
         | `Flagged -> "Flagged"

     

       113
       113
       +
         | `Snoozed -> "Snoozed"

     

       114
       114
       +
         | `Scheduled -> "Scheduled"

     

       115
       115
       +
         | `Memos -> "Memos"

     

       116
       116
       +
         | `Other name -> name

     

       117
       117
       +
         | `None -> "(No role)"

     

       118
       118
       +
       

     

       119
       119
       +
       (* Display mailboxes in tree format *)

     

       120
       120
       +
       let display_mailbox_tree mailboxes format stats =

     

       121
       121
       +
         (* Helper to find children of a parent *)

     

       122
       122
       +
         let find_children parent_id =

     

       123
       123
       +
           mailboxes |> List.filter (fun mailbox ->

     

       124
       124
       +
             match Jmap_mailbox.parent_id mailbox with

     

       125
       125
       +
             | Some id when id = parent_id -> true

     

       126
       126
       +
             | _ -> false

     

       127
       127
       +
           )

     

       128
       128
       +
         in

     

       129
       129
       +
         

     

       130
       130
       +
         (* Helper to find mailboxes without a parent (root level) *)

     

       131
       131
       +
         let find_roots () =

     

       132
       132
       +
           mailboxes |> List.filter (fun mailbox ->

     

       133
       133
       +
             Jmap_mailbox.parent_id mailbox = None

     

       134
       134
       +
           )

     

       135
       135
       +
         in

     

       136
       136
       +
         

     

       137
       137
       +
         (* Get mailbox name with role *)

     

       138
       138
       +
         let mailbox_name_with_role mailbox =

     

       139
       139
       +
           let name = Jmap_mailbox.name mailbox in

     

       140
       140
       +
           match Jmap_mailbox.role mailbox with

     

       141
       141
       +
           | Some role -> Printf.sprintf "%s (%s)" name (role_name role)

     

       142
       142
       +
           | None -> name

     

       143
       143
       +
         in

     

       144
       144
       +
         

     

       145
       145
       +
         (* Helper to get statistics for a mailbox *)

     

       146
       146
       +
         let get_stats mailbox =

     

       147
       147
       +
           let id = Jmap_mailbox.id mailbox in

     

       148
       148
       +
           let total = Jmap_mailbox.total_emails mailbox in

     

       149
       149
       +
           let unread = Jmap_mailbox.unread_emails mailbox in

     

       150
       150
       +
           

     

       151
       151
       +
           match Hashtbl.find_opt stats id with

     

       152
       152
       +
           | Some mailbox_stats -> 

     

       153
       153
       +
               let recent = match List.assoc_opt "Last week" mailbox_stats.time_periods with

     

       154
       154
       +
                 | Some count -> count

     

       155
       155
       +
                 | None -> 0

     

       156
       156
       +
               in

     

       157
       157
       +
               (total, unread, recent)

     

       158
       158
       +
           | None -> (total, unread, 0)

     

       159
       159
       +
         in

     

       160
       160
       +
         

     

       161
       161
       +
         (* Helper to print a JSON representation *)

     

       162
       162
       +
         let print_json_mailbox mailbox indent =

     

       163
       163
       +
           let id = Jmap_mailbox.id mailbox in

     

       164
       164
       +
           let name = Jmap_mailbox.name mailbox in

     

       165
       165
       +
           let role = match Jmap_mailbox.role mailbox with

     

       166
       166
       +
             | Some role -> Printf.sprintf "\"%s\"" (role_name role)

     

       167
       167
       +
             | None -> "null"

     

       168
       168
       +
           in

     

       169
       169
       +
           let total, unread, recent = get_stats mailbox in

     

       170
       170
       +
           

     

       171
       171
       +
           let indent_str = String.make indent ' ' in

     

       172
       172
       +
           Printf.printf "%s{\n" indent_str;

     

       173
       173
       +
           Printf.printf "%s  \"id\": \"%s\",\n" indent_str id;

     

       174
       174
       +
           Printf.printf "%s  \"name\": \"%s\",\n" indent_str name;

     

       175
       175
       +
           Printf.printf "%s  \"role\": %s,\n" indent_str role;

     

       176
       176
       +
           Printf.printf "%s  \"totalEmails\": %d,\n" indent_str total;

     

       177
       177
       +
           Printf.printf "%s  \"unreadEmails\": %d,\n" indent_str unread;

     

       178
       178
       +
           Printf.printf "%s  \"recentEmails\": %d\n" indent_str recent;

     

       179
       179
       +
           Printf.printf "%s}" indent_str

     

       180
       180
       +
         in

     

       181
       181
       +
         

     

       182
       182
       +
         (* Recursive function to print a tree of mailboxes *)

     

       183
       183
       +
         let rec print_tree_level mailboxes level =

     

       184
       184
       +
           mailboxes |> List.iteri (fun i mailbox ->

     

       185
       185
       +
             let id = Jmap_mailbox.id mailbox in

     

       186
       186
       +
             let name = mailbox_name_with_role mailbox in

     

       187
       187
       +
             let total, unread, recent = get_stats mailbox in

     

       188
       188
       +
             

     

       189
       189
       +
             let indent = String.make (level * 2) ' ' in

     

       190
       190
       +
             let is_last = i = List.length mailboxes - 1 in

     

       191
       191
       +
             let prefix = if level = 0 then "" else

     

       192
       192
       +
                          if is_last then "└── " else "├── " in

     

       193
       193
       +
             

     

       194
       194
       +
             match format with

     

       195
       195
       +
             | `Tree ->

     

       196
       196
       +
                 Printf.printf "%s%s%s" indent prefix name;

     

       197
       197
       +
                 if stats <> Hashtbl.create 0 then

     

       198
       198
       +
                   Printf.printf " (%d emails, %d unread, %d recent)" total unread recent;

     

       199
       199
       +
                 Printf.printf "\n";

     

       200
       200
       +
                 

     

       201
       201
       +
                 (* Print children *)

     

       202
       202
       +
                 let children = find_children id in

     

       203
       203
       +
                 let child_indent = level + 1 in

     

       204
       204
       +
                 print_tree_level children child_indent

     

       205
       205
       +
                 

     

       206
       206
       +
             | `Flat ->

     

       207
       207
       +
                 Printf.printf "%s [%s]\n" name id;

     

       208
       208
       +
                 if stats <> Hashtbl.create 0 then

     

       209
       209
       +
                   Printf.printf "  Emails: %d total, %d unread, %d in last week\n" 

     

       210
       210
       +
                     total unread recent;

     

       211
       211
       +
                 

     

       212
       212
       +
                 (* Print children *)

     

       213
       213
       +
                 let children = find_children id in

     

       214
       214
       +
                 print_tree_level children 0

     

       215
       215
       +
                 

     

       216
       216
       +
             | `Json ->

     

       217
       217
       +
                 print_json_mailbox mailbox (level * 2);

     

       218
       218
       +
                 

     

       219
       219
       +
                 (* Handle commas between mailboxes *)

     

       220
       220
       +
                 let children = find_children id in

     

       221
       221
       +
                 if children <> [] || (not is_last) then Printf.printf ",\n" else Printf.printf "\n";

     

       222
       222
       +
                 

     

       223
       223
       +
                 (* Print children as a "children" array *)

     

       224
       224
       +
                 if children <> [] then begin

     

       225
       225
       +
                   Printf.printf "%s\"children\": [\n" (String.make ((level * 2) + 2) ' ');

     

       226
       226
       +
                   print_tree_level children (level + 2);

     

       227
       227
       +
                   Printf.printf "%s]\n" (String.make ((level * 2) + 2) ' ');

     

       228
       228
       +
                   

     

       229
       229
       +
                   (* Add comma if not the last mailbox *)

     

       230
       230
       +
                   if not is_last then Printf.printf "%s,\n" (String.make (level * 2) ' ');

     

       231
       231
       +
                 end

     

       232
       232
       +
           )

     

       233
       233
       +
         in

     

       234
       234
       +
         

     

       235
       235
       +
         (* Print the mailbox tree *)

     

       236
       236
       +
         match format with

     

       237
       237
       +
         | `Tree | `Flat ->

     

       238
       238
       +
             Printf.printf "Mailboxes:\n";

     

       239
       239
       +
             print_tree_level (find_roots()) 0

     

       240
       240
       +
         | `Json ->

     

       241
       241
       +
             Printf.printf "{\n";

     

       242
       242
       +
             Printf.printf "  \"mailboxes\": [\n";

     

       243
       243
       +
             print_tree_level (find_roots()) 1;

     

       244
       244
       +
             Printf.printf "  ]\n";

     

       245
       245
       +
             Printf.printf "}\n"

     

       246
       246
       +
       

     

       247
       247
       +
       (* Command implementation *)

     

       248
       248
       +
       let mailbox_command host user password list stats mailbox create parent 

     

       249
       249
       +
                            query_mailbox days format : int =

     

       250
       250
       +
         (* Pack arguments into a record for easier passing *)

     

       251
       251
       +
         let args : mailbox_explorer_args = {

     

       252
       252
       +
           list; stats; mailbox; create; parent; 

     

       253
       253
       +
           query_mailbox; days; format

     

       254
       254
       +
         } in

     

       255
       255
       +
         

     

       256
       256
       +
         (* Main workflow would be implemented here using the JMAP library *)

     

       257
       257
       +
         Printf.printf "JMAP Mailbox Explorer\n";

     

       258
       258
       +
         Printf.printf "Server: %s\n" host;

     

       259
       259
       +
         Printf.printf "User: %s\n\n" user;

     

       260
       260
       +
         

     

       261
       261
       +
         (* This is where the actual JMAP calls would happen, like:

     

       262
       262
       +
         

     

       263
       263
       +
         let explore_mailboxes () =

     

       264
       264
       +
           let* (ctx, session) = Jmap.Unix.connect 

     

       265
       265
       +
             ~host ~username:user ~password 

     

       266
       266
       +
             ~auth_method:(Jmap.Unix.Basic(user, password)) () in

     

       267
       267
       +
           

     

       268
       268
       +
           (* Get primary account ID *)

     

       269
       269
       +
           let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       270
       270
       +
             | Ok id -> id

     

       271
       271
       +
             | Error _ -> failwith "No mail account found"

     

       272
       272
       +
           in

     

       273
       273
       +
           

     

       274
       274
       +
           (* Create a new mailbox if requested *)

     

       275
       275
       +
           if args.create <> None then

     

       276
       276
       +
             let name = Option.get args.create in

     

       277
       277
       +
             let parent_id_opt = match args.parent with

     

       278
       278
       +
               | None -> None

     

       279
       279
       +
               | Some parent_name ->

     

       280
       280
       +
                   (* Resolve parent name to ID - would need to search for it *)

     

       281
       281
       +
                   None (* This would actually find or return an error *)

     

       282
       282
       +
             in

     

       283
       283
       +
             

     

       284
       284
       +
             let create_mailbox = Jmap_mailbox.create 

     

       285
       285
       +
               ~name

     

       286
       286
       +
               ?parent_id:parent_id_opt

     

       287
       287
       +
               () in

     

       288
       288
       +
             

     

       289
       289
       +
             let* result = Jmap_mailbox.set ctx

     

       290
       290
       +
               ~account_id

     

       291
       291
       +
               ~create:(Hashtbl.of_seq (Seq.return ("new", create_mailbox)))

     

       292
       292
       +
               () in

     

       293
       293
       +
             

     

       294
       294
       +
             (* Handle mailbox creation result *)

     

       295
       295
       +
             ...

     

       296
       296
       +
           

     

       297
       297
       +
           (* List mailboxes *)

     

       298
       298
       +
           if args.list || args.stats then

     

       299
       299
       +
             (* Query mailboxes *)

     

       300
       300
       +
             let filter = 

     

       301
       301
       +
               if args.mailbox <> None then

     

       302
       302
       +
                 Jmap_mailbox.filter_name_contains (Option.get args.mailbox)

     

       303
       303
       +
               else

     

       304
       304
       +
                 Jmap_mailbox.Filter.condition (`Assoc [])

     

       305
       305
       +
             in

     

       306
       306
       +
             

     

       307
       307
       +
             let* mailbox_ids = Jmap_mailbox.query ctx

     

       308
       308
       +
               ~account_id

     

       309
       309
       +
               ~filter

     

       310
       310
       +
               ~sort:[Jmap_mailbox.sort_by_name () ]

     

       311
       311
       +
               () in

     

       312
       312
       +
             

     

       313
       313
       +
             match mailbox_ids with

     

       314
       314
       +
             | Error err -> 

     

       315
       315
       +
                 Printf.eprintf "Error querying mailboxes: %s\n" (Jmap.Error.error_to_string err);

     

       316
       316
       +
                 Lwt.return_unit

     

       317
       317
       +
             | Ok (ids, _) ->

     

       318
       318
       +
                 (* Get full mailbox objects *)

     

       319
       319
       +
                 let* mailboxes = Jmap_mailbox.get ctx

     

       320
       320
       +
                   ~account_id

     

       321
       321
       +
                   ~ids

     

       322
       322
       +
                   ~properties:["id"; "name"; "parentId"; "role"; "totalEmails"; "unreadEmails"] in

     

       323
       323
       +
                 

     

       324
       324
       +
                 match mailboxes with

     

       325
       325
       +
                 | Error err ->

     

       326
       326
       +
                     Printf.eprintf "Error getting mailboxes: %s\n" (Jmap.Error.error_to_string err);

     

       327
       327
       +
                     Lwt.return_unit

     

       328
       328
       +
                 | Ok (_, mailbox_list) ->

     

       329
       329
       +
                     (* If stats requested, gather email stats for each mailbox *)

     

       330
       330
       +
                     let* stats_opt = 

     

       331
       331
       +
                       if args.stats then

     

       332
       332
       +
                         (* For each mailbox, gather stats like weekly counts *)

     

       333
       333
       +
                         ...

     

       334
       334
       +
                       else

     

       335
       335
       +
                         Lwt.return (Hashtbl.create 0)

     

       336
       336
       +
                     in

     

       337
       337
       +
                     

     

       338
       338
       +
                     (* Display mailboxes in requested format *)

     

       339
       339
       +
                     display_mailbox_tree mailbox_list args.format stats_opt;

     

       340
       340
       +
                     Lwt.return_unit

     

       341
       341
       +
           

     

       342
       342
       +
           (* Query emails in a specific mailbox *)

     

       343
       343
       +
           if args.query_mailbox <> None then

     

       344
       344
       +
             let mailbox_name = Option.get args.query_mailbox in

     

       345
       345
       +
             

     

       346
       346
       +
             (* Find mailbox ID from name *)

     

       347
       347
       +
             ...

     

       348
       348
       +
             

     

       349
       349
       +
             (* Query emails in that mailbox *)

     

       350
       350
       +
             ...

     

       351
       351
       +
         *)

     

       352
       352
       +
         

     

       353
       353
       +
         if create <> None then

     

       354
       354
       +
           Printf.printf "Creating mailbox: %s\n" (Option.get create);

     

       355
       355
       +
         

     

       356
       356
       +
         if list || stats then

     

       357
       357
       +
           Printf.printf "Listing mailboxes%s:\n" 

     

       358
       358
       +
             (if stats then " with statistics" else "");

     

       359
       359
       +
         

     

       360
       360
       +
         (* Example output for a tree of mailboxes *)

     

       361
       361
       +
         (match format with

     

       362
       362
       +
         | `Tree -> 

     

       363
       363
       +
             Printf.printf "Mailboxes:\n";

     

       364
       364
       +
             Printf.printf "Inbox (14 emails, 3 unread, 5 recent)\n";

     

       365
       365
       +
             Printf.printf "├── Work (8 emails, 2 unread, 3 recent)\n";

     

       366
       366
       +
             Printf.printf "│   └── Project A (3 emails, 1 unread, 2 recent)\n";

     

       367
       367
       +
             Printf.printf "└── Personal (6 emails, 1 unread, 2 recent)\n"

     

       368
       368
       +
         | `Flat ->

     

       369
       369
       +
             Printf.printf "Inbox [mbox1]\n";

     

       370
       370
       +
             Printf.printf "  Emails: 14 total, 3 unread, 5 in last week\n";

     

       371
       371
       +
             Printf.printf "Work [mbox2]\n";

     

       372
       372
       +
             Printf.printf "  Emails: 8 total, 2 unread, 3 in last week\n";

     

       373
       373
       +
             Printf.printf "Project A [mbox3]\n";

     

       374
       374
       +
             Printf.printf "  Emails: 3 total, 1 unread, 2 in last week\n";

     

       375
       375
       +
             Printf.printf "Personal [mbox4]\n";

     

       376
       376
       +
             Printf.printf "  Emails: 6 total, 1 unread, 2 in last week\n"

     

       377
       377
       +
         | `Json ->

     

       378
       378
       +
             Printf.printf "{\n";

     

       379
       379
       +
             Printf.printf "  \"mailboxes\": [\n";

     

       380
       380
       +
             Printf.printf "    {\n";

     

       381
       381
       +
             Printf.printf "      \"id\": \"mbox1\",\n";

     

       382
       382
       +
             Printf.printf "      \"name\": \"Inbox\",\n";

     

       383
       383
       +
             Printf.printf "      \"role\": \"Inbox\",\n";

     

       384
       384
       +
             Printf.printf "      \"totalEmails\": 14,\n";

     

       385
       385
       +
             Printf.printf "      \"unreadEmails\": 3,\n";

     

       386
       386
       +
             Printf.printf "      \"recentEmails\": 5\n";

     

       387
       387
       +
             Printf.printf "    }\n";

     

       388
       388
       +
             Printf.printf "  ]\n";

     

       389
       389
       +
             Printf.printf "}\n");

     

       390
       390
       +
         

     

       391
       391
       +
         if query_mailbox <> None then

     

       392
       392
       +
           Printf.printf "\nQuerying emails in mailbox: %s\n" (Option.get query_mailbox);

     

       393
       393
       +
         

     

       394
       394
       +
         (* Since we're only type checking, we'll exit with success *)

     

       395
       395
       +
         0

     

       396
       396
       +
       

     

       397
       397
       +
       (* Command definition *)

     

       398
       398
       +
       let mailbox_cmd =

     

       399
       399
       +
         let doc = "explore and manage mailboxes using JMAP" in

     

       400
       400
       +
         let man = [

     

       401
       401
       +
           `S Manpage.s_description;

     

       402
       402
       +
           `P "Lists, creates, and analyzes email mailboxes using JMAP.";

     

       403
       403
       +
           `P "Demonstrates JMAP's mailbox query and management capabilities.";

     

       404
       404
       +
           `S Manpage.s_examples;

     

       405
       405
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --list";

     

       406
       406
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --stats --mailbox Inbox";

     

       407
       407
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --create \"Work/Project X\" --parent Work";

     

       408
       408
       +
         ] in

     

       409
       409
       +
         

     

       410
       410
       +
         let cmd = 

     

       411
       411
       +
           Cmd.v 

     

       412
       412
       +
             (Cmd.info "jmap-mailbox-explorer" ~version:"1.0" ~doc ~man)

     

       413
       413
       +
             Term.(const mailbox_command $ host_arg $ user_arg $ password_arg $ 

     

       414
       414
       +
                    list_arg $ stats_arg $ mailbox_arg $ create_arg $ 

     

       415
       415
       +
                    parent_arg $ query_mailbox_arg $ days_arg $ format_arg)

     

       416
       416
       +
         in

     

       417
       417
       +
         cmd

     

       418
       418
       +
       

     

       419
       419
       +
       (* Main entry point *)

     

       420
       420
       +
       let () = exit (Cmd.eval' mailbox_cmd)

+238

bin/jmap_push_listener.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_push_listener.ml - Monitor real-time changes via JMAP push notifications

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates JMAP's push notification capabilities for monitoring

     

       5
       5
       +
        * changes to emails, mailboxes, and other data in real-time.

     

       6
       6
       +
        *

     

       7
       7
       +
        * For step 2, we're only testing type checking. No implementations required.

     

       8
       8
       +
        *)

     

       9
       9
       +
       

     

       10
       10
       +
       open Cmdliner

     

       11
       11
       +
       

     

       12
       12
       +
       (** Push notification types to monitor **)

     

       13
       13
       +
       type monitor_types = {

     

       14
       14
       +
         emails : bool;

     

       15
       15
       +
         mailboxes : bool;

     

       16
       16
       +
         threads : bool;

     

       17
       17
       +
         identities : bool;

     

       18
       18
       +
         submissions : bool;

     

       19
       19
       +
         all : bool;

     

       20
       20
       +
       }

     

       21
       21
       +
       

     

       22
       22
       +
       (** Command-line arguments **)

     

       23
       23
       +
       

     

       24
       24
       +
       let host_arg =

     

       25
       25
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       26
       26
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       27
       27
       +
       

     

       28
       28
       +
       let user_arg =

     

       29
       29
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       30
       30
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       31
       31
       +
       

     

       32
       32
       +
       let password_arg =

     

       33
       33
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       34
       34
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       35
       35
       +
       

     

       36
       36
       +
       let monitor_emails_arg =

     

       37
       37
       +
         Arg.(value & flag & info ["emails"] 

     

       38
       38
       +
              ~doc:"Monitor email changes")

     

       39
       39
       +
       

     

       40
       40
       +
       let monitor_mailboxes_arg =

     

       41
       41
       +
         Arg.(value & flag & info ["mailboxes"] 

     

       42
       42
       +
              ~doc:"Monitor mailbox changes")

     

       43
       43
       +
       

     

       44
       44
       +
       let monitor_threads_arg =

     

       45
       45
       +
         Arg.(value & flag & info ["threads"] 

     

       46
       46
       +
              ~doc:"Monitor thread changes")

     

       47
       47
       +
       

     

       48
       48
       +
       let monitor_identities_arg =

     

       49
       49
       +
         Arg.(value & flag & info ["identities"] 

     

       50
       50
       +
              ~doc:"Monitor identity changes")

     

       51
       51
       +
       

     

       52
       52
       +
       let monitor_submissions_arg =

     

       53
       53
       +
         Arg.(value & flag & info ["submissions"] 

     

       54
       54
       +
              ~doc:"Monitor email submission changes")

     

       55
       55
       +
       

     

       56
       56
       +
       let monitor_all_arg =

     

       57
       57
       +
         Arg.(value & flag & info ["all"] 

     

       58
       58
       +
              ~doc:"Monitor all supported types")

     

       59
       59
       +
       

     

       60
       60
       +
       let verbose_arg =

     

       61
       61
       +
         Arg.(value & flag & info ["v"; "verbose"] 

     

       62
       62
       +
              ~doc:"Show detailed information about changes")

     

       63
       63
       +
       

     

       64
       64
       +
       let timeout_arg =

     

       65
       65
       +
         Arg.(value & opt int 300 & info ["t"; "timeout"] 

     

       66
       66
       +
              ~docv:"SECONDS" ~doc:"Timeout for push connections (default: 300)")

     

       67
       67
       +
       

     

       68
       68
       +
       (** Helper functions **)

     

       69
       69
       +
       

     

       70
       70
       +
       (* Format timestamp *)

     

       71
       71
       +
       let format_timestamp () =

     

       72
       72
       +
         let time = Unix.gettimeofday () in

     

       73
       73
       +
         let tm = Unix.localtime time in

     

       74
       74
       +
         Printf.sprintf "%04d-%02d-%02d %02d:%02d:%02d"

     

       75
       75
       +
           (tm.Unix.tm_year + 1900) (tm.Unix.tm_mon + 1) tm.Unix.tm_mday

     

       76
       76
       +
           tm.Unix.tm_hour tm.Unix.tm_min tm.Unix.tm_sec

     

       77
       77
       +
       

     

       78
       78
       +
       (* Print change notification *)

     

       79
       79
       +
       let print_change data_type change_type details verbose =

     

       80
       80
       +
         let timestamp = format_timestamp () in

     

       81
       81
       +
         Printf.printf "[%s] %s %s" timestamp data_type change_type;

     

       82
       82
       +
         if verbose && details <> "" then

     

       83
       83
       +
           Printf.printf ": %s" details;

     

       84
       84
       +
         Printf.printf "\n";

     

       85
       85
       +
         flush stdout

     

       86
       86
       +
       

     

       87
       87
       +
       (* Monitor using polling simulation *)

     

       88
       88
       +
       let monitor_changes _ctx _session _account_id monitor verbose timeout =

     

       89
       89
       +
         Printf.printf "Starting change monitoring (simulated)...\n\n";

     

       90
       90
       +
         

     

       91
       91
       +
         (* Types to monitor *)

     

       92
       92
       +
         let types = ref [] in

     

       93
       93
       +
         if monitor.emails || monitor.all then types := "Email" :: !types;

     

       94
       94
       +
         if monitor.mailboxes || monitor.all then types := "Mailbox" :: !types;

     

       95
       95
       +
         if monitor.threads || monitor.all then types := "Thread" :: !types;

     

       96
       96
       +
         if monitor.identities || monitor.all then types := "Identity" :: !types;

     

       97
       97
       +
         if monitor.submissions || monitor.all then types := "EmailSubmission" :: !types;

     

       98
       98
       +
         

     

       99
       99
       +
         Printf.printf "Monitoring: %s\n\n" (String.concat ", " !types);

     

       100
       100
       +
         

     

       101
       101
       +
         (* In a real implementation, we would:

     

       102
       102
       +
            1. Use EventSource or long polling

     

       103
       103
       +
            2. Track state changes per type

     

       104
       104
       +
            3. Fetch and display actual changes

     

       105
       105
       +
            

     

       106
       106
       +
            For this demo, we'll simulate monitoring *)

     

       107
       107
       +
         

     

       108
       108
       +
         let rec monitor_loop count =

     

       109
       109
       +
           (* Make a simple echo request to stay connected *)

     

       110
       110
       +
           let invocation = Jmap.Wire.Invocation.v

     

       111
       111
       +
             ~method_name:"Core/echo"

     

       112
       112
       +
             ~arguments:(`Assoc ["ping", `String "keepalive"]) 

     

       113
       113
       +
             ~method_call_id:"echo1"

     

       114
       114
       +
             () in

     

       115
       115
       +
             

     

       116
       116
       +
           let request = Jmap.Wire.Request.v

     

       117
       117
       +
             ~using:[Jmap.capability_core; Jmap_email.capability_mail]

     

       118
       118
       +
             ~method_calls:[invocation]

     

       119
       119
       +
             () in

     

       120
       120
       +
             

     

       121
       121
       +
           match Jmap_unix.request _ctx request with

     

       122
       122
       +
           | Ok _ ->

     

       123
       123
       +
               (* Simulate random changes for demonstration *)

     

       124
       124
       +
               if count mod 3 = 0 && !types <> [] then (

     

       125
       125
       +
                 let changed_type = List.nth !types (Random.int (List.length !types)) in

     

       126
       126
       +
                 let change_details = match changed_type with

     

       127
       127
       +
                   | "Email" -> "2 new, 1 updated"

     

       128
       128
       +
                   | "Mailbox" -> "1 updated (Inbox)"

     

       129
       129
       +
                   | "Thread" -> "3 updated"

     

       130
       130
       +
                   | "Identity" -> "settings changed"

     

       131
       131
       +
                   | "EmailSubmission" -> "1 sent"

     

       132
       132
       +
                   | _ -> "changed"

     

       133
       133
       +
                 in

     

       134
       134
       +
                 print_change changed_type "changed" change_details verbose

     

       135
       135
       +
               );

     

       136
       136
       +
               

     

       137
       137
       +
               (* Wait before next check *)

     

       138
       138
       +
               Unix.sleep 5;

     

       139
       139
       +
               

     

       140
       140
       +
               if count < timeout / 5 then

     

       141
       141
       +
                 monitor_loop (count + 1)

     

       142
       142
       +
               else (

     

       143
       143
       +
                 Printf.printf "\nMonitoring timeout reached.\n";

     

       144
       144
       +
                 0

     

       145
       145
       +
               )

     

       146
       146
       +
           | Error e ->

     

       147
       147
       +
               Printf.eprintf "Connection error: %s\n" (Jmap.Error.error_to_string e);

     

       148
       148
       +
               1

     

       149
       149
       +
         in

     

       150
       150
       +
         

     

       151
       151
       +
         monitor_loop 0

     

       152
       152
       +
       

     

       153
       153
       +
       (* Command implementation *)

     

       154
       154
       +
       let listen_command host user password emails mailboxes threads identities 

     

       155
       155
       +
                          submissions all verbose timeout : int =

     

       156
       156
       +
         Printf.printf "JMAP Push Listener\n";

     

       157
       157
       +
         Printf.printf "Server: %s\n" host;

     

       158
       158
       +
         Printf.printf "User: %s\n\n" user;

     

       159
       159
       +
         

     

       160
       160
       +
         (* Build monitor options *)

     

       161
       161
       +
         let monitor = {

     

       162
       162
       +
           emails;

     

       163
       163
       +
           mailboxes;

     

       164
       164
       +
           threads;

     

       165
       165
       +
           identities;

     

       166
       166
       +
           submissions;

     

       167
       167
       +
           all;

     

       168
       168
       +
         } in

     

       169
       169
       +
         

     

       170
       170
       +
         (* Check that at least one type is selected *)

     

       171
       171
       +
         if not (emails || mailboxes || threads || identities || submissions || all) then (

     

       172
       172
       +
           Printf.eprintf "Error: Must specify at least one type to monitor (or --all)\n";

     

       173
       173
       +
           exit 1

     

       174
       174
       +
         );

     

       175
       175
       +
         

     

       176
       176
       +
         (* Initialize random for simulation *)

     

       177
       177
       +
         Random.self_init ();

     

       178
       178
       +
         

     

       179
       179
       +
         (* Connect to server *)

     

       180
       180
       +
         let ctx = Jmap_unix.create_client () in

     

       181
       181
       +
         let result = Jmap_unix.quick_connect ~host ~username:user ~password in

     

       182
       182
       +
         

     

       183
       183
       +
         let (ctx, session) = match result with

     

       184
       184
       +
           | Ok (ctx, session) -> (ctx, session)

     

       185
       185
       +
           | Error e -> 

     

       186
       186
       +
               Printf.eprintf "Connection failed: %s\n" (Jmap.Error.error_to_string e);

     

       187
       187
       +
               exit 1

     

       188
       188
       +
         in

     

       189
       189
       +
         

     

       190
       190
       +
         (* Get the primary account ID *)

     

       191
       191
       +
         let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       192
       192
       +
           | Ok id -> id

     

       193
       193
       +
           | Error e -> 

     

       194
       194
       +
               Printf.eprintf "No mail account found: %s\n" (Jmap.Error.error_to_string e);

     

       195
       195
       +
               exit 1

     

       196
       196
       +
         in

     

       197
       197
       +
         

     

       198
       198
       +
         (* Check EventSource URL availability *)

     

       199
       199
       +
         let event_source_url = Jmap.Session.Session.event_source_url session in

     

       200
       200
       +
         if Uri.to_string event_source_url <> "" then

     

       201
       201
       +
           Printf.printf "Note: Server supports EventSource at: %s\n\n" (Uri.to_string event_source_url)

     

       202
       202
       +
         else

     

       203
       203
       +
           Printf.printf "Note: Server doesn't advertise EventSource support\n\n";

     

       204
       204
       +
         

     

       205
       205
       +
         (* Monitor for changes *)

     

       206
       206
       +
         monitor_changes ctx session account_id monitor verbose timeout

     

       207
       207
       +
       

     

       208
       208
       +
       (* Command definition *)

     

       209
       209
       +
       let listen_cmd =

     

       210
       210
       +
         let doc = "monitor real-time changes via JMAP push notifications" in

     

       211
       211
       +
         let man = [

     

       212
       212
       +
           `S Manpage.s_description;

     

       213
       213
       +
           `P "Monitor real-time changes to JMAP data using push notifications.";

     

       214
       214
       +
           `P "Supports both EventSource and long-polling methods.";

     

       215
       215
       +
           `P "Shows when emails, mailboxes, threads, and other data change.";

     

       216
       216
       +
           `S Manpage.s_examples;

     

       217
       217
       +
           `P "Monitor all changes:";

     

       218
       218
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --all";

     

       219
       219
       +
           `P "";

     

       220
       220
       +
           `P "Monitor only emails and mailboxes with details:";

     

       221
       221
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --emails --mailboxes -v";

     

       222
       222
       +
           `P "";

     

       223
       223
       +
           `P "Monitor with custom timeout:";

     

       224
       224
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --all -t 600";

     

       225
       225
       +
         ] in

     

       226
       226
       +
         

     

       227
       227
       +
         let cmd =

     

       228
       228
       +
           Cmd.v

     

       229
       229
       +
             (Cmd.info "jmap-push-listener" ~version:"1.0" ~doc ~man)

     

       230
       230
       +
             Term.(const listen_command $ host_arg $ user_arg $ password_arg $ 

     

       231
       231
       +
                   monitor_emails_arg $ monitor_mailboxes_arg $ monitor_threads_arg $

     

       232
       232
       +
                   monitor_identities_arg $ monitor_submissions_arg $ monitor_all_arg $

     

       233
       233
       +
                   verbose_arg $ timeout_arg)

     

       234
       234
       +
         in

     

       235
       235
       +
         cmd

     

       236
       236
       +
       

     

       237
       237
       +
       (* Main entry point *)

     

       238
       238
       +
       let () = exit (Cmd.eval' listen_cmd)

+533

bin/jmap_thread_analyzer.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_thread_analyzer.ml - A tool for analyzing email threads using JMAP

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates the thread-related capabilities of JMAP,

     

       5
       5
       +
        * allowing visualization and analysis of conversation threads.

     

       6
       6
       +
        *)

     

       7
       7
       +
       

     

       8
       8
       +
       open Cmdliner

     

       9
       9
       +
       (* Using standard OCaml, no Lwt *)

     

       10
       10
       +
       

     

       11
       11
       +
       (* JMAP imports *)

     

       12
       12
       +
       open Jmap

     

       13
       13
       +
       open Jmap.Types

     

       14
       14
       +
       open Jmap.Wire

     

       15
       15
       +
       open Jmap.Methods

     

       16
       16
       +
       open Jmap_email

     

       17
       17
       +
       (* For step 2, we're only testing type checking. No implementations required. *)

     

       18
       18
       +
       

     

       19
       19
       +
       (* Dummy Unix module for type checking *)

     

       20
       20
       +
       module Unix = struct

     

       21
       21
       +
         type tm = {

     

       22
       22
       +
           tm_sec : int;

     

       23
       23
       +
           tm_min : int;

     

       24
       24
       +
           tm_hour : int;

     

       25
       25
       +
           tm_mday : int;

     

       26
       26
       +
           tm_mon : int;

     

       27
       27
       +
           tm_year : int;

     

       28
       28
       +
           tm_wday : int;

     

       29
       29
       +
           tm_yday : int;

     

       30
       30
       +
           tm_isdst : bool

     

       31
       31
       +
         }

     

       32
       32
       +
         

     

       33
       33
       +
         let time () = 0.0

     

       34
       34
       +
         let gettimeofday () = 0.0

     

       35
       35
       +
         let mktime tm = (0.0, tm)

     

       36
       36
       +
         let gmtime _time = {

     

       37
       37
       +
           tm_sec = 0; tm_min = 0; tm_hour = 0;

     

       38
       38
       +
           tm_mday = 1; tm_mon = 0; tm_year = 120;

     

       39
       39
       +
           tm_wday = 0; tm_yday = 0; tm_isdst = false;

     

       40
       40
       +
         }

     

       41
       41
       +
         

     

       42
       42
       +
         (* JMAP connection function - would be in a real implementation *)

     

       43
       43
       +
         let connect ~host ~username ~password ?auth_method () =

     

       44
       44
       +
           failwith "Not implemented"

     

       45
       45
       +
       end

     

       46
       46
       +
       

     

       47
       47
       +
       (* Dummy ISO8601 module *)

     

       48
       48
       +
       module ISO8601 = struct

     

       49
       49
       +
         let string_of_datetime _tm = "2023-01-01T00:00:00Z"

     

       50
       50
       +
       end

     

       51
       51
       +
       

     

       52
       52
       +
       (** Thread analyzer arguments *)

     

       53
       53
       +
       type thread_analyzer_args = {

     

       54
       54
       +
         thread_id : string option;

     

       55
       55
       +
         search : string option;

     

       56
       56
       +
         limit : int;

     

       57
       57
       +
         days : int;

     

       58
       58
       +
         subject : string option;

     

       59
       59
       +
         participants : string list;

     

       60
       60
       +
         format : [`Summary | `Detailed | `Timeline | `Graph];

     

       61
       61
       +
         include_body : bool;

     

       62
       62
       +
       }

     

       63
       63
       +
       

     

       64
       64
       +
       (* Email filter helpers - stub implementations for type checking *)

     

       65
       65
       +
       module Email_filter = struct

     

       66
       66
       +
         let create_fulltext_filter text = Filter.condition (`Assoc [("text", `String text)])

     

       67
       67
       +
         let subject subj = Filter.condition (`Assoc [("subject", `String subj)])

     

       68
       68
       +
         let from email = Filter.condition (`Assoc [("from", `String email)])

     

       69
       69
       +
         let after date = Filter.condition (`Assoc [("receivedAt", `Assoc [("after", `Float date)])])

     

       70
       70
       +
         let before date = Filter.condition (`Assoc [("receivedAt", `Assoc [("before", `Float date)])])

     

       71
       71
       +
         let has_attachment () = Filter.condition (`Assoc [("hasAttachment", `Bool true)])

     

       72
       72
       +
         let unread () = Filter.condition (`Assoc [("isUnread", `Bool true)])

     

       73
       73
       +
         let in_mailbox id = Filter.condition (`Assoc [("inMailbox", `String id)])

     

       74
       74
       +
         let to_ email = Filter.condition (`Assoc [("to", `String email)])

     

       75
       75
       +
       end

     

       76
       76
       +
       

     

       77
       77
       +
       (* Thread module stub *)

     

       78
       78
       +
       module Thread = struct

     

       79
       79
       +
         type t = {

     

       80
       80
       +
           id : string;

     

       81
       81
       +
           email_ids : string list;

     

       82
       82
       +
         }

     

       83
       83
       +
         

     

       84
       84
       +
         let id thread = thread.id

     

       85
       85
       +
         let email_ids thread = thread.email_ids

     

       86
       86
       +
       end

     

       87
       87
       +
       

     

       88
       88
       +
       (** Command-line arguments **)

     

       89
       89
       +
       

     

       90
       90
       +
       let host_arg =

     

       91
       91
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       92
       92
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       93
       93
       +
       

     

       94
       94
       +
       let user_arg =

     

       95
       95
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       96
       96
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       97
       97
       +
       

     

       98
       98
       +
       let password_arg =

     

       99
       99
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       100
       100
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       101
       101
       +
       

     

       102
       102
       +
       let thread_id_arg =

     

       103
       103
       +
         Arg.(value & opt (some string) None & info ["t"; "thread"] 

     

       104
       104
       +
              ~docv:"THREAD_ID" ~doc:"Analyze specific thread by ID")

     

       105
       105
       +
       

     

       106
       106
       +
       let search_arg =

     

       107
       107
       +
         Arg.(value & opt (some string) None & info ["search"] 

     

       108
       108
       +
              ~docv:"QUERY" ~doc:"Search for threads containing text")

     

       109
       109
       +
       

     

       110
       110
       +
       let limit_arg =

     

       111
       111
       +
         Arg.(value & opt int 10 & info ["limit"] 

     

       112
       112
       +
              ~docv:"N" ~doc:"Maximum number of threads to display")

     

       113
       113
       +
       

     

       114
       114
       +
       let days_arg =

     

       115
       115
       +
         Arg.(value & opt int 30 & info ["days"] 

     

       116
       116
       +
              ~docv:"DAYS" ~doc:"Limit to threads from the past N days")

     

       117
       117
       +
       

     

       118
       118
       +
       let subject_arg =

     

       119
       119
       +
         Arg.(value & opt (some string) None & info ["subject"] 

     

       120
       120
       +
              ~docv:"SUBJECT" ~doc:"Search threads by subject")

     

       121
       121
       +
       

     

       122
       122
       +
       let participant_arg =

     

       123
       123
       +
         Arg.(value & opt_all string [] & info ["participant"] 

     

       124
       124
       +
              ~docv:"EMAIL" ~doc:"Filter by participant email")

     

       125
       125
       +
       

     

       126
       126
       +
       let format_arg =

     

       127
       127
       +
         Arg.(value & opt (enum [

     

       128
       128
       +
           "summary", `Summary;

     

       129
       129
       +
           "detailed", `Detailed;

     

       130
       130
       +
           "timeline", `Timeline;

     

       131
       131
       +
           "graph", `Graph;

     

       132
       132
       +
         ]) `Summary & info ["format"] ~docv:"FORMAT" ~doc:"Output format")

     

       133
       133
       +
       

     

       134
       134
       +
       let include_body_arg =

     

       135
       135
       +
         Arg.(value & flag & info ["include-body"] ~doc:"Include message bodies in output")

     

       136
       136
       +
       

     

       137
       137
       +
       (** Thread Analysis Functionality **)

     

       138
       138
       +
       

     

       139
       139
       +
       (* Calculate days ago from a date *)

     

       140
       140
       +
       let days_ago date =

     

       141
       141
       +
         let now = Unix.gettimeofday() in

     

       142
       142
       +
         int_of_float ((now -. date) /. 86400.0)

     

       143
       143
       +
       

     

       144
       144
       +
       (* Parse out email addresses from a participant string - simple version *)

     

       145
       145
       +
       let extract_email participant =

     

       146
       146
       +
         if String.contains participant '@' then participant

     

       147
       147
       +
         else participant ^ "@example.com" (* Default domain if none provided *)

     

       148
       148
       +
       

     

       149
       149
       +
       (* Create filter for thread queries *)

     

       150
       150
       +
       let create_thread_filter args =

     

       151
       151
       +
         let open Email_filter in

     

       152
       152
       +
         let filters = [] in

     

       153
       153
       +
         

     

       154
       154
       +
         (* Add search text condition *)

     

       155
       155
       +
         let filters = match args.search with

     

       156
       156
       +
           | None -> filters

     

       157
       157
       +
           | Some text -> create_fulltext_filter text :: filters

     

       158
       158
       +
         in

     

       159
       159
       +
         

     

       160
       160
       +
         (* Add subject condition *)

     

       161
       161
       +
         let filters = match args.subject with

     

       162
       162
       +
           | None -> filters

     

       163
       163
       +
           | Some subj -> Email_filter.subject subj :: filters

     

       164
       164
       +
         in

     

       165
       165
       +
         

     

       166
       166
       +
         (* Add date range based on days *)

     

       167
       167
       +
         let filters =

     

       168
       168
       +
           if args.days > 0 then

     

       169
       169
       +
             let now = Unix.gettimeofday() in

     

       170
       170
       +
             let past = now -. (float_of_int args.days *. 86400.0) in

     

       171
       171
       +
             after past :: filters

     

       172
       172
       +
           else

     

       173
       173
       +
             filters

     

       174
       174
       +
         in

     

       175
       175
       +
         

     

       176
       176
       +
         (* Add participant filters *)

     

       177
       177
       +
         let filters =

     

       178
       178
       +
           List.fold_left (fun acc participant ->

     

       179
       179
       +
             let email = extract_email participant in

     

       180
       180
       +
             (* This would need more complex logic to check both from and to fields *)

     

       181
       181
       +
             from email :: acc

     

       182
       182
       +
           ) filters args.participants

     

       183
       183
       +
         in

     

       184
       184
       +
         

     

       185
       185
       +
         (* Combine all filters with AND *)

     

       186
       186
       +
         match filters with

     

       187
       187
       +
         | [] -> Filter.condition (`Assoc [])  (* Empty filter *)

     

       188
       188
       +
         | [f] -> f

     

       189
       189
       +
         | filters -> Filter.and_ filters

     

       190
       190
       +
       

     

       191
       191
       +
       (* Display thread in requested format *)

     

       192
       192
       +
       let display_thread thread emails format include_body snippet_map =

     

       193
       193
       +
         let thread_id = Thread.id thread in

     

       194
       194
       +
         let email_count = List.length (Thread.email_ids thread) in

     

       195
       195
       +
         

     

       196
       196
       +
         (* Sort emails by date for proper display order *)

     

       197
       197
       +
         let sorted_emails = List.sort (fun e1 e2 ->

     

       198
       198
       +
           let date1 = Option.value (Types.Email.received_at e1) ~default:0.0 in

     

       199
       199
       +
           let date2 = Option.value (Types.Email.received_at e2) ~default:0.0 in

     

       200
       200
       +
           compare date1 date2

     

       201
       201
       +
         ) emails in

     

       202
       202
       +
         

     

       203
       203
       +
         (* Get a snippet for an email if available *)

     

       204
       204
       +
         let get_snippet email_id =

     

       205
       205
       +
           match Hashtbl.find_opt snippet_map email_id with

     

       206
       206
       +
           | Some snippet -> snippet

     

       207
       207
       +
           | None -> "(No preview available)"

     

       208
       208
       +
         in

     

       209
       209
       +
         

     

       210
       210
       +
         match format with

     

       211
       211
       +
         | `Summary ->

     

       212
       212
       +
             Printf.printf "Thread: %s (%d messages)\n\n" thread_id email_count;

     

       213
       213
       +
             

     

       214
       214
       +
             (* Print first email subject as thread subject *)

     

       215
       215
       +
             (match sorted_emails with

     

       216
       216
       +
             | first :: _ ->

     

       217
       217
       +
                 let subject = Option.value (Types.Email.subject first) ~default:"(No subject)" in

     

       218
       218
       +
                 Printf.printf "Subject: %s\n\n" subject

     

       219
       219
       +
             | [] -> Printf.printf "No emails available\n\n");

     

       220
       220
       +
             

     

       221
       221
       +
             (* List participants *)

     

       222
       222
       +
             let participants = sorted_emails |> List.fold_left (fun acc email ->

     

       223
       223
       +
               let from_list = Option.value (Types.Email.from email) ~default:[] in

     

       224
       224
       +
               from_list |> List.fold_left (fun acc addr ->

     

       225
       225
       +
                 let email = Types.Email_address.email addr in

     

       226
       226
       +
                 if not (List.mem email acc) then email :: acc else acc

     

       227
       227
       +
               ) acc

     

       228
       228
       +
             ) [] in

     

       229
       229
       +
             

     

       230
       230
       +
             Printf.printf "Participants: %s\n\n" (String.concat ", " participants);

     

       231
       231
       +
             

     

       232
       232
       +
             (* Show timespan *)

     

       233
       233
       +
             (match sorted_emails with

     

       234
       234
       +
             | first :: _ :: _ :: _ -> (* At least a few messages *)

     

       235
       235
       +
                 let first_date = Option.value (Types.Email.received_at first) ~default:0.0 in

     

       236
       236
       +
                 let last_date = Option.value (Types.Email.received_at (List.hd (List.rev sorted_emails))) ~default:0.0 in

     

       237
       237
       +
                 let datetime_str = ISO8601.string_of_datetime (Unix.gmtime first_date) in

     

       238
       238
       +
                 let first_str = String.sub datetime_str 0 (min 19 (String.length datetime_str)) in

     

       239
       239
       +
                 let datetime_str = ISO8601.string_of_datetime (Unix.gmtime last_date) in

     

       240
       240
       +
                 let last_str = String.sub datetime_str 0 (min 19 (String.length datetime_str)) in

     

       241
       241
       +
                 let duration_days = int_of_float ((last_date -. first_date) /. 86400.0) in

     

       242
       242
       +
                 Printf.printf "Timespan: %s to %s (%d days)\n\n" first_str last_str duration_days

     

       243
       243
       +
             | _ -> ());

     

       244
       244
       +
             

     

       245
       245
       +
             (* Show message count by participant *)

     

       246
       246
       +
             let message_counts = sorted_emails |> List.fold_left (fun acc email ->

     

       247
       247
       +
               let from_list = Option.value (Types.Email.from email) ~default:[] in

     

       248
       248
       +
               match from_list with

     

       249
       249
       +
               | addr :: _ ->

     

       250
       250
       +
                   let email = Types.Email_address.email addr in

     

       251
       251
       +
                   let count = try Hashtbl.find acc email with Not_found -> 0 in

     

       252
       252
       +
                   Hashtbl.replace acc email (count + 1);

     

       253
       253
       +
                   acc

     

       254
       254
       +
               | [] -> acc

     

       255
       255
       +
             ) (Hashtbl.create 10) in

     

       256
       256
       +
             

     

       257
       257
       +
             Printf.printf "Messages per participant:\n";

     

       258
       258
       +
             Hashtbl.iter (fun email count ->

     

       259
       259
       +
               Printf.printf "  %s: %d messages\n" email count

     

       260
       260
       +
             ) message_counts;

     

       261
       261
       +
             Printf.printf "\n"

     

       262
       262
       +
         

     

       263
       263
       +
         | `Detailed ->

     

       264
       264
       +
             Printf.printf "Thread: %s (%d messages)\n\n" thread_id email_count;

     

       265
       265
       +
             

     

       266
       266
       +
             (* Print detailed information for each email *)

     

       267
       267
       +
             sorted_emails |> List.iteri (fun i email ->

     

       268
       268
       +
               let id = Option.value (Types.Email.id email) ~default:"(unknown)" in

     

       269
       269
       +
               let subject = Option.value (Types.Email.subject email) ~default:"(No subject)" in

     

       270
       270
       +
               

     

       271
       271
       +
               let from_list = Option.value (Types.Email.from email) ~default:[] in

     

       272
       272
       +
               let from = match from_list with

     

       273
       273
       +
                 | addr :: _ -> Types.Email_address.email addr

     

       274
       274
       +
                 | [] -> "(unknown)"

     

       275
       275
       +
               in

     

       276
       276
       +
               

     

       277
       277
       +
               let date = match Types.Email.received_at email with

     

       278
       278
       +
                 | Some d ->

     

       279
       279
       +
                     let datetime_str = ISO8601.string_of_datetime (Unix.gmtime d) in

     

       280
       280
       +
                     String.sub datetime_str 0 (min 19 (String.length datetime_str))

     

       281
       281
       +
                 | None -> "(unknown)"

     

       282
       282
       +
               in

     

       283
       283
       +
               

     

       284
       284
       +
               let days = match Types.Email.received_at email with

     

       285
       285
       +
                 | Some d -> Printf.sprintf " (%d days ago)" (days_ago d)

     

       286
       286
       +
                 | None -> ""

     

       287
       287
       +
               in

     

       288
       288
       +
               

     

       289
       289
       +
               Printf.printf "Email %d of %d:\n" (i+1) email_count;

     

       290
       290
       +
               Printf.printf "  ID:      %s\n" id;

     

       291
       291
       +
               Printf.printf "  Subject: %s\n" subject;

     

       292
       292
       +
               Printf.printf "  From:    %s\n" from;

     

       293
       293
       +
               Printf.printf "  Date:    %s%s\n" date days;

     

       294
       294
       +
               

     

       295
       295
       +
               let keywords = match Types.Email.keywords email with

     

       296
       296
       +
                 | Some kw -> Types.Keywords.custom_keywords kw |> String.concat ", "

     

       297
       297
       +
                 | None -> "(none)"

     

       298
       298
       +
               in

     

       299
       299
       +
               if keywords <> "(none)" then

     

       300
       300
       +
                 Printf.printf "  Flags:   %s\n" keywords;

     

       301
       301
       +
               

     

       302
       302
       +
               (* Show preview from snippet if available *)

     

       303
       303
       +
               Printf.printf "  Snippet: %s\n" (get_snippet id);

     

       304
       304
       +
               

     

       305
       305
       +
               (* Show message body if requested *)

     

       306
       306
       +
               if include_body then

     

       307
       307
       +
                 match Types.Email.text_body email with

     

       308
       308
       +
                 | Some parts when parts <> [] ->

     

       309
       309
       +
                     let first_part = List.hd parts in

     

       310
       310
       +
                     Printf.printf "  Body: %s\n" "(body content would be here in real implementation)";

     

       311
       311
       +
                 | _ -> ();

     

       312
       312
       +
               

     

       313
       313
       +
               Printf.printf "\n"

     

       314
       314
       +
             )

     

       315
       315
       +
         

     

       316
       316
       +
         | `Timeline ->

     

       317
       317
       +
             Printf.printf "Timeline for Thread: %s\n\n" thread_id;

     

       318
       318
       +
             

     

       319
       319
       +
             (* Get the first email's subject as thread subject *)

     

       320
       320
       +
             (match sorted_emails with

     

       321
       321
       +
             | first :: _ ->

     

       322
       322
       +
                 let subject = Option.value (Types.Email.subject first) ~default:"(No subject)" in

     

       323
       323
       +
                 Printf.printf "Subject: %s\n\n" subject

     

       324
       324
       +
             | [] -> Printf.printf "No emails available\n\n");

     

       325
       325
       +
             

     

       326
       326
       +
             (* Create a timeline visualization *)

     

       327
       327
       +
             if sorted_emails = [] then

     

       328
       328
       +
               Printf.printf "No emails to display\n"

     

       329
       329
       +
             else

     

       330
       330
       +
               let first_email = List.hd sorted_emails in

     

       331
       331
       +
               let last_email = List.hd (List.rev sorted_emails) in

     

       332
       332
       +
               

     

       333
       333
       +
               let first_date = Option.value (Types.Email.received_at first_email) ~default:0.0 in

     

       334
       334
       +
               let last_date = Option.value (Types.Email.received_at last_email) ~default:0.0 in

     

       335
       335
       +
               

     

       336
       336
       +
               let total_duration = max 1.0 (last_date -. first_date) in

     

       337
       337
       +
               let timeline_width = 50 in

     

       338
       338
       +
               

     

       339
       339
       +
               let datetime_str = ISO8601.string_of_datetime (Unix.gmtime first_date) in

     

       340
       340
       +
               let start_str = String.sub datetime_str 0 (min 19 (String.length datetime_str)) in

     

       341
       341
       +
               Printf.printf "Start date: %s\n" start_str;

     

       342
       342
       +
               

     

       343
       343
       +
               let datetime_str = ISO8601.string_of_datetime (Unix.gmtime last_date) in

     

       344
       344
       +
               let end_str = String.sub datetime_str 0 (min 19 (String.length datetime_str)) in

     

       345
       345
       +
               Printf.printf "End date:   %s\n\n" end_str;

     

       346
       346
       +
               

     

       347
       347
       +
               Printf.printf "Timeline: [%s]\n" (String.make timeline_width '-');

     

       348
       348
       +
               

     

       349
       349
       +
               sorted_emails |> List.iteri (fun i email ->

     

       350
       350
       +
                 let date = Option.value (Types.Email.received_at email) ~default:0.0 in

     

       351
       351
       +
                 let position = int_of_float (float_of_int timeline_width *. (date -. first_date) /. total_duration) in

     

       352
       352
       +
                 

     

       353
       353
       +
                 let from_list = Option.value (Types.Email.from email) ~default:[] in

     

       354
       354
       +
                 let from = match from_list with

     

       355
       355
       +
                   | addr :: _ -> Types.Email_address.email addr

     

       356
       356
       +
                   | [] -> "(unknown)"

     

       357
       357
       +
                 in

     

       358
       358
       +
                 

     

       359
       359
       +
                 let datetime_str = ISO8601.string_of_datetime (Unix.gmtime date) in

     

       360
       360
       +
                 let date_str = String.sub datetime_str 0 (min 19 (String.length datetime_str)) in

     

       361
       361
       +
                 

     

       362
       362
       +
                 let marker = String.make timeline_width ' ' |> String.mapi (fun j c ->

     

       363
       363
       +
                   if j = position then '*' else if j < position then ' ' else c

     

       364
       364
       +
                 ) in

     

       365
       365
       +
                 

     

       366
       366
       +
                 Printf.printf "%s [%s] %s: %s\n" date_str marker from (get_snippet (Option.value (Types.Email.id email) ~default:""))

     

       367
       367
       +
               );

     

       368
       368
       +
               

     

       369
       369
       +
               Printf.printf "\n"

     

       370
       370
       +
         

     

       371
       371
       +
         | `Graph ->

     

       372
       372
       +
             Printf.printf "Thread Graph for: %s\n\n" thread_id;

     

       373
       373
       +
             

     

       374
       374
       +
             (* In a real implementation, this would build a proper thread graph based on

     

       375
       375
       +
                In-Reply-To and References headers. For this demo, we'll just show a simple tree. *)

     

       376
       376
       +
             

     

       377
       377
       +
             (* Get the first email's subject as thread subject *)

     

       378
       378
       +
             (match sorted_emails with

     

       379
       379
       +
             | first :: _ ->

     

       380
       380
       +
                 let subject = Option.value (Types.Email.subject first) ~default:"(No subject)" in

     

       381
       381
       +
                 Printf.printf "Subject: %s\n\n" subject

     

       382
       382
       +
             | [] -> Printf.printf "No emails available\n\n");

     

       383
       383
       +
             

     

       384
       384
       +
             (* Create a simple thread tree visualization *)

     

       385
       385
       +
             if sorted_emails = [] then

     

       386
       386
       +
               Printf.printf "No emails to display\n"

     

       387
       387
       +
             else

     

       388
       388
       +
               let indent level = String.make (level * 2) ' ' in

     

       389
       389
       +
               

     

       390
       390
       +
               (* Very simplified threading model - in a real implementation, 

     

       391
       391
       +
                  this would use In-Reply-To and References headers *)

     

       392
       392
       +
               sorted_emails |> List.iteri (fun i email ->

     

       393
       393
       +
                 let level = min i 4 in  (* Simplified nesting - would be based on real reply chain *)

     

       394
       394
       +
                 

     

       395
       395
       +
                 let id = Option.value (Types.Email.id email) ~default:"(unknown)" in

     

       396
       396
       +
                 

     

       397
       397
       +
                 let from_list = Option.value (Types.Email.from email) ~default:[] in

     

       398
       398
       +
                 let from = match from_list with

     

       399
       399
       +
                   | addr :: _ -> Types.Email_address.email addr

     

       400
       400
       +
                   | [] -> "(unknown)"

     

       401
       401
       +
                 in

     

       402
       402
       +
                 

     

       403
       403
       +
                 let date = match Types.Email.received_at email with

     

       404
       404
       +
                   | Some d -> 

     

       405
       405
       +
                       let datetime_str = ISO8601.string_of_datetime (Unix.gmtime d) in

     

       406
       406
       +
                       String.sub datetime_str 0 (min 19 (String.length datetime_str))

     

       407
       407
       +
                   | None -> "(unknown)"

     

       408
       408
       +
                 in

     

       409
       409
       +
                 

     

       410
       410
       +
                 Printf.printf "%s%s [%s] %s\n" 

     

       411
       411
       +
                   (indent level) 

     

       412
       412
       +
                   (if level = 0 then "+" else if level = 1 then "|-" else "|--")

     

       413
       413
       +
                   date from;

     

       414
       414
       +
                 

     

       415
       415
       +
                 Printf.printf "%s%s\n" (indent (level + 4)) (get_snippet id);

     

       416
       416
       +
               );

     

       417
       417
       +
               

     

       418
       418
       +
               Printf.printf "\n"

     

       419
       419
       +
       

     

       420
       420
       +
       (* Command implementation *)

     

       421
       421
       +
       let thread_command host user password thread_id search limit days subject 

     

       422
       422
       +
                           participant format include_body : int =

     

       423
       423
       +
         (* Pack arguments into a record for easier passing *)

     

       424
       424
       +
         let args : thread_analyzer_args = {

     

       425
       425
       +
           thread_id; search; limit; days; subject; 

     

       426
       426
       +
           participants = participant; format; include_body

     

       427
       427
       +
         } in

     

       428
       428
       +
         

     

       429
       429
       +
         (* Main workflow would be implemented here using the JMAP library *)

     

       430
       430
       +
         Printf.printf "JMAP Thread Analyzer\n";

     

       431
       431
       +
         Printf.printf "Server: %s\n" host;

     

       432
       432
       +
         Printf.printf "User: %s\n\n" user;

     

       433
       433
       +
         

     

       434
       434
       +
         (* This is where the actual JMAP calls would happen, like:

     

       435
       435
       +
         

     

       436
       436
       +
         let analyze_threads () =

     

       437
       437
       +
           let* (ctx, session) = Jmap.Unix.connect 

     

       438
       438
       +
             ~host ~username:user ~password 

     

       439
       439
       +
             ~auth_method:(Jmap.Unix.Basic(user, password)) () in

     

       440
       440
       +
           

     

       441
       441
       +
           (* Get primary account ID *)

     

       442
       442
       +
           let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       443
       443
       +
             | Ok id -> id

     

       444
       444
       +
             | Error _ -> failwith "No mail account found"

     

       445
       445
       +
           in

     

       446
       446
       +
           

     

       447
       447
       +
           match args.thread_id with

     

       448
       448
       +
           | Some id ->

     

       449
       449
       +
               (* Analyze a specific thread by ID *)

     

       450
       450
       +
               let* thread_result = Thread.get ctx

     

       451
       451
       +
                 ~account_id

     

       452
       452
       +
                 ~ids:[id] in

     

       453
       453
       +
               

     

       454
       454
       +
               (* Handle thread fetch result *)

     

       455
       455
       +
               ...

     

       456
       456
       +
               

     

       457
       457
       +
           | None ->

     

       458
       458
       +
               (* Search for threads based on criteria *)

     

       459
       459
       +
               let filter = create_thread_filter args in

     

       460
       460
       +
               

     

       461
       461
       +
               (* Email/query to find emails matching criteria *)

     

       462
       462
       +
               let* query_result = Email.query ctx

     

       463
       463
       +
                 ~account_id

     

       464
       464
       +
                 ~filter

     

       465
       465
       +
                 ~sort:[Email_sort.received_newest_first ()]

     

       466
       466
       +
                 ~collapse_threads:true

     

       467
       467
       +
                 ~limit:args.limit in

     

       468
       468
       +
               

     

       469
       469
       +
               (* Process query results to get thread IDs *)

     

       470
       470
       +
               ...

     

       471
       471
       +
         *)

     

       472
       472
       +
         

     

       473
       473
       +
         (match thread_id with

     

       474
       474
       +
         | Some id ->

     

       475
       475
       +
             Printf.printf "Analyzing thread: %s\n\n" id;

     

       476
       476
       +
             

     

       477
       477
       +
             (* Simulate a thread with some emails *)

     

       478
       478
       +
             let emails = 5 in

     

       479
       479
       +
             Printf.printf "Thread contains %d emails\n" emails;

     

       480
       480
       +
             

     

       481
       481
       +
             (* In a real implementation, we would display the actual thread data here *)

     

       482
       482
       +
             Printf.printf "Example output format would show thread details here\n"

     

       483
       483
       +
         

     

       484
       484
       +
         | None ->

     

       485
       485
       +
             if search <> None then

     

       486
       486
       +
               Printf.printf "Searching for threads containing: %s\n" (Option.get search)

     

       487
       487
       +
             else if subject <> None then

     

       488
       488
       +
               Printf.printf "Searching for threads with subject: %s\n" (Option.get subject)

     

       489
       489
       +
             else

     

       490
       490
       +
               Printf.printf "No specific thread or search criteria provided\n");

     

       491
       491
       +
             

     

       492
       492
       +
             if participant <> [] then

     

       493
       493
       +
               Printf.printf "Filtering to threads involving: %s\n" 

     

       494
       494
       +
                 (String.concat ", " participant);

     

       495
       495
       +
             

     

       496
       496
       +
             Printf.printf "Looking at threads from the past %d days\n" days;

     

       497
       497
       +
             Printf.printf "Showing up to %d threads\n\n" limit;

     

       498
       498
       +
             

     

       499
       499
       +
             (* Simulate finding some threads *)

     

       500
       500
       +
             let thread_count = min limit 3 in

     

       501
       501
       +
             Printf.printf "Found %d matching threads\n\n" thread_count;

     

       502
       502
       +
             

     

       503
       503
       +
             (* In a real implementation, we would display the actual threads here *)

     

       504
       504
       +
             for i = 1 to thread_count do

     

       505
       505
       +
               Printf.printf "Thread %d would be displayed here\n\n" i

     

       506
       506
       +
             done;

     

       507
       507
       +
         

     

       508
       508
       +
         (* Since we're only type checking, we'll exit with success *)

     

       509
       509
       +
         0

     

       510
       510
       +
       

     

       511
       511
       +
       (* Command definition *)

     

       512
       512
       +
       let thread_cmd =

     

       513
       513
       +
         let doc = "analyze email threads using JMAP" in

     

       514
       514
       +
         let man = [

     

       515
       515
       +
           `S Manpage.s_description;

     

       516
       516
       +
           `P "Analyzes email threads with detailed visualization options.";

     

       517
       517
       +
           `P "Demonstrates how to work with JMAP's thread capabilities.";

     

       518
       518
       +
           `S Manpage.s_examples;

     

       519
       519
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 -t thread123";

     

       520
       520
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --search \"project update\" --format timeline";

     

       521
       521
       +
         ] in

     

       522
       522
       +
         

     

       523
       523
       +
         let cmd =

     

       524
       524
       +
           Cmd.v

     

       525
       525
       +
             (Cmd.info "jmap-thread-analyzer" ~version:"1.0" ~doc ~man)

     

       526
       526
       +
             Term.(const thread_command $ host_arg $ user_arg $ password_arg $ 

     

       527
       527
       +
                   thread_id_arg $ search_arg $ limit_arg $ days_arg $ 

     

       528
       528
       +
                   subject_arg $ participant_arg $ format_arg $ include_body_arg)

     

       529
       529
       +
         in

     

       530
       530
       +
         cmd

     

       531
       531
       +
       

     

       532
       532
       +
       (* Main entry point *)

     

       533
       533
       +
       let () = exit (Cmd.eval' thread_cmd)

+406

bin/jmap_vacation_manager.ml

···

       1
       1
       +
       (*

     

       2
       2
       +
        * jmap_vacation_manager.ml - Manage vacation/out-of-office auto-responses

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary demonstrates JMAP's vacation response capabilities for setting

     

       5
       5
       +
        * up and managing automatic email responses.

     

       6
       6
       +
        *

     

       7
       7
       +
        * For step 2, we're only testing type checking. No implementations required.

     

       8
       8
       +
        *)

     

       9
       9
       +
       

     

       10
       10
       +
       open Cmdliner

     

       11
       11
       +
       

     

       12
       12
       +
       (** Vacation response actions **)

     

       13
       13
       +
       type vacation_action = 

     

       14
       14
       +
         | Show

     

       15
       15
       +
         | Enable of vacation_config

     

       16
       16
       +
         | Disable

     

       17
       17
       +
         | Update of vacation_config

     

       18
       18
       +
       

     

       19
       19
       +
       and vacation_config = {

     

       20
       20
       +
         subject : string option;

     

       21
       21
       +
         text_body : string;

     

       22
       22
       +
         html_body : string option;

     

       23
       23
       +
         from_date : float option;

     

       24
       24
       +
         to_date : float option;

     

       25
       25
       +
         exclude_addresses : string list;

     

       26
       26
       +
       }

     

       27
       27
       +
       

     

       28
       28
       +
       (** Command-line arguments **)

     

       29
       29
       +
       

     

       30
       30
       +
       let host_arg =

     

       31
       31
       +
         Arg.(required & opt (some string) None & info ["h"; "host"] 

     

       32
       32
       +
              ~docv:"HOST" ~doc:"JMAP server hostname")

     

       33
       33
       +
       

     

       34
       34
       +
       let user_arg =

     

       35
       35
       +
         Arg.(required & opt (some string) None & info ["u"; "user"] 

     

       36
       36
       +
              ~docv:"USERNAME" ~doc:"Username for authentication")

     

       37
       37
       +
       

     

       38
       38
       +
       let password_arg =

     

       39
       39
       +
         Arg.(required & opt (some string) None & info ["p"; "password"] 

     

       40
       40
       +
              ~docv:"PASSWORD" ~doc:"Password for authentication")

     

       41
       41
       +
       

     

       42
       42
       +
       let enable_arg =

     

       43
       43
       +
         Arg.(value & flag & info ["e"; "enable"] 

     

       44
       44
       +
              ~doc:"Enable vacation response")

     

       45
       45
       +
       

     

       46
       46
       +
       let disable_arg =

     

       47
       47
       +
         Arg.(value & flag & info ["d"; "disable"] 

     

       48
       48
       +
              ~doc:"Disable vacation response")

     

       49
       49
       +
       

     

       50
       50
       +
       let show_arg =

     

       51
       51
       +
         Arg.(value & flag & info ["s"; "show"] 

     

       52
       52
       +
              ~doc:"Show current vacation settings")

     

       53
       53
       +
       

     

       54
       54
       +
       let subject_arg =

     

       55
       55
       +
         Arg.(value & opt (some string) None & info ["subject"] 

     

       56
       56
       +
              ~docv:"SUBJECT" ~doc:"Vacation email subject line")

     

       57
       57
       +
       

     

       58
       58
       +
       let message_arg =

     

       59
       59
       +
         Arg.(value & opt (some string) None & info ["m"; "message"] 

     

       60
       60
       +
              ~docv:"TEXT" ~doc:"Vacation message text")

     

       61
       61
       +
       

     

       62
       62
       +
       let message_file_arg =

     

       63
       63
       +
         Arg.(value & opt (some string) None & info ["message-file"] 

     

       64
       64
       +
              ~docv:"FILE" ~doc:"Read vacation message from file")

     

       65
       65
       +
       

     

       66
       66
       +
       let html_message_arg =

     

       67
       67
       +
         Arg.(value & opt (some string) None & info ["html-message"] 

     

       68
       68
       +
              ~docv:"HTML" ~doc:"HTML vacation message")

     

       69
       69
       +
       

     

       70
       70
       +
       let from_date_arg =

     

       71
       71
       +
         Arg.(value & opt (some string) None & info ["from-date"] 

     

       72
       72
       +
              ~docv:"DATE" ~doc:"Start date for vacation (YYYY-MM-DD)")

     

       73
       73
       +
       

     

       74
       74
       +
       let to_date_arg =

     

       75
       75
       +
         Arg.(value & opt (some string) None & info ["to-date"] 

     

       76
       76
       +
              ~docv:"DATE" ~doc:"End date for vacation (YYYY-MM-DD)")

     

       77
       77
       +
       

     

       78
       78
       +
       let exclude_arg =

     

       79
       79
       +
         Arg.(value & opt_all string [] & info ["exclude"] 

     

       80
       80
       +
              ~docv:"EMAIL" ~doc:"Email address to exclude from auto-response")

     

       81
       81
       +
       

     

       82
       82
       +
       (** Helper functions **)

     

       83
       83
       +
       

     

       84
       84
       +
       (* Parse date string to Unix timestamp *)

     

       85
       85
       +
       let parse_date date_str =

     

       86
       86
       +
         try

     

       87
       87
       +
           let (year, month, day) = Scanf.sscanf date_str "%d-%d-%d" (fun y m d -> (y, m, d)) in

     

       88
       88
       +
           let tm = Unix.{ tm_sec = 0; tm_min = 0; tm_hour = 0;

     

       89
       89
       +
                           tm_mday = day; tm_mon = month - 1; tm_year = year - 1900;

     

       90
       90
       +
                           tm_wday = 0; tm_yday = 0; tm_isdst = false } in

     

       91
       91
       +
           Some (Unix.mktime tm |> fst)

     

       92
       92
       +
         with _ ->

     

       93
       93
       +
           Printf.eprintf "Invalid date format: %s (use YYYY-MM-DD)\n" date_str;

     

       94
       94
       +
           None

     

       95
       95
       +
       

     

       96
       96
       +
       (* Format Unix timestamp as date string *)

     

       97
       97
       +
       let format_date timestamp =

     

       98
       98
       +
         let tm = Unix.localtime timestamp in

     

       99
       99
       +
         Printf.sprintf "%04d-%02d-%02d"

     

       100
       100
       +
           (tm.Unix.tm_year + 1900) (tm.Unix.tm_mon + 1) tm.Unix.tm_mday

     

       101
       101
       +
       

     

       102
       102
       +
       (* Read file contents *)

     

       103
       103
       +
       let read_file filename =

     

       104
       104
       +
         let ic = open_in filename in

     

       105
       105
       +
         let len = in_channel_length ic in

     

       106
       106
       +
         let content = really_input_string ic len in

     

       107
       107
       +
         close_in ic;

     

       108
       108
       +
         content

     

       109
       109
       +
       

     

       110
       110
       +
       (* Display vacation response settings *)

     

       111
       111
       +
       let show_vacation_response vacation =

     

       112
       112
       +
         Printf.printf "\nVacation Response Settings:\n";

     

       113
       113
       +
         Printf.printf "==========================\n\n";

     

       114
       114
       +
         

     

       115
       115
       +
         Printf.printf "Status: %s\n" 

     

       116
       116
       +
           (if Jmap_email.Vacation.Vacation_response.is_enabled vacation then "ENABLED" else "DISABLED");

     

       117
       117
       +
         

     

       118
       118
       +
         (match Jmap_email.Vacation.Vacation_response.subject vacation with

     

       119
       119
       +
         | Some subj -> Printf.printf "Subject: %s\n" subj

     

       120
       120
       +
         | None -> Printf.printf "Subject: (default)\n");

     

       121
       121
       +
         

     

       122
       122
       +
         (match Jmap_email.Vacation.Vacation_response.text_body vacation with

     

       123
       123
       +
         | Some body -> 

     

       124
       124
       +
             Printf.printf "\nMessage:\n";

     

       125
       125
       +
             Printf.printf "--------\n";

     

       126
       126
       +
             Printf.printf "%s\n" body;

     

       127
       127
       +
             Printf.printf "--------\n"

     

       128
       128
       +
         | None -> Printf.printf "\nMessage: (none set)\n");

     

       129
       129
       +
         

     

       130
       130
       +
         (match Jmap_email.Vacation.Vacation_response.from_date vacation with

     

       131
       131
       +
         | Some date -> Printf.printf "\nActive from: %s\n" (format_date date)

     

       132
       132
       +
         | None -> ());

     

       133
       133
       +
         

     

       134
       134
       +
         (match Jmap_email.Vacation.Vacation_response.to_date vacation with

     

       135
       135
       +
         | Some date -> Printf.printf "Active until: %s\n" (format_date date)

     

       136
       136
       +
         | None -> ());

     

       137
       137
       +
         

     

       138
       138
       +
         let excluded = match Jmap_email.Vacation.Vacation_response.id vacation with

     

       139
       139
       +
           | _ -> []  (* exclude_addresses not available in interface *) in

     

       140
       140
       +
         if excluded <> [] then (

     

       141
       141
       +
           Printf.printf "\nExcluded addresses:\n";

     

       142
       142
       +
           List.iter (Printf.printf "  - %s\n") excluded

     

       143
       143
       +
         )

     

       144
       144
       +
       

     

       145
       145
       +
       (* Get current vacation response *)

     

       146
       146
       +
       let get_vacation_response ctx session account_id =

     

       147
       147
       +
         let get_args = Jmap.Methods.Get_args.v

     

       148
       148
       +
           ~account_id

     

       149
       149
       +
           ~properties:["isEnabled"; "subject"; "textBody"; "htmlBody"; 

     

       150
       150
       +
                        "fromDate"; "toDate"; "excludeAddresses"]

     

       151
       151
       +
           () in

     

       152
       152
       +
           

     

       153
       153
       +
         let invocation = Jmap.Wire.Invocation.v

     

       154
       154
       +
           ~method_name:"VacationResponse/get"

     

       155
       155
       +
           ~arguments:(`Assoc []) (* Would serialize get_args *)

     

       156
       156
       +
           ~method_call_id:"get1"

     

       157
       157
       +
           () in

     

       158
       158
       +
           

     

       159
       159
       +
         let request = Jmap.Wire.Request.v

     

       160
       160
       +
           ~using:[Jmap.capability_core; Jmap_email.capability_mail; Jmap_email.capability_vacationresponse]

     

       161
       161
       +
           ~method_calls:[invocation]

     

       162
       162
       +
           () in

     

       163
       163
       +
           

     

       164
       164
       +
         match Jmap_unix.request ctx request with

     

       165
       165
       +
         | Ok _ ->

     

       166
       166
       +
             (* Would extract from response - for now create a sample *)

     

       167
       167
       +
             Ok (Jmap_email.Vacation.Vacation_response.v

     

       168
       168
       +
               ~id:"vacation1"

     

       169
       169
       +
               ~is_enabled:false

     

       170
       170
       +
               ~subject:"Out of Office"

     

       171
       171
       +
               ~text_body:"I am currently out of the office and will respond when I return."

     

       172
       172
       +
               ())

     

       173
       173
       +
         | Error e -> Error e

     

       174
       174
       +
       

     

       175
       175
       +
       (* Update vacation response *)

     

       176
       176
       +
       let update_vacation_response ctx session account_id vacation_id updates =

     

       177
       177
       +
         let update_map = Hashtbl.create 1 in

     

       178
       178
       +
         Hashtbl.add update_map vacation_id updates;

     

       179
       179
       +
         

     

       180
       180
       +
         let set_args = Jmap.Methods.Set_args.v

     

       181
       181
       +
           ~account_id

     

       182
       182
       +
           ~update:update_map

     

       183
       183
       +
           () in

     

       184
       184
       +
           

     

       185
       185
       +
         let invocation = Jmap.Wire.Invocation.v

     

       186
       186
       +
           ~method_name:"VacationResponse/set"

     

       187
       187
       +
           ~arguments:(`Assoc []) (* Would serialize set_args *)

     

       188
       188
       +
           ~method_call_id:"set1"

     

       189
       189
       +
           () in

     

       190
       190
       +
           

     

       191
       191
       +
         let request = Jmap.Wire.Request.v

     

       192
       192
       +
           ~using:[Jmap.capability_core; Jmap_email.capability_mail; Jmap_email.capability_vacationresponse]

     

       193
       193
       +
           ~method_calls:[invocation]

     

       194
       194
       +
           () in

     

       195
       195
       +
           

     

       196
       196
       +
         match Jmap_unix.request ctx request with

     

       197
       197
       +
         | Ok _ -> Ok ()

     

       198
       198
       +
         | Error e -> Error e

     

       199
       199
       +
       

     

       200
       200
       +
       (* Process vacation action *)

     

       201
       201
       +
       let process_vacation_action ctx session account_id action =

     

       202
       202
       +
         match action with

     

       203
       203
       +
         | Show ->

     

       204
       204
       +
             (match get_vacation_response ctx session account_id with

     

       205
       205
       +
             | Ok vacation ->

     

       206
       206
       +
                 show_vacation_response vacation;

     

       207
       207
       +
                 0

     

       208
       208
       +
             | Error e ->

     

       209
       209
       +
                 Printf.eprintf "Failed to get vacation response: %s\n" (Jmap.Error.error_to_string e);

     

       210
       210
       +
                 1)

     

       211
       211
       +
             

     

       212
       212
       +
         | Enable config ->

     

       213
       213
       +
             Printf.printf "Enabling vacation response...\n";

     

       214
       214
       +
             

     

       215
       215
       +
             (* Build the vacation response object *)

     

       216
       216
       +
             let vacation = Jmap_email.Vacation.Vacation_response.v

     

       217
       217
       +
               ~id:"singleton"

     

       218
       218
       +
               ~is_enabled:true

     

       219
       219
       +
               ?subject:config.subject

     

       220
       220
       +
               ~text_body:config.text_body

     

       221
       221
       +
               ?html_body:config.html_body

     

       222
       222
       +
               ?from_date:config.from_date

     

       223
       223
       +
               ?to_date:config.to_date

     

       224
       224
       +
               () in

     

       225
       225
       +
               

     

       226
       226
       +
             (match update_vacation_response ctx session account_id "singleton" vacation with

     

       227
       227
       +
             | Ok () ->

     

       228
       228
       +
                 Printf.printf "\nVacation response enabled successfully!\n";

     

       229
       229
       +
                 

     

       230
       230
       +
                 (* Show what was set *)

     

       231
       231
       +
                 show_vacation_response vacation;

     

       232
       232
       +
                 0

     

       233
       233
       +
             | Error e ->

     

       234
       234
       +
                 Printf.eprintf "Failed to enable vacation response: %s\n" (Jmap.Error.error_to_string e);

     

       235
       235
       +
                 1)

     

       236
       236
       +
             

     

       237
       237
       +
         | Disable ->

     

       238
       238
       +
             Printf.printf "Disabling vacation response...\n";

     

       239
       239
       +
             

     

       240
       240
       +
             let updates = Jmap_email.Vacation.Vacation_response.v

     

       241
       241
       +
               ~id:"singleton"

     

       242
       242
       +
               ~is_enabled:false

     

       243
       243
       +
               () in

     

       244
       244
       +
               

     

       245
       245
       +
             (match update_vacation_response ctx session account_id "singleton" updates with

     

       246
       246
       +
             | Ok () ->

     

       247
       247
       +
                 Printf.printf "Vacation response disabled successfully!\n";

     

       248
       248
       +
                 0

     

       249
       249
       +
             | Error e ->

     

       250
       250
       +
                 Printf.eprintf "Failed to disable vacation response: %s\n" (Jmap.Error.error_to_string e);

     

       251
       251
       +
                 1)

     

       252
       252
       +
             

     

       253
       253
       +
         | Update config ->

     

       254
       254
       +
             Printf.printf "Updating vacation response...\n";

     

       255
       255
       +
             

     

       256
       256
       +
             (* Only update specified fields *)

     

       257
       257
       +
             let vacation = Jmap_email.Vacation.Vacation_response.v

     

       258
       258
       +
               ~id:"singleton"

     

       259
       259
       +
               ?subject:config.subject

     

       260
       260
       +
               ~text_body:config.text_body

     

       261
       261
       +
               ?html_body:config.html_body

     

       262
       262
       +
               ?from_date:config.from_date

     

       263
       263
       +
               ?to_date:config.to_date

     

       264
       264
       +
               () in

     

       265
       265
       +
               

     

       266
       266
       +
             (match update_vacation_response ctx session account_id "singleton" vacation with

     

       267
       267
       +
             | Ok () ->

     

       268
       268
       +
                 Printf.printf "Vacation response updated successfully!\n";

     

       269
       269
       +
                 

     

       270
       270
       +
                 (* Show current settings *)

     

       271
       271
       +
                 (match get_vacation_response ctx session account_id with

     

       272
       272
       +
                 | Ok current -> show_vacation_response current

     

       273
       273
       +
                 | Error _ -> ());

     

       274
       274
       +
                 0

     

       275
       275
       +
             | Error e ->

     

       276
       276
       +
                 Printf.eprintf "Failed to update vacation response: %s\n" (Jmap.Error.error_to_string e);

     

       277
       277
       +
                 1)

     

       278
       278
       +
       

     

       279
       279
       +
       (* Command implementation *)

     

       280
       280
       +
       let vacation_command host user password enable disable show subject message 

     

       281
       281
       +
                            message_file html_message from_date to_date exclude : int =

     

       282
       282
       +
         Printf.printf "JMAP Vacation Manager\n";

     

       283
       283
       +
         Printf.printf "Server: %s\n" host;

     

       284
       284
       +
         Printf.printf "User: %s\n\n" user;

     

       285
       285
       +
         

     

       286
       286
       +
         (* Determine action *)

     

       287
       287
       +
         let action_count = (if enable then 1 else 0) + 

     

       288
       288
       +
                            (if disable then 1 else 0) + 

     

       289
       289
       +
                            (if show then 1 else 0) in

     

       290
       290
       +
                            

     

       291
       291
       +
         if action_count = 0 then (

     

       292
       292
       +
           Printf.eprintf "Error: Must specify an action: --enable, --disable, or --show\n";

     

       293
       293
       +
           exit 1

     

       294
       294
       +
         );

     

       295
       295
       +
         

     

       296
       296
       +
         if action_count > 1 then (

     

       297
       297
       +
           Printf.eprintf "Error: Can only specify one action at a time\n";

     

       298
       298
       +
           exit 1

     

       299
       299
       +
         );

     

       300
       300
       +
         

     

       301
       301
       +
         (* Build vacation config if enabling or updating *)

     

       302
       302
       +
         let config = if enable || (not disable && not show) then

     

       303
       303
       +
           (* Read message content *)

     

       304
       304
       +
           let text_body = match message, message_file with

     

       305
       305
       +
             | Some text, _ -> text

     

       306
       306
       +
             | None, Some file -> read_file file

     

       307
       307
       +
             | None, None ->

     

       308
       308
       +
                 if enable then (

     

       309
       309
       +
                   Printf.eprintf "Error: Must provide vacation message (--message or --message-file)\n";

     

       310
       310
       +
                   exit 1

     

       311
       311
       +
                 ) else ""

     

       312
       312
       +
           in

     

       313
       313
       +
           

     

       314
       314
       +
           (* Parse dates *)

     

       315
       315
       +
           let from_date = match from_date with

     

       316
       316
       +
             | Some date_str -> parse_date date_str

     

       317
       317
       +
             | None -> None

     

       318
       318
       +
           in

     

       319
       319
       +
           

     

       320
       320
       +
           let to_date = match to_date with

     

       321
       321
       +
             | Some date_str -> parse_date date_str

     

       322
       322
       +
             | None -> None

     

       323
       323
       +
           in

     

       324
       324
       +
           

     

       325
       325
       +
           Some {

     

       326
       326
       +
             subject;

     

       327
       327
       +
             text_body;

     

       328
       328
       +
             html_body = html_message;

     

       329
       329
       +
             from_date;

     

       330
       330
       +
             to_date;

     

       331
       331
       +
             exclude_addresses = exclude;

     

       332
       332
       +
           }

     

       333
       333
       +
         else

     

       334
       334
       +
           None

     

       335
       335
       +
         in

     

       336
       336
       +
         

     

       337
       337
       +
         (* Determine action *)

     

       338
       338
       +
         let action = 

     

       339
       339
       +
           if show then Show

     

       340
       340
       +
           else if disable then Disable

     

       341
       341
       +
           else if enable then Enable (Option.get config)

     

       342
       342
       +
           else Update (Option.get config)

     

       343
       343
       +
         in

     

       344
       344
       +
         

     

       345
       345
       +
         (* Connect to server *)

     

       346
       346
       +
         let ctx = Jmap_unix.create_client () in

     

       347
       347
       +
         let result = Jmap_unix.quick_connect ~host ~username:user ~password in

     

       348
       348
       +
         

     

       349
       349
       +
         let (ctx, session) = match result with

     

       350
       350
       +
           | Ok (ctx, session) -> (ctx, session)

     

       351
       351
       +
           | Error e -> 

     

       352
       352
       +
               Printf.eprintf "Connection failed: %s\n" (Jmap.Error.error_to_string e);

     

       353
       353
       +
               exit 1

     

       354
       354
       +
         in

     

       355
       355
       +
         

     

       356
       356
       +
         (* Check vacation capability *)

     

       357
       357
       +
         (* Note: has_capability not available in interface, assuming server supports it *)

     

       358
       358
       +
         

     

       359
       359
       +
         (* Get the primary account ID *)

     

       360
       360
       +
         let account_id = match Jmap.get_primary_account session Jmap_email.capability_mail with

     

       361
       361
       +
           | Ok id -> id

     

       362
       362
       +
           | Error e -> 

     

       363
       363
       +
               Printf.eprintf "No mail account found: %s\n" (Jmap.Error.error_to_string e);

     

       364
       364
       +
               exit 1

     

       365
       365
       +
         in

     

       366
       366
       +
         

     

       367
       367
       +
         (* Process the action *)

     

       368
       368
       +
         process_vacation_action ctx session account_id action

     

       369
       369
       +
       

     

       370
       370
       +
       (* Command definition *)

     

       371
       371
       +
       let vacation_cmd =

     

       372
       372
       +
         let doc = "manage vacation/out-of-office auto-responses" in

     

       373
       373
       +
         let man = [

     

       374
       374
       +
           `S Manpage.s_description;

     

       375
       375
       +
           `P "Manage vacation responses (out-of-office auto-replies) via JMAP.";

     

       376
       376
       +
           `P "Configure automatic email responses for when you're away.";

     

       377
       377
       +
           `S Manpage.s_examples;

     

       378
       378
       +
           `P "Show current vacation settings:";

     

       379
       379
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --show";

     

       380
       380
       +
           `P "";

     

       381
       381
       +
           `P "Enable vacation response:";

     

       382
       382
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --enable \\";

     

       383
       383
       +
           `P "    --subject \"Out of Office\" \\";

     

       384
       384
       +
           `P "    --message \"I am currently out of the office and will return on Monday.\"";

     

       385
       385
       +
           `P "";

     

       386
       386
       +
           `P "Enable with date range:";

     

       387
       387
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --enable \\";

     

       388
       388
       +
           `P "    --message-file vacation.txt \\";

     

       389
       389
       +
           `P "    --from-date 2024-07-01 --to-date 2024-07-15";

     

       390
       390
       +
           `P "";

     

       391
       391
       +
           `P "Disable vacation response:";

     

       392
       392
       +
           `P "  $(mname) -h jmap.example.com -u user@example.com -p secret123 --disable";

     

       393
       393
       +
         ] in

     

       394
       394
       +
         

     

       395
       395
       +
         let cmd =

     

       396
       396
       +
           Cmd.v

     

       397
       397
       +
             (Cmd.info "jmap-vacation-manager" ~version:"1.0" ~doc ~man)

     

       398
       398
       +
             Term.(const vacation_command $ host_arg $ user_arg $ password_arg $ 

     

       399
       399
       +
                   enable_arg $ disable_arg $ show_arg $ subject_arg $ message_arg $

     

       400
       400
       +
                   message_file_arg $ html_message_arg $ from_date_arg $ to_date_arg $

     

       401
       401
       +
                   exclude_arg)

     

       402
       402
       +
         in

     

       403
       403
       +
         cmd

     

       404
       404
       +
       

     

       405
       405
       +
       (* Main entry point *)

     

       406
       406
       +
       let () = exit (Cmd.eval' vacation_cmd)

+1 -18

dune-project

···

       1
       1
       -
       (lang dune 3.17)

     

       2
       2
       -
       (name jmap)

     

       3
       3
       -
       

     

       4
       4
       -
       (source (github avsm/jmap))

     

       5
       5
       -
       (license ISC)

     

       6
       6
       -
       (authors "Anil Madhavapeddy")

     

       7
       7
       -
       (maintainers "anil@recoil.org")

     

       8
       8
       -
       

     

       9
       9
       -
       (generate_opam_files true)

     

       10
       10
       -
       

     

       11
       11
       -
       (package

     

       12
       12
       -
        (name jmap)

     

       13
       13
       -
        (synopsis "JMAP protocol")

     

       14
       14
       -
        (description "This is all still a work in progress")

     

       15
       15
       -
        (depends

     

       16
       16
       -
         (ocaml (>= "5.2.0"))

     

       17
       17
       -
         ezjsonm

     

       18
       18
       -
         ptime))

     

       1
       1
       +
       (lang dune 3.17)

+15

jmap/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name jmap)

     

       3
       3
       +
        (public_name jmap)

     

       4
       4
       +
        (libraries yojson uri)

     

       5
       5
       +
        (modules_without_implementation jmap jmap_binary jmap_error jmap_methods

     

       6
       6
       +
         jmap_push jmap_session jmap_types jmap_wire)

     

       7
       7
       +
        (modules

     

       8
       8
       +
         jmap

     

       9
       9
       +
         jmap_types

     

       10
       10
       +
         jmap_error

     

       11
       11
       +
         jmap_wire

     

       12
       12
       +
         jmap_session

     

       13
       13
       +
         jmap_methods

     

       14
       14
       +
         jmap_binary

     

       15
       15
       +
         jmap_push))

+136

jmap/jmap.mli

···

       1
       1
       +
       (** JMAP Core Protocol Library Interface (RFC 8620)

     

       2
       2
       +
           

     

       3
       3
       +
           This library provides OCaml types and function signatures for interacting

     

       4
       4
       +
           with a JMAP server according to the core protocol specification in RFC 8620.

     

       5
       5
       +
           

     

       6
       6
       +
           Modules:

     

       7
       7
       +
           - {!Jmap.Types}: Basic data types (Id, Date, etc.).

     

       8
       8
       +
           - {!Jmap.Error}: Error types (ProblemDetails, MethodError, SetError).

     

       9
       9
       +
           - {!Jmap.Wire}: Request and Response structures.

     

       10
       10
       +
           - {!Jmap.Session}: Session object and discovery.

     

       11
       11
       +
           - {!Jmap.Methods}: Standard method patterns (/get, /set, etc.) and Core/echo.

     

       12
       12
       +
           - {!Jmap.Binary}: Binary data upload/download types.

     

       13
       13
       +
           - {!Jmap.Push}: Push notification types (StateChange, PushSubscription).

     

       14
       14
       +
           

     

       15
       15
       +
           For email-specific extensions (RFC 8621), see the Jmap_email library.

     

       16
       16
       +
           For Unix-specific implementation, see the Jmap_unix library.

     

       17
       17
       +
           

     

       18
       18
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html> RFC 8620: Core JMAP

     

       19
       19
       +
       *)

     

       20
       20
       +
       

     

       21
       21
       +
       (** {1 Core JMAP Types and Modules} *)

     

       22
       22
       +
       

     

       23
       23
       +
       module Types = Jmap_types

     

       24
       24
       +
       module Error = Jmap_error

     

       25
       25
       +
       module Wire = Jmap_wire

     

       26
       26
       +
       module Session = Jmap_session

     

       27
       27
       +
       module Methods = Jmap_methods

     

       28
       28
       +
       module Binary = Jmap_binary

     

       29
       29
       +
       module Push = Jmap_push

     

       30
       30
       +
       

     

       31
       31
       +
       (** {1 Example Usage} 

     

       32
       32
       +
       

     

       33
       33
       +
           The following example demonstrates using the Core JMAP library with the Unix implementation

     

       34
       34
       +
           to make a simple echo request.

     

       35
       35
       +
       

     

       36
       36
       +
       {[ 

     

       37
       37
       +
         (* OCaml 5.1 required for Lwt let operators *) 

     

       38
       38
       +
         open Lwt.Syntax 

     

       39
       39
       +
         open Jmap 

     

       40
       40
       +
         open Jmap.Types 

     

       41
       41
       +
         open Jmap.Wire 

     

       42
       42
       +
         open Jmap.Methods

     

       43
       43
       +
         open Jmap.Unix

     

       44
       44
       +
         

     

       45
       45
       +
         let simple_echo_request ctx session = 

     

       46
       46
       +
           (* Prepare an echo invocation *) 

     

       47
       47
       +
           let echo_args = Yojson.Safe.to_basic (`Assoc [

     

       48
       48
       +
             ("hello", `String "world");

     

       49
       49
       +
             ("array", `List [`Int 1; `Int 2; `Int 3]);

     

       50
       50
       +
           ]) in

     

       51
       51
       +
           

     

       52
       52
       +
           let echo_invocation = Invocation.v 

     

       53
       53
       +
             ~method_name:"Core/echo"

     

       54
       54
       +
             ~arguments:echo_args

     

       55
       55
       +
             ~method_call_id:"echo1"

     

       56
       56
       +
             ()

     

       57
       57
       +
           in

     

       58
       58
       +
       

     

       59
       59
       +
           (* Prepare the JMAP request *) 

     

       60
       60
       +
           let request = Request.v

     

       61
       61
       +
             ~using:[capability_core]

     

       62
       62
       +
             ~method_calls:[echo_invocation]

     

       63
       63
       +
             ()

     

       64
       64
       +
           in

     

       65
       65
       +
       

     

       66
       66
       +
           (* Send the request *) 

     

       67
       67
       +
           let* response = Jmap.Unix.request ctx request in

     

       68
       68
       +
       

     

       69
       69
       +
           (* Process the response *) 

     

       70
       70
       +
           match Wire.find_method_response response "echo1" with

     

       71
       71
       +
           | Some (method_name, args, _) when method_name = "Core/echo" ->

     

       72
       72
       +
               (* Echo response should contain the same arguments we sent *)

     

       73
       73
       +
               let hello_value = match Yojson.Safe.Util.member "hello" args with

     

       74
       74
       +
                 | `String s -> s

     

       75
       75
       +
                 | _ -> "not found"

     

       76
       76
       +
               in

     

       77
       77
       +
               Printf.printf "Echo response received: hello=%s\n" hello_value;

     

       78
       78
       +
               Lwt.return_unit

     

       79
       79
       +
           | _ ->

     

       80
       80
       +
               Printf.eprintf "Echo response not found or unexpected format\n";

     

       81
       81
       +
               Lwt.return_unit

     

       82
       82
       +
       

     

       83
       83
       +
         let main () = 

     

       84
       84
       +
           (* Authentication details are placeholder *) 

     

       85
       85
       +
           let credentials = "my_auth_token" in 

     

       86
       86
       +
           let* (ctx, session) = Jmap.Unix.connect ~host:"jmap.example.com" ~credentials in 

     

       87
       87
       +
           let* () = simple_echo_request ctx session in 

     

       88
       88
       +
           Jmap.Unix.close ctx 

     

       89
       89
       +
       

     

       90
       90
       +
         (* Lwt_main.run (main ()) *) 

     

       91
       91
       +
       ]} 

     

       92
       92
       +
       *)

     

       93
       93
       +
       

     

       94
       94
       +
       (** Capability URI for JMAP Core.

     

       95
       95
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)

     

       96
       96
       +
       val capability_core : string

     

       97
       97
       +
       

     

       98
       98
       +
       (** {1 Convenience Functions} *)

     

       99
       99
       +
       

     

       100
       100
       +
       (** Check if a session supports a given capability.

     

       101
       101
       +
           @param session The session object.

     

       102
       102
       +
           @param capability The capability URI to check.

     

       103
       103
       +
           @return True if supported, false otherwise.

     

       104
       104
       +
       *)

     

       105
       105
       +
       val supports_capability : Jmap_session.Session.t -> string -> bool

     

       106
       106
       +
       

     

       107
       107
       +
       (** Get the primary account ID for a given capability.

     

       108
       108
       +
           @param session The session object.

     

       109
       109
       +
           @param capability The capability URI.

     

       110
       110
       +
           @return The account ID or an error if not found.

     

       111
       111
       +
       *)

     

       112
       112
       +
       val get_primary_account : Jmap_session.Session.t -> string -> (Jmap_types.id, Error.error) result

     

       113
       113
       +
       

     

       114
       114
       +
       (** Get the download URL for a blob.

     

       115
       115
       +
           @param session The session object.

     

       116
       116
       +
           @param account_id The account ID.

     

       117
       117
       +
           @param blob_id The blob ID.

     

       118
       118
       +
           @param ?name Optional filename for the download.

     

       119
       119
       +
           @param ?content_type Optional content type for the download.

     

       120
       120
       +
           @return The download URL.

     

       121
       121
       +
       *)

     

       122
       122
       +
       val get_download_url : 

     

       123
       123
       +
         Jmap_session.Session.t -> 

     

       124
       124
       +
         account_id:Jmap_types.id -> 

     

       125
       125
       +
         blob_id:Jmap_types.id -> 

     

       126
       126
       +
         ?name:string -> 

     

       127
       127
       +
         ?content_type:string -> 

     

       128
       128
       +
         unit ->

     

       129
       129
       +
         Uri.t

     

       130
       130
       +
       

     

       131
       131
       +
       (** Get the upload URL for a blob.

     

       132
       132
       +
           @param session The session object.

     

       133
       133
       +
           @param account_id The account ID.

     

       134
       134
       +
           @return The upload URL.

     

       135
       135
       +
       *)

     

       136
       136
       +
       val get_upload_url : Jmap_session.Session.t -> account_id:Jmap_types.id -> Uri.t

+60

jmap/jmap_binary.mli

···

       1
       1
       +
       (** JMAP Binary Data Handling.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-6> RFC 8620, Section 6 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap_types

     

       5
       5
       +
       open Jmap_error

     

       6
       6
       +
       

     

       7
       7
       +
       (** Response from uploading binary data.

     

       8
       8
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-6.1> RFC 8620, Section 6.1 *)

     

       9
       9
       +
       module Upload_response : sig

     

       10
       10
       +
         type t

     

       11
       11
       +
         

     

       12
       12
       +
         val account_id : t -> id

     

       13
       13
       +
         val blob_id : t -> id

     

       14
       14
       +
         val type_ : t -> string

     

       15
       15
       +
         val size : t -> uint

     

       16
       16
       +
         

     

       17
       17
       +
         val v :

     

       18
       18
       +
           account_id:id ->

     

       19
       19
       +
           blob_id:id ->

     

       20
       20
       +
           type_:string ->

     

       21
       21
       +
           size:uint ->

     

       22
       22
       +
           unit ->

     

       23
       23
       +
           t

     

       24
       24
       +
       end

     

       25
       25
       +
       

     

       26
       26
       +
       (** Arguments for Blob/copy.

     

       27
       27
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-6.3> RFC 8620, Section 6.3 *)

     

       28
       28
       +
       module Blob_copy_args : sig

     

       29
       29
       +
         type t

     

       30
       30
       +
         

     

       31
       31
       +
         val from_account_id : t -> id

     

       32
       32
       +
         val account_id : t -> id

     

       33
       33
       +
         val blob_ids : t -> id list

     

       34
       34
       +
         

     

       35
       35
       +
         val v :

     

       36
       36
       +
           from_account_id:id ->

     

       37
       37
       +
           account_id:id ->

     

       38
       38
       +
           blob_ids:id list ->

     

       39
       39
       +
           unit ->

     

       40
       40
       +
           t

     

       41
       41
       +
       end

     

       42
       42
       +
       

     

       43
       43
       +
       (** Response for Blob/copy.

     

       44
       44
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-6.3> RFC 8620, Section 6.3 *)

     

       45
       45
       +
       module Blob_copy_response : sig

     

       46
       46
       +
         type t

     

       47
       47
       +
         

     

       48
       48
       +
         val from_account_id : t -> id

     

       49
       49
       +
         val account_id : t -> id

     

       50
       50
       +
         val copied : t -> id id_map option

     

       51
       51
       +
         val not_copied : t -> Set_error.t id_map option

     

       52
       52
       +
         

     

       53
       53
       +
         val v :

     

       54
       54
       +
           from_account_id:id ->

     

       55
       55
       +
           account_id:id ->

     

       56
       56
       +
           ?copied:id id_map ->

     

       57
       57
       +
           ?not_copied:Set_error.t id_map ->

     

       58
       58
       +
           unit ->

     

       59
       59
       +
           t

     

       60
       60
       +
       end

+189

jmap/jmap_error.mli

···

       1
       1
       +
       (** JMAP Error Types.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6> RFC 8620, Section 3.6 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap_types

     

       5
       5
       +
       

     

       6
       6
       +
       (** Standard Method-level error types.

     

       7
       7
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.2> RFC 8620, Section 3.6.2 *)

     

       8
       8
       +
       type method_error_type = [

     

       9
       9
       +
         | `ServerUnavailable

     

       10
       10
       +
         | `ServerFail

     

       11
       11
       +
         | `ServerPartialFail

     

       12
       12
       +
         | `UnknownMethod

     

       13
       13
       +
         | `InvalidArguments

     

       14
       14
       +
         | `InvalidResultReference

     

       15
       15
       +
         | `Forbidden

     

       16
       16
       +
         | `AccountNotFound

     

       17
       17
       +
         | `AccountNotSupportedByMethod

     

       18
       18
       +
         | `AccountReadOnly

     

       19
       19
       +
         | `RequestTooLarge

     

       20
       20
       +
         | `CannotCalculateChanges

     

       21
       21
       +
         | `StateMismatch

     

       22
       22
       +
         | `AnchorNotFound

     

       23
       23
       +
         | `UnsupportedSort

     

       24
       24
       +
         | `UnsupportedFilter

     

       25
       25
       +
         | `TooManyChanges

     

       26
       26
       +
         | `FromAccountNotFound

     

       27
       27
       +
         | `FromAccountNotSupportedByMethod

     

       28
       28
       +
         | `Other_method_error of string

     

       29
       29
       +
       ]

     

       30
       30
       +
       

     

       31
       31
       +
       (** Standard SetError types.

     

       32
       32
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3> RFC 8620, Section 5.3 *)

     

       33
       33
       +
       type set_error_type = [

     

       34
       34
       +
         | `Forbidden

     

       35
       35
       +
         | `OverQuota

     

       36
       36
       +
         | `TooLarge

     

       37
       37
       +
         | `RateLimit

     

       38
       38
       +
         | `NotFound

     

       39
       39
       +
         | `InvalidPatch

     

       40
       40
       +
         | `WillDestroy

     

       41
       41
       +
         | `InvalidProperties

     

       42
       42
       +
         | `Singleton

     

       43
       43
       +
         | `AlreadyExists (* From /copy *)

     

       44
       44
       +
         | `MailboxHasChild (* RFC 8621 *)

     

       45
       45
       +
         | `MailboxHasEmail (* RFC 8621 *)

     

       46
       46
       +
         | `BlobNotFound (* RFC 8621 *)

     

       47
       47
       +
         | `TooManyKeywords (* RFC 8621 *)

     

       48
       48
       +
         | `TooManyMailboxes (* RFC 8621 *)

     

       49
       49
       +
         | `InvalidEmail (* RFC 8621 *)

     

       50
       50
       +
         | `TooManyRecipients (* RFC 8621 *)

     

       51
       51
       +
         | `NoRecipients (* RFC 8621 *)

     

       52
       52
       +
         | `InvalidRecipients (* RFC 8621 *)

     

       53
       53
       +
         | `ForbiddenMailFrom (* RFC 8621 *)

     

       54
       54
       +
         | `ForbiddenFrom (* RFC 8621 *)

     

       55
       55
       +
         | `ForbiddenToSend (* RFC 8621 *)

     

       56
       56
       +
         | `CannotUnsend (* RFC 8621 *)

     

       57
       57
       +
         | `Other_set_error of string (* For future or custom errors *)

     

       58
       58
       +
       ]

     

       59
       59
       +
       

     

       60
       60
       +
       (** Primary error type that can represent all JMAP errors *)

     

       61
       61
       +
       type error =

     

       62
       62
       +
         | Transport of string     (** Network/HTTP-level error *)

     

       63
       63
       +
         | Parse of string         (** JSON parsing error *)

     

       64
       64
       +
         | Protocol of string      (** JMAP protocol error *)

     

       65
       65
       +
         | Problem of string       (** Problem Details object error *)

     

       66
       66
       +
         | Method of method_error_type * string option (** Method error with optional description *)

     

       67
       67
       +
         | SetItem of id * set_error_type * string option (** Error for a specific item in a /set operation *)

     

       68
       68
       +
         | Auth of string          (** Authentication error *)

     

       69
       69
       +
         | ServerError of string   (** Server reported an error *)

     

       70
       70
       +
       

     

       71
       71
       +
       (** Standard Result type for JMAP operations *)

     

       72
       72
       +
       type 'a result = ('a, error) Result.t

     

       73
       73
       +
       

     

       74
       74
       +
       (** Problem details object for HTTP-level errors.

     

       75
       75
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.1> RFC 8620, Section 3.6.1

     

       76
       76
       +
           @see <https://www.rfc-editor.org/rfc/rfc7807.html> RFC 7807 *)

     

       77
       77
       +
       module Problem_details : sig

     

       78
       78
       +
         type t

     

       79
       79
       +
       

     

       80
       80
       +
         val problem_type : t -> string

     

       81
       81
       +
         val status : t -> int option

     

       82
       82
       +
         val detail : t -> string option

     

       83
       83
       +
         val limit : t -> string option

     

       84
       84
       +
         val other_fields : t -> Yojson.Safe.t string_map

     

       85
       85
       +
         

     

       86
       86
       +
         val v : 

     

       87
       87
       +
           ?status:int ->

     

       88
       88
       +
           ?detail:string ->

     

       89
       89
       +
           ?limit:string ->

     

       90
       90
       +
           ?other_fields:Yojson.Safe.t string_map ->

     

       91
       91
       +
           string ->

     

       92
       92
       +
           t

     

       93
       93
       +
       end

     

       94
       94
       +
       

     

       95
       95
       +
       (** Description for method errors. May contain additional details.

     

       96
       96
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.2> RFC 8620, Section 3.6.2 *)

     

       97
       97
       +
       module Method_error_description : sig

     

       98
       98
       +
         type t

     

       99
       99
       +
         

     

       100
       100
       +
         val description : t -> string option

     

       101
       101
       +
         

     

       102
       102
       +
         val v : ?description:string -> unit -> t

     

       103
       103
       +
       end

     

       104
       104
       +
       

     

       105
       105
       +
       (** Represents a method-level error response invocation part.

     

       106
       106
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.2> RFC 8620, Section 3.6.2 *)

     

       107
       107
       +
       module Method_error : sig

     

       108
       108
       +
         type t

     

       109
       109
       +
         

     

       110
       110
       +
         val type_ : t -> method_error_type

     

       111
       111
       +
         val description : t -> Method_error_description.t option

     

       112
       112
       +
         

     

       113
       113
       +
         val v : 

     

       114
       114
       +
           ?description:Method_error_description.t ->

     

       115
       115
       +
           method_error_type ->

     

       116
       116
       +
           t

     

       117
       117
       +
       end

     

       118
       118
       +
       

     

       119
       119
       +
       (** SetError object.

     

       120
       120
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3> RFC 8620, Section 5.3 *)

     

       121
       121
       +
       module Set_error : sig

     

       122
       122
       +
         type t

     

       123
       123
       +
         

     

       124
       124
       +
         val type_ : t -> set_error_type

     

       125
       125
       +
         val description : t -> string option

     

       126
       126
       +
         val properties : t -> string list option

     

       127
       127
       +
         val existing_id : t -> id option

     

       128
       128
       +
         val max_recipients : t -> uint option

     

       129
       129
       +
         val invalid_recipients : t -> string list option

     

       130
       130
       +
         val max_size : t -> uint option

     

       131
       131
       +
         val not_found_blob_ids : t -> id list option

     

       132
       132
       +
         

     

       133
       133
       +
         val v :

     

       134
       134
       +
           ?description:string ->

     

       135
       135
       +
           ?properties:string list ->

     

       136
       136
       +
           ?existing_id:id ->

     

       137
       137
       +
           ?max_recipients:uint ->

     

       138
       138
       +
           ?invalid_recipients:string list ->

     

       139
       139
       +
           ?max_size:uint ->

     

       140
       140
       +
           ?not_found_blob_ids:id list ->

     

       141
       141
       +
           set_error_type ->

     

       142
       142
       +
           t

     

       143
       143
       +
       end

     

       144
       144
       +
       

     

       145
       145
       +
       (** {2 Error Handling Functions} *)

     

       146
       146
       +
       

     

       147
       147
       +
       (** Create a transport error *)

     

       148
       148
       +
       val transport_error : string -> error

     

       149
       149
       +
       

     

       150
       150
       +
       (** Create a parse error *)

     

       151
       151
       +
       val parse_error : string -> error

     

       152
       152
       +
       

     

       153
       153
       +
       (** Create a protocol error *)

     

       154
       154
       +
       val protocol_error : string -> error 

     

       155
       155
       +
       

     

       156
       156
       +
       (** Create a problem details error *)

     

       157
       157
       +
       val problem_error : Problem_details.t -> error

     

       158
       158
       +
       

     

       159
       159
       +
       (** Create a method error *)

     

       160
       160
       +
       val method_error : ?description:string -> method_error_type -> error

     

       161
       161
       +
       

     

       162
       162
       +
       (** Create a SetItem error *)

     

       163
       163
       +
       val set_item_error : id -> ?description:string -> set_error_type -> error

     

       164
       164
       +
       

     

       165
       165
       +
       (** Create an auth error *)

     

       166
       166
       +
       val auth_error : string -> error

     

       167
       167
       +
       

     

       168
       168
       +
       (** Create a server error *)

     

       169
       169
       +
       val server_error : string -> error

     

       170
       170
       +
       

     

       171
       171
       +
       (** Convert a Method_error.t to error *)

     

       172
       172
       +
       val of_method_error : Method_error.t -> error

     

       173
       173
       +
       

     

       174
       174
       +
       (** Convert a Set_error.t to error for a specific ID *)

     

       175
       175
       +
       val of_set_error : id -> Set_error.t -> error

     

       176
       176
       +
       

     

       177
       177
       +
       (** Get a human-readable description of an error *)

     

       178
       178
       +
       val error_to_string : error -> string

     

       179
       179
       +
       

     

       180
       180
       +
       (** {2 Result Handling} *)

     

       181
       181
       +
       

     

       182
       182
       +
       (** Map an error with additional context *)

     

       183
       183
       +
       val map_error : 'a result -> (error -> error) -> 'a result

     

       184
       184
       +
       

     

       185
       185
       +
       (** Add context to an error *)

     

       186
       186
       +
       val with_context : 'a result -> string -> 'a result

     

       187
       187
       +
       

     

       188
       188
       +
       (** Convert an option to a result with an error for None *)

     

       189
       189
       +
       val of_option : 'a option -> error -> 'a result

+417

jmap/jmap_methods.mli

···

       1
       1
       +
       (** Standard JMAP Methods and Core/echo.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-4> RFC 8620, Section 4

     

       3
       3
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5> RFC 8620, Section 5 *)

     

       4
       4
       +
       

     

       5
       5
       +
       open Jmap_types

     

       6
       6
       +
       open Jmap_error

     

       7
       7
       +
       

     

       8
       8
       +
       (** Generic representation of a record type. Actual types defined elsewhere. *)

     

       9
       9
       +
       type generic_record

     

       10
       10
       +
       

     

       11
       11
       +
       (** Arguments for /get methods.

     

       12
       12
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.1> RFC 8620, Section 5.1 *)

     

       13
       13
       +
       module Get_args : sig

     

       14
       14
       +
         type 'record t

     

       15
       15
       +
         

     

       16
       16
       +
         val account_id : 'record t -> id

     

       17
       17
       +
         val ids : 'record t -> id list option

     

       18
       18
       +
         val properties : 'record t -> string list option

     

       19
       19
       +
         

     

       20
       20
       +
         val v :

     

       21
       21
       +
           account_id:id ->

     

       22
       22
       +
           ?ids:id list ->

     

       23
       23
       +
           ?properties:string list ->

     

       24
       24
       +
           unit ->

     

       25
       25
       +
           'record t

     

       26
       26
       +
       end

     

       27
       27
       +
       

     

       28
       28
       +
       (** Response for /get methods.

     

       29
       29
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.1> RFC 8620, Section 5.1 *)

     

       30
       30
       +
       module Get_response : sig

     

       31
       31
       +
         type 'record t

     

       32
       32
       +
         

     

       33
       33
       +
         val account_id : 'record t -> id

     

       34
       34
       +
         val state : 'record t -> string

     

       35
       35
       +
         val list : 'record t -> 'record list

     

       36
       36
       +
         val not_found : 'record t -> id list

     

       37
       37
       +
         

     

       38
       38
       +
         val v :

     

       39
       39
       +
           account_id:id ->

     

       40
       40
       +
           state:string ->

     

       41
       41
       +
           list:'record list ->

     

       42
       42
       +
           not_found:id list ->

     

       43
       43
       +
           unit ->

     

       44
       44
       +
           'record t

     

       45
       45
       +
       end

     

       46
       46
       +
       

     

       47
       47
       +
       (** Arguments for /changes methods.

     

       48
       48
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.2> RFC 8620, Section 5.2 *)

     

       49
       49
       +
       module Changes_args : sig

     

       50
       50
       +
         type t

     

       51
       51
       +
         

     

       52
       52
       +
         val account_id : t -> id

     

       53
       53
       +
         val since_state : t -> string

     

       54
       54
       +
         val max_changes : t -> uint option

     

       55
       55
       +
         

     

       56
       56
       +
         val v :

     

       57
       57
       +
           account_id:id ->

     

       58
       58
       +
           since_state:string ->

     

       59
       59
       +
           ?max_changes:uint ->

     

       60
       60
       +
           unit ->

     

       61
       61
       +
           t

     

       62
       62
       +
       end

     

       63
       63
       +
       

     

       64
       64
       +
       (** Response for /changes methods.

     

       65
       65
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.2> RFC 8620, Section 5.2 *)

     

       66
       66
       +
       module Changes_response : sig

     

       67
       67
       +
         type t

     

       68
       68
       +
         

     

       69
       69
       +
         val account_id : t -> id

     

       70
       70
       +
         val old_state : t -> string

     

       71
       71
       +
         val new_state : t -> string

     

       72
       72
       +
         val has_more_changes : t -> bool

     

       73
       73
       +
         val created : t -> id list

     

       74
       74
       +
         val updated : t -> id list

     

       75
       75
       +
         val destroyed : t -> id list

     

       76
       76
       +
         val updated_properties : t -> string list option

     

       77
       77
       +
         

     

       78
       78
       +
         val v :

     

       79
       79
       +
           account_id:id ->

     

       80
       80
       +
           old_state:string ->

     

       81
       81
       +
           new_state:string ->

     

       82
       82
       +
           has_more_changes:bool ->

     

       83
       83
       +
           created:id list ->

     

       84
       84
       +
           updated:id list ->

     

       85
       85
       +
           destroyed:id list ->

     

       86
       86
       +
           ?updated_properties:string list ->

     

       87
       87
       +
           unit ->

     

       88
       88
       +
           t

     

       89
       89
       +
       end

     

       90
       90
       +
       

     

       91
       91
       +
       (** Patch object for /set update.

     

       92
       92
       +
           A list of (JSON Pointer path, value) pairs.

     

       93
       93
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3> RFC 8620, Section 5.3 *)

     

       94
       94
       +
       type patch_object = (json_pointer * Yojson.Safe.t) list

     

       95
       95
       +
       

     

       96
       96
       +
       (** Arguments for /set methods.

     

       97
       97
       +
           ['create_record] is the record type without server-set/immutable fields.

     

       98
       98
       +
           ['update_record] is the patch object type (usually [patch_object]).

     

       99
       99
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3> RFC 8620, Section 5.3 *)

     

       100
       100
       +
       module Set_args : sig

     

       101
       101
       +
         type ('create_record, 'update_record) t

     

       102
       102
       +
         

     

       103
       103
       +
         val account_id : ('a, 'b) t -> id

     

       104
       104
       +
         val if_in_state : ('a, 'b) t -> string option

     

       105
       105
       +
         val create : ('a, 'b) t -> 'a id_map option

     

       106
       106
       +
         val update : ('a, 'b) t -> 'b id_map option

     

       107
       107
       +
         val destroy : ('a, 'b) t -> id list option

     

       108
       108
       +
         val on_success_destroy_original : ('a, 'b) t -> bool option

     

       109
       109
       +
         val destroy_from_if_in_state : ('a, 'b) t -> string option

     

       110
       110
       +
         val on_destroy_remove_emails : ('a, 'b) t -> bool option

     

       111
       111
       +
         

     

       112
       112
       +
         val v :

     

       113
       113
       +
           account_id:id ->

     

       114
       114
       +
           ?if_in_state:string ->

     

       115
       115
       +
           ?create:'a id_map ->

     

       116
       116
       +
           ?update:'b id_map ->

     

       117
       117
       +
           ?destroy:id list ->

     

       118
       118
       +
           ?on_success_destroy_original:bool ->

     

       119
       119
       +
           ?destroy_from_if_in_state:string ->

     

       120
       120
       +
           ?on_destroy_remove_emails:bool ->

     

       121
       121
       +
           unit ->

     

       122
       122
       +
           ('a, 'b) t

     

       123
       123
       +
       end

     

       124
       124
       +
       

     

       125
       125
       +
       (** Response for /set methods.

     

       126
       126
       +
           ['created_record_info] is the server-set info for created records.

     

       127
       127
       +
           ['updated_record_info] is the server-set/computed info for updated records.

     

       128
       128
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.3> RFC 8620, Section 5.3 *)

     

       129
       129
       +
       module Set_response : sig

     

       130
       130
       +
         type ('created_record_info, 'updated_record_info) t

     

       131
       131
       +
         

     

       132
       132
       +
         val account_id : ('a, 'b) t -> id

     

       133
       133
       +
         val old_state : ('a, 'b) t -> string option

     

       134
       134
       +
         val new_state : ('a, 'b) t -> string

     

       135
       135
       +
         val created : ('a, 'b) t -> 'a id_map option

     

       136
       136
       +
         val updated : ('a, 'b) t -> 'b option id_map option

     

       137
       137
       +
         val destroyed : ('a, 'b) t -> id list option

     

       138
       138
       +
         val not_created : ('a, 'b) t -> Set_error.t id_map option

     

       139
       139
       +
         val not_updated : ('a, 'b) t -> Set_error.t id_map option

     

       140
       140
       +
         val not_destroyed : ('a, 'b) t -> Set_error.t id_map option

     

       141
       141
       +
         

     

       142
       142
       +
         val v :

     

       143
       143
       +
           account_id:id ->

     

       144
       144
       +
           ?old_state:string ->

     

       145
       145
       +
           new_state:string ->

     

       146
       146
       +
           ?created:'a id_map ->

     

       147
       147
       +
           ?updated:'b option id_map ->

     

       148
       148
       +
           ?destroyed:id list ->

     

       149
       149
       +
           ?not_created:Set_error.t id_map ->

     

       150
       150
       +
           ?not_updated:Set_error.t id_map ->

     

       151
       151
       +
           ?not_destroyed:Set_error.t id_map ->

     

       152
       152
       +
           unit ->

     

       153
       153
       +
           ('a, 'b) t

     

       154
       154
       +
       end

     

       155
       155
       +
       

     

       156
       156
       +
       (** Arguments for /copy methods.

     

       157
       157
       +
           ['copy_record_override] contains the record id and override properties.

     

       158
       158
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.4> RFC 8620, Section 5.4 *)

     

       159
       159
       +
       module Copy_args : sig

     

       160
       160
       +
         type 'copy_record_override t

     

       161
       161
       +
         

     

       162
       162
       +
         val from_account_id : 'a t -> id

     

       163
       163
       +
         val if_from_in_state : 'a t -> string option

     

       164
       164
       +
         val account_id : 'a t -> id

     

       165
       165
       +
         val if_in_state : 'a t -> string option

     

       166
       166
       +
         val create : 'a t -> 'a id_map

     

       167
       167
       +
         val on_success_destroy_original : 'a t -> bool

     

       168
       168
       +
         val destroy_from_if_in_state : 'a t -> string option

     

       169
       169
       +
         

     

       170
       170
       +
         val v :

     

       171
       171
       +
           from_account_id:id ->

     

       172
       172
       +
           ?if_from_in_state:string ->

     

       173
       173
       +
           account_id:id ->

     

       174
       174
       +
           ?if_in_state:string ->

     

       175
       175
       +
           create:'a id_map ->

     

       176
       176
       +
           ?on_success_destroy_original:bool ->

     

       177
       177
       +
           ?destroy_from_if_in_state:string ->

     

       178
       178
       +
           unit ->

     

       179
       179
       +
           'a t

     

       180
       180
       +
       end

     

       181
       181
       +
       

     

       182
       182
       +
       (** Response for /copy methods.

     

       183
       183
       +
           ['created_record_info] is the server-set info for the created copy.

     

       184
       184
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.4> RFC 8620, Section 5.4 *)

     

       185
       185
       +
       module Copy_response : sig

     

       186
       186
       +
         type 'created_record_info t

     

       187
       187
       +
         

     

       188
       188
       +
         val from_account_id : 'a t -> id

     

       189
       189
       +
         val account_id : 'a t -> id

     

       190
       190
       +
         val old_state : 'a t -> string option

     

       191
       191
       +
         val new_state : 'a t -> string

     

       192
       192
       +
         val created : 'a t -> 'a id_map option

     

       193
       193
       +
         val not_created : 'a t -> Set_error.t id_map option

     

       194
       194
       +
         

     

       195
       195
       +
         val v :

     

       196
       196
       +
           from_account_id:id ->

     

       197
       197
       +
           account_id:id ->

     

       198
       198
       +
           ?old_state:string ->

     

       199
       199
       +
           new_state:string ->

     

       200
       200
       +
           ?created:'a id_map ->

     

       201
       201
       +
           ?not_created:Set_error.t id_map ->

     

       202
       202
       +
           unit ->

     

       203
       203
       +
           'a t

     

       204
       204
       +
       end

     

       205
       205
       +
       

     

       206
       206
       +
       (** Module for generic filter representation.

     

       207
       207
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.5> RFC 8620, Section 5.5 *)

     

       208
       208
       +
       module Filter : sig

     

       209
       209
       +
         type t

     

       210
       210
       +
         

     

       211
       211
       +
         (** Create a filter from a raw JSON condition *)

     

       212
       212
       +
         val condition : Yojson.Safe.t -> t

     

       213
       213
       +
         

     

       214
       214
       +
         (** Create a filter with a logical operator (AND, OR, NOT) *)

     

       215
       215
       +
         val operator : [ `AND | `OR | `NOT ] -> t list -> t

     

       216
       216
       +
         

     

       217
       217
       +
         (** Combine filters with AND *)

     

       218
       218
       +
         val and_ : t list -> t

     

       219
       219
       +
         

     

       220
       220
       +
         (** Combine filters with OR *)

     

       221
       221
       +
         val or_ : t list -> t

     

       222
       222
       +
         

     

       223
       223
       +
         (** Negate a filter with NOT *)

     

       224
       224
       +
         val not_ : t -> t

     

       225
       225
       +
         

     

       226
       226
       +
         (** Convert a filter to JSON *)

     

       227
       227
       +
         val to_json : t -> Yojson.Safe.t

     

       228
       228
       +
         

     

       229
       229
       +
         (** Predefined filter helpers *)

     

       230
       230
       +
         

     

       231
       231
       +
         (** Create a filter for a text property containing a string *)

     

       232
       232
       +
         val text_contains : string -> string -> t

     

       233
       233
       +
         

     

       234
       234
       +
         (** Create a filter for a property being equal to a value *)

     

       235
       235
       +
         val property_equals : string -> Yojson.Safe.t -> t

     

       236
       236
       +
         

     

       237
       237
       +
         (** Create a filter for a property being not equal to a value *)

     

       238
       238
       +
         val property_not_equals : string -> Yojson.Safe.t -> t

     

       239
       239
       +
         

     

       240
       240
       +
         (** Create a filter for a property being greater than a value *)

     

       241
       241
       +
         val property_gt : string -> Yojson.Safe.t -> t

     

       242
       242
       +
         

     

       243
       243
       +
         (** Create a filter for a property being greater than or equal to a value *)

     

       244
       244
       +
         val property_ge : string -> Yojson.Safe.t -> t

     

       245
       245
       +
         

     

       246
       246
       +
         (** Create a filter for a property being less than a value *)

     

       247
       247
       +
         val property_lt : string -> Yojson.Safe.t -> t

     

       248
       248
       +
         

     

       249
       249
       +
         (** Create a filter for a property being less than or equal to a value *)

     

       250
       250
       +
         val property_le : string -> Yojson.Safe.t -> t

     

       251
       251
       +
         

     

       252
       252
       +
         (** Create a filter for a property value being in a list *)

     

       253
       253
       +
         val property_in : string -> Yojson.Safe.t list -> t

     

       254
       254
       +
         

     

       255
       255
       +
         (** Create a filter for a property value not being in a list *)

     

       256
       256
       +
         val property_not_in : string -> Yojson.Safe.t list -> t

     

       257
       257
       +
         

     

       258
       258
       +
         (** Create a filter for a property being present (not null) *)

     

       259
       259
       +
         val property_exists : string -> t

     

       260
       260
       +
         

     

       261
       261
       +
         (** Create a filter for a string property starting with a prefix *)

     

       262
       262
       +
         val string_starts_with : string -> string -> t

     

       263
       263
       +
         

     

       264
       264
       +
         (** Create a filter for a string property ending with a suffix *)

     

       265
       265
       +
         val string_ends_with : string -> string -> t

     

       266
       266
       +
       end

     

       267
       267
       +
       

     

       268
       268
       +
       

     

       269
       269
       +
       

     

       270
       270
       +
       (** Comparator for sorting.

     

       271
       271
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.5> RFC 8620, Section 5.5 *)

     

       272
       272
       +
       module Comparator : sig

     

       273
       273
       +
         type t

     

       274
       274
       +
         

     

       275
       275
       +
         val property : t -> string

     

       276
       276
       +
         val is_ascending : t -> bool option

     

       277
       277
       +
         val collation : t -> string option

     

       278
       278
       +
         val keyword : t -> string option

     

       279
       279
       +
         val other_fields : t -> Yojson.Safe.t string_map

     

       280
       280
       +
         

     

       281
       281
       +
         val v :

     

       282
       282
       +
           property:string ->

     

       283
       283
       +
           ?is_ascending:bool ->

     

       284
       284
       +
           ?collation:string ->

     

       285
       285
       +
           ?keyword:string ->

     

       286
       286
       +
           ?other_fields:Yojson.Safe.t string_map ->

     

       287
       287
       +
           unit ->

     

       288
       288
       +
           t

     

       289
       289
       +
       end

     

       290
       290
       +
       

     

       291
       291
       +
       (** Arguments for /query methods.

     

       292
       292
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.5> RFC 8620, Section 5.5 *)

     

       293
       293
       +
       module Query_args : sig

     

       294
       294
       +
         type t

     

       295
       295
       +
         

     

       296
       296
       +
         val account_id : t -> id

     

       297
       297
       +
         val filter : t -> Filter.t option

     

       298
       298
       +
         val sort : t -> Comparator.t list option

     

       299
       299
       +
         val position : t -> jint option

     

       300
       300
       +
         val anchor : t -> id option

     

       301
       301
       +
         val anchor_offset : t -> jint option

     

       302
       302
       +
         val limit : t -> uint option

     

       303
       303
       +
         val calculate_total : t -> bool option

     

       304
       304
       +
         val collapse_threads : t -> bool option

     

       305
       305
       +
         val sort_as_tree : t -> bool option

     

       306
       306
       +
         val filter_as_tree : t -> bool option

     

       307
       307
       +
         

     

       308
       308
       +
         val v :

     

       309
       309
       +
           account_id:id ->

     

       310
       310
       +
           ?filter:Filter.t ->

     

       311
       311
       +
           ?sort:Comparator.t list ->

     

       312
       312
       +
           ?position:jint ->

     

       313
       313
       +
           ?anchor:id ->

     

       314
       314
       +
           ?anchor_offset:jint ->

     

       315
       315
       +
           ?limit:uint ->

     

       316
       316
       +
           ?calculate_total:bool ->

     

       317
       317
       +
           ?collapse_threads:bool ->

     

       318
       318
       +
           ?sort_as_tree:bool ->

     

       319
       319
       +
           ?filter_as_tree:bool ->

     

       320
       320
       +
           unit ->

     

       321
       321
       +
           t

     

       322
       322
       +
       end

     

       323
       323
       +
       

     

       324
       324
       +
       (** Response for /query methods.

     

       325
       325
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.5> RFC 8620, Section 5.5 *)

     

       326
       326
       +
       module Query_response : sig

     

       327
       327
       +
         type t

     

       328
       328
       +
         

     

       329
       329
       +
         val account_id : t -> id

     

       330
       330
       +
         val query_state : t -> string

     

       331
       331
       +
         val can_calculate_changes : t -> bool

     

       332
       332
       +
         val position : t -> uint

     

       333
       333
       +
         val ids : t -> id list

     

       334
       334
       +
         val total : t -> uint option

     

       335
       335
       +
         val limit : t -> uint option

     

       336
       336
       +
         

     

       337
       337
       +
         val v :

     

       338
       338
       +
           account_id:id ->

     

       339
       339
       +
           query_state:string ->

     

       340
       340
       +
           can_calculate_changes:bool ->

     

       341
       341
       +
           position:uint ->

     

       342
       342
       +
           ids:id list ->

     

       343
       343
       +
           ?total:uint ->

     

       344
       344
       +
           ?limit:uint ->

     

       345
       345
       +
           unit ->

     

       346
       346
       +
           t

     

       347
       347
       +
       end

     

       348
       348
       +
       

     

       349
       349
       +
       (** Item indicating an added record in /queryChanges.

     

       350
       350
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.6> RFC 8620, Section 5.6 *)

     

       351
       351
       +
       module Added_item : sig

     

       352
       352
       +
         type t

     

       353
       353
       +
         

     

       354
       354
       +
         val id : t -> id

     

       355
       355
       +
         val index : t -> uint

     

       356
       356
       +
         

     

       357
       357
       +
         val v :

     

       358
       358
       +
           id:id ->

     

       359
       359
       +
           index:uint ->

     

       360
       360
       +
           unit ->

     

       361
       361
       +
           t

     

       362
       362
       +
       end

     

       363
       363
       +
       

     

       364
       364
       +
       (** Arguments for /queryChanges methods.

     

       365
       365
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.6> RFC 8620, Section 5.6 *)

     

       366
       366
       +
       module Query_changes_args : sig

     

       367
       367
       +
         type t

     

       368
       368
       +
         

     

       369
       369
       +
         val account_id : t -> id

     

       370
       370
       +
         val filter : t -> Filter.t option

     

       371
       371
       +
         val sort : t -> Comparator.t list option

     

       372
       372
       +
         val since_query_state : t -> string

     

       373
       373
       +
         val max_changes : t -> uint option

     

       374
       374
       +
         val up_to_id : t -> id option

     

       375
       375
       +
         val calculate_total : t -> bool option

     

       376
       376
       +
         val collapse_threads : t -> bool option

     

       377
       377
       +
         

     

       378
       378
       +
         val v :

     

       379
       379
       +
           account_id:id ->

     

       380
       380
       +
           ?filter:Filter.t ->

     

       381
       381
       +
           ?sort:Comparator.t list ->

     

       382
       382
       +
           since_query_state:string ->

     

       383
       383
       +
           ?max_changes:uint ->

     

       384
       384
       +
           ?up_to_id:id ->

     

       385
       385
       +
           ?calculate_total:bool ->

     

       386
       386
       +
           ?collapse_threads:bool ->

     

       387
       387
       +
           unit ->

     

       388
       388
       +
           t

     

       389
       389
       +
       end

     

       390
       390
       +
       

     

       391
       391
       +
       (** Response for /queryChanges methods.

     

       392
       392
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-5.6> RFC 8620, Section 5.6 *)

     

       393
       393
       +
       module Query_changes_response : sig

     

       394
       394
       +
         type t

     

       395
       395
       +
         

     

       396
       396
       +
         val account_id : t -> id

     

       397
       397
       +
         val old_query_state : t -> string

     

       398
       398
       +
         val new_query_state : t -> string

     

       399
       399
       +
         val total : t -> uint option

     

       400
       400
       +
         val removed : t -> id list

     

       401
       401
       +
         val added : t -> Added_item.t list

     

       402
       402
       +
         

     

       403
       403
       +
         val v :

     

       404
       404
       +
           account_id:id ->

     

       405
       405
       +
           old_query_state:string ->

     

       406
       406
       +
           new_query_state:string ->

     

       407
       407
       +
           ?total:uint ->

     

       408
       408
       +
           removed:id list ->

     

       409
       409
       +
           added:Added_item.t list ->

     

       410
       410
       +
           unit ->

     

       411
       411
       +
           t

     

       412
       412
       +
       end

     

       413
       413
       +
       

     

       414
       414
       +
       (** Core/echo method: Arguments are mirrored in the response.

     

       415
       415
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-4> RFC 8620, Section 4 *)

     

       416
       416
       +
       type core_echo_args = Yojson.Safe.t

     

       417
       417
       +
       type core_echo_response = Yojson.Safe.t

+230

jmap/jmap_push.mli

···

       1
       1
       +
       (** JMAP Push Notifications.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7> RFC 8620, Section 7 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap_types

     

       5
       5
       +
       open Jmap_methods

     

       6
       6
       +
       open Jmap_error

     

       7
       7
       +
       

     

       8
       8
       +
       (** TypeState object map (TypeName -> StateString).

     

       9
       9
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.1> RFC 8620, Section 7.1 *)

     

       10
       10
       +
       type type_state = string string_map

     

       11
       11
       +
       

     

       12
       12
       +
       (** StateChange object.

     

       13
       13
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.1> RFC 8620, Section 7.1 *)

     

       14
       14
       +
       module State_change : sig

     

       15
       15
       +
         type t

     

       16
       16
       +
         

     

       17
       17
       +
         val changed : t -> type_state id_map

     

       18
       18
       +
         

     

       19
       19
       +
         val v :

     

       20
       20
       +
           changed:type_state id_map ->

     

       21
       21
       +
           unit ->

     

       22
       22
       +
           t

     

       23
       23
       +
       end

     

       24
       24
       +
       

     

       25
       25
       +
       (** PushSubscription encryption keys.

     

       26
       26
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2> RFC 8620, Section 7.2 *)

     

       27
       27
       +
       module Push_encryption_keys : sig

     

       28
       28
       +
         type t

     

       29
       29
       +
         

     

       30
       30
       +
         (** P-256 ECDH public key (URL-safe base64) *)

     

       31
       31
       +
         val p256dh : t -> string

     

       32
       32
       +
         

     

       33
       33
       +
         (** Authentication secret (URL-safe base64) *)

     

       34
       34
       +
         val auth : t -> string

     

       35
       35
       +
         

     

       36
       36
       +
         val v :

     

       37
       37
       +
           p256dh:string ->

     

       38
       38
       +
           auth:string ->

     

       39
       39
       +
           unit ->

     

       40
       40
       +
           t

     

       41
       41
       +
       end

     

       42
       42
       +
       

     

       43
       43
       +
       (** PushSubscription object.

     

       44
       44
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2> RFC 8620, Section 7.2 *)

     

       45
       45
       +
       module Push_subscription : sig

     

       46
       46
       +
         type t

     

       47
       47
       +
         

     

       48
       48
       +
         (** Id of the subscription (server-set, immutable) *)

     

       49
       49
       +
         val id : t -> id

     

       50
       50
       +
         

     

       51
       51
       +
         (** Device client id (immutable) *)

     

       52
       52
       +
         val device_client_id : t -> string

     

       53
       53
       +
         

     

       54
       54
       +
         (** Notification URL (immutable) *)

     

       55
       55
       +
         val url : t -> Uri.t

     

       56
       56
       +
         

     

       57
       57
       +
         (** Encryption keys (immutable) *)

     

       58
       58
       +
         val keys : t -> Push_encryption_keys.t option

     

       59
       59
       +
         val verification_code : t -> string option

     

       60
       60
       +
         val expires : t -> utc_date option

     

       61
       61
       +
         val types : t -> string list option

     

       62
       62
       +
         

     

       63
       63
       +
         val v :

     

       64
       64
       +
           id:id ->

     

       65
       65
       +
           device_client_id:string ->

     

       66
       66
       +
           url:Uri.t ->

     

       67
       67
       +
           ?keys:Push_encryption_keys.t ->

     

       68
       68
       +
           ?verification_code:string ->

     

       69
       69
       +
           ?expires:utc_date ->

     

       70
       70
       +
           ?types:string list ->

     

       71
       71
       +
           unit ->

     

       72
       72
       +
           t

     

       73
       73
       +
       end

     

       74
       74
       +
       

     

       75
       75
       +
       (** PushSubscription object for creation (omits server-set fields).

     

       76
       76
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2> RFC 8620, Section 7.2 *)

     

       77
       77
       +
       module Push_subscription_create : sig

     

       78
       78
       +
         type t

     

       79
       79
       +
         

     

       80
       80
       +
         val device_client_id : t -> string

     

       81
       81
       +
         val url : t -> Uri.t

     

       82
       82
       +
         val keys : t -> Push_encryption_keys.t option

     

       83
       83
       +
         val expires : t -> utc_date option

     

       84
       84
       +
         val types : t -> string list option

     

       85
       85
       +
         

     

       86
       86
       +
         val v :

     

       87
       87
       +
           device_client_id:string ->

     

       88
       88
       +
           url:Uri.t ->

     

       89
       89
       +
           ?keys:Push_encryption_keys.t ->

     

       90
       90
       +
           ?expires:utc_date ->

     

       91
       91
       +
           ?types:string list ->

     

       92
       92
       +
           unit ->

     

       93
       93
       +
           t

     

       94
       94
       +
       end

     

       95
       95
       +
       

     

       96
       96
       +
       (** PushSubscription object for update patch.

     

       97
       97
       +
           Only verification_code and expires can be updated.

     

       98
       98
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2> RFC 8620, Section 7.2

     

       99
       99
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2.2> RFC 8620, Section 7.2.2 *)

     

       100
       100
       +
       type push_subscription_update = patch_object

     

       101
       101
       +
       

     

       102
       102
       +
       (** Arguments for PushSubscription/get.

     

       103
       103
       +
           Extends standard /get args.

     

       104
       104
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2.1> RFC 8620, Section 7.2.1 *)

     

       105
       105
       +
       module Push_subscription_get_args : sig

     

       106
       106
       +
         type t

     

       107
       107
       +
         

     

       108
       108
       +
         val ids : t -> id list option

     

       109
       109
       +
         val properties : t -> string list option

     

       110
       110
       +
         

     

       111
       111
       +
         val v :

     

       112
       112
       +
           ?ids:id list ->

     

       113
       113
       +
           ?properties:string list ->

     

       114
       114
       +
           unit ->

     

       115
       115
       +
           t

     

       116
       116
       +
       end

     

       117
       117
       +
       

     

       118
       118
       +
       (** Response for PushSubscription/get.

     

       119
       119
       +
           Extends standard /get response.

     

       120
       120
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2.1> RFC 8620, Section 7.2.1 *)

     

       121
       121
       +
       module Push_subscription_get_response : sig

     

       122
       122
       +
         type t

     

       123
       123
       +
         

     

       124
       124
       +
         val list : t -> Push_subscription.t list

     

       125
       125
       +
         val not_found : t -> id list

     

       126
       126
       +
         

     

       127
       127
       +
         val v :

     

       128
       128
       +
           list:Push_subscription.t list ->

     

       129
       129
       +
           not_found:id list ->

     

       130
       130
       +
           unit ->

     

       131
       131
       +
           t

     

       132
       132
       +
       end

     

       133
       133
       +
       

     

       134
       134
       +
       (** Arguments for PushSubscription/set.

     

       135
       135
       +
           Extends standard /set args.

     

       136
       136
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2.2> RFC 8620, Section 7.2.2 *)

     

       137
       137
       +
       module Push_subscription_set_args : sig

     

       138
       138
       +
         type t

     

       139
       139
       +
         

     

       140
       140
       +
         val create : t -> Push_subscription_create.t id_map option

     

       141
       141
       +
         val update : t -> push_subscription_update id_map option

     

       142
       142
       +
         val destroy : t -> id list option

     

       143
       143
       +
         

     

       144
       144
       +
         val v :

     

       145
       145
       +
           ?create:Push_subscription_create.t id_map ->

     

       146
       146
       +
           ?update:push_subscription_update id_map ->

     

       147
       147
       +
           ?destroy:id list ->

     

       148
       148
       +
           unit ->

     

       149
       149
       +
           t

     

       150
       150
       +
       end

     

       151
       151
       +
       

     

       152
       152
       +
       (** Server-set information for created PushSubscription.

     

       153
       153
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2.2> RFC 8620, Section 7.2.2 *)

     

       154
       154
       +
       module Push_subscription_created_info : sig

     

       155
       155
       +
         type t

     

       156
       156
       +
         

     

       157
       157
       +
         val id : t -> id

     

       158
       158
       +
         val expires : t -> utc_date option

     

       159
       159
       +
         

     

       160
       160
       +
         val v :

     

       161
       161
       +
           id:id ->

     

       162
       162
       +
           ?expires:utc_date ->

     

       163
       163
       +
           unit ->

     

       164
       164
       +
           t

     

       165
       165
       +
       end

     

       166
       166
       +
       

     

       167
       167
       +
       (** Server-set information for updated PushSubscription.

     

       168
       168
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2.2> RFC 8620, Section 7.2.2 *)

     

       169
       169
       +
       module Push_subscription_updated_info : sig

     

       170
       170
       +
         type t

     

       171
       171
       +
         

     

       172
       172
       +
         val expires : t -> utc_date option

     

       173
       173
       +
         

     

       174
       174
       +
         val v :

     

       175
       175
       +
           ?expires:utc_date ->

     

       176
       176
       +
           unit ->

     

       177
       177
       +
           t

     

       178
       178
       +
       end

     

       179
       179
       +
       

     

       180
       180
       +
       (** Response for PushSubscription/set.

     

       181
       181
       +
           Extends standard /set response.

     

       182
       182
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2.2> RFC 8620, Section 7.2.2 *)

     

       183
       183
       +
       module Push_subscription_set_response : sig

     

       184
       184
       +
         type t

     

       185
       185
       +
         

     

       186
       186
       +
         val created : t -> Push_subscription_created_info.t id_map option

     

       187
       187
       +
         val updated : t -> Push_subscription_updated_info.t option id_map option

     

       188
       188
       +
         val destroyed : t -> id list option

     

       189
       189
       +
         val not_created : t -> Set_error.t id_map option

     

       190
       190
       +
         val not_updated : t -> Set_error.t id_map option

     

       191
       191
       +
         val not_destroyed : t -> Set_error.t id_map option

     

       192
       192
       +
         

     

       193
       193
       +
         val v :

     

       194
       194
       +
           ?created:Push_subscription_created_info.t id_map ->

     

       195
       195
       +
           ?updated:Push_subscription_updated_info.t option id_map ->

     

       196
       196
       +
           ?destroyed:id list ->

     

       197
       197
       +
           ?not_created:Set_error.t id_map ->

     

       198
       198
       +
           ?not_updated:Set_error.t id_map ->

     

       199
       199
       +
           ?not_destroyed:Set_error.t id_map ->

     

       200
       200
       +
           unit ->

     

       201
       201
       +
           t

     

       202
       202
       +
       end

     

       203
       203
       +
       

     

       204
       204
       +
       (** PushVerification object.

     

       205
       205
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.2.2> RFC 8620, Section 7.2.2 *)

     

       206
       206
       +
       module Push_verification : sig

     

       207
       207
       +
         type t

     

       208
       208
       +
         

     

       209
       209
       +
         val push_subscription_id : t -> id

     

       210
       210
       +
         val verification_code : t -> string

     

       211
       211
       +
         

     

       212
       212
       +
         val v :

     

       213
       213
       +
           push_subscription_id:id ->

     

       214
       214
       +
           verification_code:string ->

     

       215
       215
       +
           unit ->

     

       216
       216
       +
           t

     

       217
       217
       +
       end

     

       218
       218
       +
       

     

       219
       219
       +
       (** Data for EventSource ping event.

     

       220
       220
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.3> RFC 8620, Section 7.3 *)

     

       221
       221
       +
       module Event_source_ping_data : sig

     

       222
       222
       +
         type t

     

       223
       223
       +
         

     

       224
       224
       +
         val interval : t -> uint

     

       225
       225
       +
         

     

       226
       226
       +
         val v :

     

       227
       227
       +
           interval:uint ->

     

       228
       228
       +
           unit ->

     

       229
       229
       +
           t

     

       230
       230
       +
       end

+98

jmap/jmap_session.mli

···

       1
       1
       +
       (** JMAP Session Resource.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap_types

     

       5
       5
       +
       

     

       6
       6
       +
       (** Account capability information.

     

       7
       7
       +
           The value is capability-specific.

     

       8
       8
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)

     

       9
       9
       +
       type account_capability_value = Yojson.Safe.t

     

       10
       10
       +
       

     

       11
       11
       +
       (** Server capability information.

     

       12
       12
       +
           The value is capability-specific.

     

       13
       13
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)

     

       14
       14
       +
       type server_capability_value = Yojson.Safe.t

     

       15
       15
       +
       

     

       16
       16
       +
       (** Core capability information.

     

       17
       17
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)

     

       18
       18
       +
       module Core_capability : sig

     

       19
       19
       +
         type t

     

       20
       20
       +
         

     

       21
       21
       +
         val max_size_upload : t -> uint

     

       22
       22
       +
         val max_concurrent_upload : t -> uint

     

       23
       23
       +
         val max_size_request : t -> uint

     

       24
       24
       +
         val max_concurrent_requests : t -> uint

     

       25
       25
       +
         val max_calls_in_request : t -> uint

     

       26
       26
       +
         val max_objects_in_get : t -> uint

     

       27
       27
       +
         val max_objects_in_set : t -> uint

     

       28
       28
       +
         val collation_algorithms : t -> string list

     

       29
       29
       +
         

     

       30
       30
       +
         val v :

     

       31
       31
       +
           max_size_upload:uint ->

     

       32
       32
       +
           max_concurrent_upload:uint ->

     

       33
       33
       +
           max_size_request:uint ->

     

       34
       34
       +
           max_concurrent_requests:uint ->

     

       35
       35
       +
           max_calls_in_request:uint ->

     

       36
       36
       +
           max_objects_in_get:uint ->

     

       37
       37
       +
           max_objects_in_set:uint ->

     

       38
       38
       +
           collation_algorithms:string list ->

     

       39
       39
       +
           unit ->

     

       40
       40
       +
           t

     

       41
       41
       +
       end

     

       42
       42
       +
       

     

       43
       43
       +
       (** An Account object.

     

       44
       44
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)

     

       45
       45
       +
       module Account : sig

     

       46
       46
       +
         type t

     

       47
       47
       +
         

     

       48
       48
       +
         val name : t -> string

     

       49
       49
       +
         val is_personal : t -> bool

     

       50
       50
       +
         val is_read_only : t -> bool

     

       51
       51
       +
         val account_capabilities : t -> account_capability_value string_map

     

       52
       52
       +
         

     

       53
       53
       +
         val v :

     

       54
       54
       +
           name:string ->

     

       55
       55
       +
           ?is_personal:bool ->

     

       56
       56
       +
           ?is_read_only:bool ->

     

       57
       57
       +
           ?account_capabilities:account_capability_value string_map ->

     

       58
       58
       +
           unit ->

     

       59
       59
       +
           t

     

       60
       60
       +
       end

     

       61
       61
       +
       

     

       62
       62
       +
       (** The Session object.

     

       63
       63
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)

     

       64
       64
       +
       module Session : sig

     

       65
       65
       +
         type t

     

       66
       66
       +
         

     

       67
       67
       +
         val capabilities : t -> server_capability_value string_map

     

       68
       68
       +
         val accounts : t -> Account.t id_map

     

       69
       69
       +
         val primary_accounts : t -> id string_map

     

       70
       70
       +
         val username : t -> string

     

       71
       71
       +
         val api_url : t -> Uri.t

     

       72
       72
       +
         val download_url : t -> Uri.t

     

       73
       73
       +
         val upload_url : t -> Uri.t

     

       74
       74
       +
         val event_source_url : t -> Uri.t

     

       75
       75
       +
         val state : t -> string

     

       76
       76
       +
         

     

       77
       77
       +
         val v :

     

       78
       78
       +
           capabilities:server_capability_value string_map ->

     

       79
       79
       +
           accounts:Account.t id_map ->

     

       80
       80
       +
           primary_accounts:id string_map ->

     

       81
       81
       +
           username:string ->

     

       82
       82
       +
           api_url:Uri.t ->

     

       83
       83
       +
           download_url:Uri.t ->

     

       84
       84
       +
           upload_url:Uri.t ->

     

       85
       85
       +
           event_source_url:Uri.t ->

     

       86
       86
       +
           state:string ->

     

       87
       87
       +
           unit ->

     

       88
       88
       +
           t

     

       89
       89
       +
       end

     

       90
       90
       +
       

     

       91
       91
       +
       (** Function to perform service autodiscovery.

     

       92
       92
       +
           Returns the session URL if found.

     

       93
       93
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2.2> RFC 8620, Section 2.2 *)

     

       94
       94
       +
       val discover : domain:string -> Uri.t option

     

       95
       95
       +
       

     

       96
       96
       +
       (** Function to fetch the session object from a given URL.

     

       97
       97
       +
           Requires authentication handling (details TBD/outside this signature). *)

     

       98
       98
       +
       val get_session : url:Uri.t -> Session.t

+38

jmap/jmap_types.mli

···

       1
       1
       +
       (** Basic JMAP types as defined in RFC 8620. *)

     

       2
       2
       +
       

     

       3
       3
       +
       (** The Id data type.

     

       4
       4
       +
           A string of 1 to 255 octets, using URL-safe base64 characters.

     

       5
       5
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-1.2> RFC 8620, Section 1.2 *)

     

       6
       6
       +
       type id = string

     

       7
       7
       +
       

     

       8
       8
       +
       (** The Int data type.

     

       9
       9
       +
           An integer in the range [-2^53+1, 2^53-1]. Represented as OCaml's standard [int].

     

       10
       10
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-1.3> RFC 8620, Section 1.3 *)

     

       11
       11
       +
       type jint = int

     

       12
       12
       +
       

     

       13
       13
       +
       (** The UnsignedInt data type.

     

       14
       14
       +
           An integer in the range [0, 2^53-1]. Represented as OCaml's standard [int].

     

       15
       15
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-1.3> RFC 8620, Section 1.3 *)

     

       16
       16
       +
       type uint = int

     

       17
       17
       +
       

     

       18
       18
       +
       (** The Date data type.

     

       19
       19
       +
           A string in RFC 3339 "date-time" format.

     

       20
       20
       +
           Represented as a float using Unix time.

     

       21
       21
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-1.4> RFC 8620, Section 1.4 *)

     

       22
       22
       +
       type date = float

     

       23
       23
       +
       

     

       24
       24
       +
       (** The UTCDate data type.

     

       25
       25
       +
           A string in RFC 3339 "date-time" format, restricted to UTC (Z timezone).

     

       26
       26
       +
           Represented as a float using Unix time.

     

       27
       27
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-1.4> RFC 8620, Section 1.4 *)

     

       28
       28
       +
       type utc_date = float

     

       29
       29
       +
       

     

       30
       30
       +
       (** Represents a JSON object used as a map String -> V. *)

     

       31
       31
       +
       type 'v string_map = (string, 'v) Hashtbl.t

     

       32
       32
       +
       

     

       33
       33
       +
       (** Represents a JSON object used as a map Id -> V. *)

     

       34
       34
       +
       type 'v id_map = (id, 'v) Hashtbl.t

     

       35
       35
       +
       

     

       36
       36
       +
       (** Represents a JSON Pointer path with JMAP extensions.

     

       37
       37
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.7> RFC 8620, Section 3.7 *)

     

       38
       38
       +
       type json_pointer = string

+80

jmap/jmap_wire.mli

···

       1
       1
       +
       (** JMAP Wire Protocol Structures (Request/Response). *)

     

       2
       2
       +
       

     

       3
       3
       +
       open Jmap_types

     

       4
       4
       +
       

     

       5
       5
       +
       (** An invocation tuple within a request or response.

     

       6
       6
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.2> RFC 8620, Section 3.2 *)

     

       7
       7
       +
       module Invocation : sig

     

       8
       8
       +
         type t

     

       9
       9
       +
         

     

       10
       10
       +
         val method_name : t -> string

     

       11
       11
       +
         val arguments : t -> Yojson.Safe.t

     

       12
       12
       +
         val method_call_id : t -> string

     

       13
       13
       +
         

     

       14
       14
       +
         val v : 

     

       15
       15
       +
           ?arguments:Yojson.Safe.t ->

     

       16
       16
       +
           method_name:string ->

     

       17
       17
       +
           method_call_id:string ->

     

       18
       18
       +
           unit ->

     

       19
       19
       +
           t

     

       20
       20
       +
       end

     

       21
       21
       +
       

     

       22
       22
       +
       (** Method error type with context.

     

       23
       23
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.2> RFC 8620, Section 3.6.2 *)

     

       24
       24
       +
       type method_error = Jmap_error.Method_error.t * string

     

       25
       25
       +
       

     

       26
       26
       +
       (** A response invocation part, which can be a standard response or an error.

     

       27
       27
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.4> RFC 8620, Section 3.4

     

       28
       28
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.2> RFC 8620, Section 3.6.2 *)

     

       29
       29
       +
       type response_invocation = (Invocation.t, method_error) result

     

       30
       30
       +
       

     

       31
       31
       +
       (** A reference to a previous method call's result.

     

       32
       32
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.7> RFC 8620, Section 3.7 *)

     

       33
       33
       +
       module Result_reference : sig

     

       34
       34
       +
         type t

     

       35
       35
       +
         

     

       36
       36
       +
         val result_of : t -> string

     

       37
       37
       +
         val name : t -> string

     

       38
       38
       +
         val path : t -> json_pointer

     

       39
       39
       +
         

     

       40
       40
       +
         val v :

     

       41
       41
       +
           result_of:string ->

     

       42
       42
       +
           name:string ->

     

       43
       43
       +
           path:json_pointer ->

     

       44
       44
       +
           unit ->

     

       45
       45
       +
           t

     

       46
       46
       +
       end

     

       47
       47
       +
       

     

       48
       48
       +
       (** The Request object.

     

       49
       49
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.3> RFC 8620, Section 3.3 *)

     

       50
       50
       +
       module Request : sig

     

       51
       51
       +
         type t

     

       52
       52
       +
         

     

       53
       53
       +
         val using : t -> string list

     

       54
       54
       +
         val method_calls : t -> Invocation.t list

     

       55
       55
       +
         val created_ids : t -> id id_map option

     

       56
       56
       +
         

     

       57
       57
       +
         val v :

     

       58
       58
       +
           using:string list ->

     

       59
       59
       +
           method_calls:Invocation.t list ->

     

       60
       60
       +
           ?created_ids:id id_map ->

     

       61
       61
       +
           unit ->

     

       62
       62
       +
           t

     

       63
       63
       +
       end

     

       64
       64
       +
       

     

       65
       65
       +
       (** The Response object.

     

       66
       66
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.4> RFC 8620, Section 3.4 *)

     

       67
       67
       +
       module Response : sig

     

       68
       68
       +
         type t

     

       69
       69
       +
         

     

       70
       70
       +
         val method_responses : t -> response_invocation list

     

       71
       71
       +
         val created_ids : t -> id id_map option

     

       72
       72
       +
         val session_state : t -> string

     

       73
       73
       +
         

     

       74
       74
       +
         val v :

     

       75
       75
       +
           method_responses:response_invocation list ->

     

       76
       76
       +
           ?created_ids:id id_map ->

     

       77
       77
       +
           session_state:string ->

     

       78
       78
       +
           unit ->

     

       79
       79
       +
           t

     

       80
       80
       +
       end

+15

jmap-email/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name jmap_email)

     

       3
       3
       +
        (public_name jmap-email)

     

       4
       4
       +
        (libraries jmap yojson uri)

     

       5
       5
       +
        (modules_without_implementation jmap_email jmap_email_types jmap_identity

     

       6
       6
       +
         jmap_mailbox jmap_search_snippet jmap_submission jmap_thread jmap_vacation)

     

       7
       7
       +
        (modules

     

       8
       8
       +
         jmap_email

     

       9
       9
       +
         jmap_email_types

     

       10
       10
       +
         jmap_mailbox

     

       11
       11
       +
         jmap_thread

     

       12
       12
       +
         jmap_search_snippet

     

       13
       13
       +
         jmap_identity

     

       14
       14
       +
         jmap_submission

     

       15
       15
       +
         jmap_vacation))

+503

jmap-email/jmap_email.mli

···

       1
       1
       +
       (** JMAP Mail Extension Library (RFC 8621).

     

       2
       2
       +
       

     

       3
       3
       +
           This library extends the core JMAP protocol with email-specific

     

       4
       4
       +
           functionality as defined in RFC 8621. It provides types and signatures

     

       5
       5
       +
           for interacting with JMAP Mail data types: Mailbox, Thread, Email, 

     

       6
       6
       +
           SearchSnippet, Identity, EmailSubmission, and VacationResponse.

     

       7
       7
       +
           

     

       8
       8
       +
           Requires the core Jmap library and Jmap_unix library for network operations.

     

       9
       9
       +
           

     

       10
       10
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html> RFC 8621: JMAP for Mail

     

       11
       11
       +
       *)

     

       12
       12
       +
       

     

       13
       13
       +
       open Jmap.Types

     

       14
       14
       +
       

     

       15
       15
       +
       (** {1 Core Types} *)

     

       16
       16
       +
       module Types = Jmap_email_types

     

       17
       17
       +
       

     

       18
       18
       +
       (** {1 Mailbox} 

     

       19
       19
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)

     

       20
       20
       +
       module Mailbox = Jmap_mailbox

     

       21
       21
       +
       

     

       22
       22
       +
       (** {1 Thread}

     

       23
       23
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-3> RFC 8621, Section 3 *)

     

       24
       24
       +
       module Thread = Jmap_thread

     

       25
       25
       +
       

     

       26
       26
       +
       (** {1 Search Snippet}

     

       27
       27
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5> RFC 8621, Section 5 *)

     

       28
       28
       +
       module SearchSnippet = Jmap_search_snippet

     

       29
       29
       +
       

     

       30
       30
       +
       (** {1 Identity}

     

       31
       31
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6> RFC 8621, Section 6 *)

     

       32
       32
       +
       module Identity = Jmap_identity

     

       33
       33
       +
       

     

       34
       34
       +
       (** {1 Email Submission}

     

       35
       35
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)

     

       36
       36
       +
       module Submission = Jmap_submission

     

       37
       37
       +
       

     

       38
       38
       +
       (** {1 Vacation Response}

     

       39
       39
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8> RFC 8621, Section 8 *)

     

       40
       40
       +
       module Vacation = Jmap_vacation

     

       41
       41
       +
       

     

       42
       42
       +
       (** {1 Example Usage}

     

       43
       43
       +
       

     

       44
       44
       +
           The following example demonstrates using the JMAP Email library to fetch unread emails

     

       45
       45
       +
           from a specific sender.

     

       46
       46
       +
       

     

       47
       47
       +
       {[

     

       48
       48
       +
         (* OCaml 5.1 required for Lwt let operators *)

     

       49
       49
       +
         open Lwt.Syntax

     

       50
       50
       +
         open Jmap

     

       51
       51
       +
         open Jmap.Types

     

       52
       52
       +
         open Jmap.Wire

     

       53
       53
       +
         open Jmap.Methods

     

       54
       54
       +
         open Jmap_email

     

       55
       55
       +
         open Jmap.Unix

     

       56
       56
       +
         

     

       57
       57
       +
         let list_unread_from_sender ctx session sender_email =

     

       58
       58
       +
           (* Find the primary mail account *)

     

       59
       59
       +
           let primary_mail_account_id =

     

       60
       60
       +
             Hashtbl.find session.primary_accounts capability_mail

     

       61
       61
       +
           in

     

       62
       62
       +
           (* Construct the filter *)

     

       63
       63
       +
           let filter : filter =

     

       64
       64
       +
             Filter_operator (Filter_operator.v

     

       65
       65
       +
               ~operator:`AND

     

       66
       66
       +
               ~conditions:[

     

       67
       67
       +
                 Filter_condition (Yojson.Safe.to_basic (`Assoc [

     

       68
       68
       +
                   ("from", `String sender_email);

     

       69
       69
       +
                 ]));

     

       70
       70
       +
                 Filter_condition (Yojson.Safe.to_basic (`Assoc [

     

       71
       71
       +
                   ("hasKeyword", `String keyword_seen);

     

       72
       72
       +
                   ("value", `Bool false);

     

       73
       73
       +
                 ]));

     

       74
       74
       +
               ]

     

       75
       75
       +
               ())

     

       76
       76
       +
           in

     

       77
       77
       +
           (* Prepare the Email/query invocation *)

     

       78
       78
       +
           let query_args = Query_args.v

     

       79
       79
       +
             ~account_id:primary_mail_account_id

     

       80
       80
       +
             ~filter

     

       81
       81
       +
             ~sort:[

     

       82
       82
       +
               Comparator.v

     

       83
       83
       +
                 ~property:"receivedAt"

     

       84
       84
       +
                 ~is_ascending:false

     

       85
       85
       +
                 ()

     

       86
       86
       +
             ]

     

       87
       87
       +
             ~position:0

     

       88
       88
       +
             ~limit:20 (* Get latest 20 *)

     

       89
       89
       +
             ~calculate_total:false

     

       90
       90
       +
             ~collapse_threads:false

     

       91
       91
       +
             ()

     

       92
       92
       +
           in

     

       93
       93
       +
           let query_invocation = Invocation.v

     

       94
       94
       +
             ~method_name:"Email/query"

     

       95
       95
       +
             ~arguments:(* Yojson conversion of query_args needed here *)

     

       96
       96
       +
             ~method_call_id:"q1"

     

       97
       97
       +
             ()

     

       98
       98
       +
           in

     

       99
       99
       +
       

     

       100
       100
       +
           (* Prepare the Email/get invocation using a back-reference *)

     

       101
       101
       +
           let get_args = Get_args.v

     

       102
       102
       +
             ~account_id:primary_mail_account_id

     

       103
       103
       +
             ~properties:["id"; "subject"; "receivedAt"; "from"]

     

       104
       104
       +
             ()

     

       105
       105
       +
           in

     

       106
       106
       +
           let get_invocation = Invocation.v

     

       107
       107
       +
             ~method_name:"Email/get"

     

       108
       108
       +
             ~arguments:(* Yojson conversion of get_args, with ids replaced by a ResultReference to q1 needed here *)

     

       109
       109
       +
             ~method_call_id:"g1"

     

       110
       110
       +
             ()

     

       111
       111
       +
           in

     

       112
       112
       +
       

     

       113
       113
       +
           (* Prepare the JMAP request *)

     

       114
       114
       +
           let request = Request.v

     

       115
       115
       +
             ~using:[ Jmap.capability_core; capability_mail ]

     

       116
       116
       +
             ~method_calls:[ query_invocation; get_invocation ]

     

       117
       117
       +
             ()

     

       118
       118
       +
           in

     

       119
       119
       +
       

     

       120
       120
       +
           (* Send the request *)

     

       121
       121
       +
           let* response = Jmap.Unix.request ctx request in

     

       122
       122
       +
       

     

       123
       123
       +
           (* Process the response (extract Email/get results) *)

     

       124
       124
       +
           (* ... Omitted: find the Email/get response in response.method_responses ... *)

     

       125
       125
       +
           Lwt.return_unit

     

       126
       126
       +
       ]}

     

       127
       127
       +
       *)

     

       128
       128
       +
       

     

       129
       129
       +
       (** Capability URI for JMAP Mail.

     

       130
       130
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-1.3.1> RFC 8621, Section 1.3.1 *)

     

       131
       131
       +
       val capability_mail : string

     

       132
       132
       +
       

     

       133
       133
       +
       (** Capability URI for JMAP Submission.

     

       134
       134
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-1.3.2> RFC 8621, Section 1.3.2 *)

     

       135
       135
       +
       val capability_submission : string

     

       136
       136
       +
       

     

       137
       137
       +
       (** Capability URI for JMAP Vacation Response.

     

       138
       138
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-1.3.3> RFC 8621, Section 1.3.3 *)

     

       139
       139
       +
       val capability_vacationresponse : string

     

       140
       140
       +
       

     

       141
       141
       +
       (** Type name for EmailDelivery push notifications.

     

       142
       142
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-1.5> RFC 8621, Section 1.5 *)

     

       143
       143
       +
       val push_event_type_email_delivery : string

     

       144
       144
       +
       

     

       145
       145
       +
       (** Keyword string constants for JMAP email flags.

     

       146
       146
       +
           Provides easy access to standardized keyword string values.

     

       147
       147
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.1> RFC 8621, Section 4.1.1 *)

     

       148
       148
       +
       module Keyword : sig

     

       149
       149
       +
         (** {1 IMAP System Flags} *)

     

       150
       150
       +
         

     

       151
       151
       +
         (** "$draft": The Email is a draft the user is composing *)

     

       152
       152
       +
         val draft : string

     

       153
       153
       +
         

     

       154
       154
       +
         (** "$seen": The Email has been read *)

     

       155
       155
       +
         val seen : string

     

       156
       156
       +
         

     

       157
       157
       +
         (** "$flagged": The Email has been flagged for urgent/special attention *)

     

       158
       158
       +
         val flagged : string

     

       159
       159
       +
         

     

       160
       160
       +
         (** "$answered": The Email has been replied to *)

     

       161
       161
       +
         val answered : string

     

       162
       162
       +
         

     

       163
       163
       +
         (** {1 Common Extension Keywords} *)

     

       164
       164
       +
         

     

       165
       165
       +
         (** "$forwarded": The Email has been forwarded *)

     

       166
       166
       +
         val forwarded : string

     

       167
       167
       +
         

     

       168
       168
       +
         (** "$phishing": The Email is likely to be phishing *)

     

       169
       169
       +
         val phishing : string

     

       170
       170
       +
         

     

       171
       171
       +
         (** "$junk": The Email is spam/junk *)

     

       172
       172
       +
         val junk : string

     

       173
       173
       +
         

     

       174
       174
       +
         (** "$notjunk": The Email is explicitly marked as not spam/junk *)

     

       175
       175
       +
         val notjunk : string

     

       176
       176
       +
         

     

       177
       177
       +
         (** {1 Apple Mail and Vendor Extensions} 

     

       178
       178
       +
             @see <https://datatracker.ietf.org/doc/draft-ietf-mailmaint-messageflag-mailboxattribute/> *)

     

       179
       179
       +
         

     

       180
       180
       +
         (** "$notify": Request to be notified when this email gets a reply *)

     

       181
       181
       +
         val notify : string

     

       182
       182
       +
         

     

       183
       183
       +
         (** "$muted": Email is muted (notifications disabled) *)

     

       184
       184
       +
         val muted : string

     

       185
       185
       +
         

     

       186
       186
       +
         (** "$followed": Email thread is followed for notifications *)

     

       187
       187
       +
         val followed : string

     

       188
       188
       +
         

     

       189
       189
       +
         (** "$memo": Email has a memo/note associated with it *)

     

       190
       190
       +
         val memo : string

     

       191
       191
       +
         

     

       192
       192
       +
         (** "$hasmemo": Email has a memo, annotation or note property *)

     

       193
       193
       +
         val hasmemo : string

     

       194
       194
       +
         

     

       195
       195
       +
         (** "$autosent": Email was generated or sent automatically *)

     

       196
       196
       +
         val autosent : string

     

       197
       197
       +
         

     

       198
       198
       +
         (** "$unsubscribed": User has unsubscribed from this sender *)

     

       199
       199
       +
         val unsubscribed : string

     

       200
       200
       +
         

     

       201
       201
       +
         (** "$canunsubscribe": Email contains unsubscribe information *)

     

       202
       202
       +
         val canunsubscribe : string

     

       203
       203
       +
         

     

       204
       204
       +
         (** "$imported": Email was imported from another system *)

     

       205
       205
       +
         val imported : string

     

       206
       206
       +
         

     

       207
       207
       +
         (** "$istrusted": Email is from a trusted/verified sender *)

     

       208
       208
       +
         val istrusted : string

     

       209
       209
       +
         

     

       210
       210
       +
         (** "$maskedemail": Email is to/from a masked/anonymous address *)

     

       211
       211
       +
         val maskedemail : string

     

       212
       212
       +
         

     

       213
       213
       +
         (** "$new": Email was recently delivered *)

     

       214
       214
       +
         val new_mail : string

     

       215
       215
       +
         

     

       216
       216
       +
         (** {1 Apple Mail Color Flag Bits} *)

     

       217
       217
       +
         

     

       218
       218
       +
         (** "$MailFlagBit0": First color flag bit (red) *)

     

       219
       219
       +
         val mailflagbit0 : string

     

       220
       220
       +
         

     

       221
       221
       +
         (** "$MailFlagBit1": Second color flag bit (orange) *)

     

       222
       222
       +
         val mailflagbit1 : string

     

       223
       223
       +
         

     

       224
       224
       +
         (** "$MailFlagBit2": Third color flag bit (yellow) *)

     

       225
       225
       +
         val mailflagbit2 : string

     

       226
       226
       +
         

     

       227
       227
       +
         (** {1 Color Flag Combinations} *)

     

       228
       228
       +
         

     

       229
       229
       +
         (** Get color flag bit values for a specific color 

     

       230
       230
       +
             @return A list of flags to set to create the requested color *)

     

       231
       231
       +
         val color_flags : [`Red | `Orange | `Yellow | `Green | `Blue | `Purple | `Gray] -> string list

     

       232
       232
       +
         

     

       233
       233
       +
         (** Check if a string is a valid keyword according to the RFC

     

       234
       234
       +
             @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.1> RFC 8621, Section 4.1.1 *)

     

       235
       235
       +
         val is_valid : string -> bool

     

       236
       236
       +
       end

     

       237
       237
       +
       

     

       238
       238
       +
       (** For backward compatibility - DEPRECATED, use Keyword.draft instead *)

     

       239
       239
       +
       val keyword_draft : string

     

       240
       240
       +
       

     

       241
       241
       +
       (** For backward compatibility - DEPRECATED, use Keyword.seen instead *)

     

       242
       242
       +
       val keyword_seen : string

     

       243
       243
       +
       

     

       244
       244
       +
       (** For backward compatibility - DEPRECATED, use Keyword.flagged instead *)

     

       245
       245
       +
       val keyword_flagged : string

     

       246
       246
       +
       

     

       247
       247
       +
       (** For backward compatibility - DEPRECATED, use Keyword.answered instead *)

     

       248
       248
       +
       val keyword_answered : string

     

       249
       249
       +
       

     

       250
       250
       +
       (** For backward compatibility - DEPRECATED, use Keyword.forwarded instead *)

     

       251
       251
       +
       val keyword_forwarded : string

     

       252
       252
       +
       

     

       253
       253
       +
       (** For backward compatibility - DEPRECATED, use Keyword.phishing instead *)

     

       254
       254
       +
       val keyword_phishing : string

     

       255
       255
       +
       

     

       256
       256
       +
       (** For backward compatibility - DEPRECATED, use Keyword.junk instead *)

     

       257
       257
       +
       val keyword_junk : string

     

       258
       258
       +
       

     

       259
       259
       +
       (** For backward compatibility - DEPRECATED, use Keyword.notjunk instead *)

     

       260
       260
       +
       val keyword_notjunk : string

     

       261
       261
       +
       

     

       262
       262
       +
       (** Email keyword operations.

     

       263
       263
       +
           Functions to manipulate and update email keywords/flags. *)

     

       264
       264
       +
       module Keyword_ops : sig

     

       265
       265
       +
         (** Add a keyword/flag to an email *)

     

       266
       266
       +
         val add : Types.Email.t -> Types.Keywords.keyword -> Types.Email.t

     

       267
       267
       +
         

     

       268
       268
       +
         (** Remove a keyword/flag from an email *)

     

       269
       269
       +
         val remove : Types.Email.t -> Types.Keywords.keyword -> Types.Email.t

     

       270
       270
       +
         

     

       271
       271
       +
         (** {1 System Flag Operations} *)

     

       272
       272
       +
         

     

       273
       273
       +
         (** Mark an email as seen/read *)

     

       274
       274
       +
         val mark_as_seen : Types.Email.t -> Types.Email.t

     

       275
       275
       +
         

     

       276
       276
       +
         (** Mark an email as unseen/unread *)

     

       277
       277
       +
         val mark_as_unseen : Types.Email.t -> Types.Email.t

     

       278
       278
       +
         

     

       279
       279
       +
         (** Mark an email as flagged/important *)

     

       280
       280
       +
         val mark_as_flagged : Types.Email.t -> Types.Email.t

     

       281
       281
       +
         

     

       282
       282
       +
         (** Remove flagged/important marking from an email *)

     

       283
       283
       +
         val unmark_flagged : Types.Email.t -> Types.Email.t

     

       284
       284
       +
         

     

       285
       285
       +
         (** Mark an email as a draft *)

     

       286
       286
       +
         val mark_as_draft : Types.Email.t -> Types.Email.t

     

       287
       287
       +
         

     

       288
       288
       +
         (** Remove draft marking from an email *)

     

       289
       289
       +
         val unmark_draft : Types.Email.t -> Types.Email.t

     

       290
       290
       +
         

     

       291
       291
       +
         (** Mark an email as answered/replied *)

     

       292
       292
       +
         val mark_as_answered : Types.Email.t -> Types.Email.t

     

       293
       293
       +
         

     

       294
       294
       +
         (** Remove answered/replied marking from an email *)

     

       295
       295
       +
         val unmark_answered : Types.Email.t -> Types.Email.t

     

       296
       296
       +
         

     

       297
       297
       +
         (** Mark an email as forwarded *)

     

       298
       298
       +
         val mark_as_forwarded : Types.Email.t -> Types.Email.t

     

       299
       299
       +
         

     

       300
       300
       +
         (** Mark an email as spam/junk *)

     

       301
       301
       +
         val mark_as_junk : Types.Email.t -> Types.Email.t

     

       302
       302
       +
         

     

       303
       303
       +
         (** Mark an email as not spam/junk *)

     

       304
       304
       +
         val mark_as_not_junk : Types.Email.t -> Types.Email.t

     

       305
       305
       +
         

     

       306
       306
       +
         (** Mark an email as phishing *)

     

       307
       307
       +
         val mark_as_phishing : Types.Email.t -> Types.Email.t

     

       308
       308
       +
         

     

       309
       309
       +
         (** {1 Extension Flag Operations} *)

     

       310
       310
       +
         

     

       311
       311
       +
         (** Mark an email for notification when replied to *)

     

       312
       312
       +
         val mark_as_notify : Types.Email.t -> Types.Email.t

     

       313
       313
       +
         

     

       314
       314
       +
         (** Remove notification flag from an email *)

     

       315
       315
       +
         val unmark_notify : Types.Email.t -> Types.Email.t

     

       316
       316
       +
         

     

       317
       317
       +
         (** Mark an email as muted (no notifications) *)

     

       318
       318
       +
         val mark_as_muted : Types.Email.t -> Types.Email.t

     

       319
       319
       +
         

     

       320
       320
       +
         (** Unmute an email (allow notifications) *)

     

       321
       321
       +
         val unmark_muted : Types.Email.t -> Types.Email.t

     

       322
       322
       +
         

     

       323
       323
       +
         (** Mark an email thread as followed for notifications *)

     

       324
       324
       +
         val mark_as_followed : Types.Email.t -> Types.Email.t

     

       325
       325
       +
         

     

       326
       326
       +
         (** Remove followed status from an email thread *)

     

       327
       327
       +
         val unmark_followed : Types.Email.t -> Types.Email.t

     

       328
       328
       +
         

     

       329
       329
       +
         (** Mark an email with a memo *)

     

       330
       330
       +
         val mark_as_memo : Types.Email.t -> Types.Email.t

     

       331
       331
       +
         

     

       332
       332
       +
         (** Mark an email with the hasmemo flag *)

     

       333
       333
       +
         val mark_as_hasmemo : Types.Email.t -> Types.Email.t

     

       334
       334
       +
         

     

       335
       335
       +
         (** Mark an email as automatically sent *)

     

       336
       336
       +
         val mark_as_autosent : Types.Email.t -> Types.Email.t

     

       337
       337
       +
         

     

       338
       338
       +
         (** Mark an email as being from an unsubscribed sender *)

     

       339
       339
       +
         val mark_as_unsubscribed : Types.Email.t -> Types.Email.t

     

       340
       340
       +
         

     

       341
       341
       +
         (** Mark an email as having unsubscribe capability *)

     

       342
       342
       +
         val mark_as_canunsubscribe : Types.Email.t -> Types.Email.t

     

       343
       343
       +
         

     

       344
       344
       +
         (** Mark an email as imported from another system *)

     

       345
       345
       +
         val mark_as_imported : Types.Email.t -> Types.Email.t

     

       346
       346
       +
         

     

       347
       347
       +
         (** Mark an email as from a trusted/verified sender *)

     

       348
       348
       +
         val mark_as_trusted : Types.Email.t -> Types.Email.t

     

       349
       349
       +
         

     

       350
       350
       +
         (** Mark an email as having masked/anonymous address *)

     

       351
       351
       +
         val mark_as_maskedemail : Types.Email.t -> Types.Email.t

     

       352
       352
       +
         

     

       353
       353
       +
         (** Mark an email as new/recent *)

     

       354
       354
       +
         val mark_as_new : Types.Email.t -> Types.Email.t

     

       355
       355
       +
         

     

       356
       356
       +
         (** Remove new/recent flag from an email *)

     

       357
       357
       +
         val unmark_new : Types.Email.t -> Types.Email.t

     

       358
       358
       +
         

     

       359
       359
       +
         (** {1 Color Flag Operations} *)

     

       360
       360
       +
         

     

       361
       361
       +
         (** Set color flag bits on an email *)

     

       362
       362
       +
         val set_color_flags : Types.Email.t -> red:bool -> orange:bool -> yellow:bool -> Types.Email.t

     

       363
       363
       +
         

     

       364
       364
       +
         (** Mark an email with a predefined color *)

     

       365
       365
       +
         val mark_as_color : Types.Email.t -> 

     

       366
       366
       +
           [`Red | `Orange | `Yellow | `Green | `Blue | `Purple | `Gray] -> Types.Email.t

     

       367
       367
       +
         

     

       368
       368
       +
         (** Remove all color flag bits from an email *)

     

       369
       369
       +
         val clear_color_flags : Types.Email.t -> Types.Email.t

     

       370
       370
       +
         

     

       371
       371
       +
         (** {1 Custom Flag Operations} *)

     

       372
       372
       +
         

     

       373
       373
       +
         (** Add a custom keyword to an email *)

     

       374
       374
       +
         val add_custom : Types.Email.t -> string -> Types.Email.t

     

       375
       375
       +
         

     

       376
       376
       +
         (** Remove a custom keyword from an email *)

     

       377
       377
       +
         val remove_custom : Types.Email.t -> string -> Types.Email.t

     

       378
       378
       +
       

     

       379
       379
       +
         (** {1 Patch Object Creation} *)

     

       380
       380
       +
       

     

       381
       381
       +
         (** Create a patch object to add a keyword to emails *)

     

       382
       382
       +
         val add_keyword_patch : Types.Keywords.keyword -> Jmap.Methods.patch_object

     

       383
       383
       +
       

     

       384
       384
       +
         (** Create a patch object to remove a keyword from emails *)

     

       385
       385
       +
         val remove_keyword_patch : Types.Keywords.keyword -> Jmap.Methods.patch_object

     

       386
       386
       +
       

     

       387
       387
       +
         (** Create a patch object to mark emails as seen/read *)

     

       388
       388
       +
         val mark_seen_patch : unit -> Jmap.Methods.patch_object

     

       389
       389
       +
       

     

       390
       390
       +
         (** Create a patch object to mark emails as unseen/unread *)

     

       391
       391
       +
         val mark_unseen_patch : unit -> Jmap.Methods.patch_object

     

       392
       392
       +
         

     

       393
       393
       +
         (** Create a patch object to set a specific color on emails *)

     

       394
       394
       +
         val set_color_patch : [`Red | `Orange | `Yellow | `Green | `Blue | `Purple | `Gray] -> 

     

       395
       395
       +
           Jmap.Methods.patch_object

     

       396
       396
       +
       end

     

       397
       397
       +
       

     

       398
       398
       +
       (** Conversion functions for JMAP/IMAP compatibility *)

     

       399
       399
       +
       module Conversion : sig

     

       400
       400
       +
         (** {1 Keyword/Flag Conversion} *)

     

       401
       401
       +
         

     

       402
       402
       +
         (** Convert a JMAP keyword variant to IMAP flag *)

     

       403
       403
       +
         val keyword_to_imap_flag : Types.Keywords.keyword -> string

     

       404
       404
       +
         

     

       405
       405
       +
         (** Convert an IMAP flag to JMAP keyword variant *)

     

       406
       406
       +
         val imap_flag_to_keyword : string -> Types.Keywords.keyword

     

       407
       407
       +
         

     

       408
       408
       +
         (** Check if a string is valid for use as a custom keyword according to RFC 8621.

     

       409
       409
       +
             @deprecated Use Keyword.is_valid instead. *)

     

       410
       410
       +
         val is_valid_custom_keyword : string -> bool

     

       411
       411
       +
         

     

       412
       412
       +
         (** Get the JMAP protocol string representation of a keyword *)

     

       413
       413
       +
         val keyword_to_string : Types.Keywords.keyword -> string

     

       414
       414
       +
         

     

       415
       415
       +
         (** Parse a JMAP protocol string into a keyword variant *)

     

       416
       416
       +
         val string_to_keyword : string -> Types.Keywords.keyword

     

       417
       417
       +
         

     

       418
       418
       +
         (** {1 Color Conversion} *)

     

       419
       419
       +
         

     

       420
       420
       +
         (** Convert a color name to the corresponding flag bit combination *)

     

       421
       421
       +
         val color_to_flags : [`Red | `Orange | `Yellow | `Green | `Blue | `Purple | `Gray] -> 

     

       422
       422
       +
           Types.Keywords.keyword list

     

       423
       423
       +
           

     

       424
       424
       +
         (** Try to determine a color from a set of keywords *)

     

       425
       425
       +
         val keywords_to_color : Types.Keywords.t -> 

     

       426
       426
       +
           [`Red | `Orange | `Yellow | `Green | `Blue | `Purple | `Gray | `None] option

     

       427
       427
       +
       end

     

       428
       428
       +
       

     

       429
       429
       +
       (** {1 Helper Functions} *)

     

       430
       430
       +
       

     

       431
       431
       +
       (** Email query filter helpers *)

     

       432
       432
       +
       module Email_filter : sig

     

       433
       433
       +
         (** Create a filter to find messages in a specific mailbox *)

     

       434
       434
       +
         val in_mailbox : id -> Jmap.Methods.Filter.t

     

       435
       435
       +
         

     

       436
       436
       +
         (** Create a filter to find messages with a specific keyword/flag *)

     

       437
       437
       +
         val has_keyword : Types.Keywords.keyword -> Jmap.Methods.Filter.t

     

       438
       438
       +
         

     

       439
       439
       +
         (** Create a filter to find messages without a specific keyword/flag *)

     

       440
       440
       +
         val not_has_keyword : Types.Keywords.keyword -> Jmap.Methods.Filter.t

     

       441
       441
       +
         

     

       442
       442
       +
         (** Create a filter to find unread messages *)

     

       443
       443
       +
         val unread : unit -> Jmap.Methods.Filter.t

     

       444
       444
       +
         

     

       445
       445
       +
         (** Create a filter to find messages with a specific subject *)

     

       446
       446
       +
         val subject : string -> Jmap.Methods.Filter.t

     

       447
       447
       +
         

     

       448
       448
       +
         (** Create a filter to find messages from a specific sender *)

     

       449
       449
       +
         val from : string -> Jmap.Methods.Filter.t

     

       450
       450
       +
         

     

       451
       451
       +
         (** Create a filter to find messages sent to a specific recipient *)

     

       452
       452
       +
         val to_ : string -> Jmap.Methods.Filter.t

     

       453
       453
       +
         

     

       454
       454
       +
         (** Create a filter to find messages with attachments *)

     

       455
       455
       +
         val has_attachment : unit -> Jmap.Methods.Filter.t

     

       456
       456
       +
         

     

       457
       457
       +
         (** Create a filter to find messages received before a date *)

     

       458
       458
       +
         val before : date -> Jmap.Methods.Filter.t

     

       459
       459
       +
         

     

       460
       460
       +
         (** Create a filter to find messages received after a date *)

     

       461
       461
       +
         val after : date -> Jmap.Methods.Filter.t

     

       462
       462
       +
         

     

       463
       463
       +
         (** Create a filter to find messages with size larger than the given bytes *)

     

       464
       464
       +
         val larger_than : uint -> Jmap.Methods.Filter.t

     

       465
       465
       +
         

     

       466
       466
       +
         (** Create a filter to find messages with size smaller than the given bytes *)

     

       467
       467
       +
         val smaller_than : uint -> Jmap.Methods.Filter.t

     

       468
       468
       +
       end

     

       469
       469
       +
       

     

       470
       470
       +
       (** Common email sorting comparators *)

     

       471
       471
       +
       module Email_sort : sig

     

       472
       472
       +
         (** Sort by received date (most recent first) *)

     

       473
       473
       +
         val received_newest_first : unit -> Jmap.Methods.Comparator.t

     

       474
       474
       +
         

     

       475
       475
       +
         (** Sort by received date (oldest first) *)

     

       476
       476
       +
         val received_oldest_first : unit -> Jmap.Methods.Comparator.t

     

       477
       477
       +
         

     

       478
       478
       +
         (** Sort by sent date (most recent first) *)

     

       479
       479
       +
         val sent_newest_first : unit -> Jmap.Methods.Comparator.t

     

       480
       480
       +
         

     

       481
       481
       +
         (** Sort by sent date (oldest first) *)

     

       482
       482
       +
         val sent_oldest_first : unit -> Jmap.Methods.Comparator.t

     

       483
       483
       +
         

     

       484
       484
       +
         (** Sort by subject (A-Z) *)

     

       485
       485
       +
         val subject_asc : unit -> Jmap.Methods.Comparator.t

     

       486
       486
       +
         

     

       487
       487
       +
         (** Sort by subject (Z-A) *)

     

       488
       488
       +
         val subject_desc : unit -> Jmap.Methods.Comparator.t

     

       489
       489
       +
         

     

       490
       490
       +
         (** Sort by size (largest first) *)

     

       491
       491
       +
         val size_largest_first : unit -> Jmap.Methods.Comparator.t

     

       492
       492
       +
         

     

       493
       493
       +
         (** Sort by size (smallest first) *)

     

       494
       494
       +
         val size_smallest_first : unit -> Jmap.Methods.Comparator.t

     

       495
       495
       +
         

     

       496
       496
       +
         (** Sort by from address (A-Z) *)

     

       497
       497
       +
         val from_asc : unit -> Jmap.Methods.Comparator.t

     

       498
       498
       +
         

     

       499
       499
       +
         (** Sort by from address (Z-A) *)

     

       500
       500
       +
         val from_desc : unit -> Jmap.Methods.Comparator.t

     

       501
       501
       +
       end

     

       502
       502
       +
       

     

       503
       503
       +
       (** High-level email operations are implemented in the Jmap.Unix.Email module *)

+519

jmap-email/jmap_email_types.mli

···

       1
       1
       +
       (** Common types for JMAP Mail (RFC 8621). *)

     

       2
       2
       +
       

     

       3
       3
       +
       open Jmap.Types

     

       4
       4
       +
       

     

       5
       5
       +
       (** Represents an email address with an optional name.

     

       6
       6
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.3> RFC 8621, Section 4.1.2.3 *)

     

       7
       7
       +
       module Email_address : sig

     

       8
       8
       +
         type t

     

       9
       9
       +
       

     

       10
       10
       +
         (** Get the display name for the address (if any) *)

     

       11
       11
       +
         val name : t -> string option

     

       12
       12
       +
         

     

       13
       13
       +
         (** Get the email address *)

     

       14
       14
       +
         val email : t -> string

     

       15
       15
       +
         

     

       16
       16
       +
         (** Create a new email address *)

     

       17
       17
       +
         val v : 

     

       18
       18
       +
           ?name:string -> 

     

       19
       19
       +
           email:string -> 

     

       20
       20
       +
           unit -> t

     

       21
       21
       +
       end

     

       22
       22
       +
       

     

       23
       23
       +
       (** Represents a group of email addresses.

     

       24
       24
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.2.4> RFC 8621, Section 4.1.2.4 *)

     

       25
       25
       +
       module Email_address_group : sig

     

       26
       26
       +
         type t

     

       27
       27
       +
         

     

       28
       28
       +
         (** Get the name of the group (if any) *)

     

       29
       29
       +
         val name : t -> string option

     

       30
       30
       +
         

     

       31
       31
       +
         (** Get the list of addresses in the group *)

     

       32
       32
       +
         val addresses : t -> Email_address.t list

     

       33
       33
       +
         

     

       34
       34
       +
         (** Create a new address group *)

     

       35
       35
       +
         val v : 

     

       36
       36
       +
           ?name:string -> 

     

       37
       37
       +
           addresses:Email_address.t list -> 

     

       38
       38
       +
           unit -> t

     

       39
       39
       +
       end

     

       40
       40
       +
       

     

       41
       41
       +
       (** Represents a header field (name and raw value).

     

       42
       42
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.3> RFC 8621, Section 4.1.3 *)

     

       43
       43
       +
       module Email_header : sig

     

       44
       44
       +
         type t

     

       45
       45
       +
         

     

       46
       46
       +
         (** Get the header field name *)

     

       47
       47
       +
         val name : t -> string

     

       48
       48
       +
         

     

       49
       49
       +
         (** Get the raw header field value *)

     

       50
       50
       +
         val value : t -> string

     

       51
       51
       +
         

     

       52
       52
       +
         (** Create a new header field *)

     

       53
       53
       +
         val v : 

     

       54
       54
       +
           name:string -> 

     

       55
       55
       +
           value:string -> 

     

       56
       56
       +
           unit -> t

     

       57
       57
       +
       end

     

       58
       58
       +
       

     

       59
       59
       +
       (** Represents a body part within an Email's MIME structure.

     

       60
       60
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.4> RFC 8621, Section 4.1.4 *)

     

       61
       61
       +
       module Email_body_part : sig

     

       62
       62
       +
         type t

     

       63
       63
       +
         

     

       64
       64
       +
         (** Get the part ID (null only for multipart types) *)

     

       65
       65
       +
         val id : t -> string option

     

       66
       66
       +
         

     

       67
       67
       +
         (** Get the blob ID (null only for multipart types) *)

     

       68
       68
       +
         val blob_id : t -> id option

     

       69
       69
       +
         

     

       70
       70
       +
         (** Get the size of the part in bytes *)

     

       71
       71
       +
         val size : t -> uint

     

       72
       72
       +
         

     

       73
       73
       +
         (** Get the list of headers for this part *)

     

       74
       74
       +
         val headers : t -> Email_header.t list

     

       75
       75
       +
         

     

       76
       76
       +
         (** Get the filename (if any) *)

     

       77
       77
       +
         val name : t -> string option

     

       78
       78
       +
         

     

       79
       79
       +
         (** Get the MIME type *)

     

       80
       80
       +
         val mime_type : t -> string

     

       81
       81
       +
         

     

       82
       82
       +
         (** Get the charset (if any) *)

     

       83
       83
       +
         val charset : t -> string option

     

       84
       84
       +
         

     

       85
       85
       +
         (** Get the content disposition (if any) *)

     

       86
       86
       +
         val disposition : t -> string option

     

       87
       87
       +
         

     

       88
       88
       +
         (** Get the content ID (if any) *)

     

       89
       89
       +
         val cid : t -> string option

     

       90
       90
       +
         

     

       91
       91
       +
         (** Get the list of languages (if any) *)

     

       92
       92
       +
         val language : t -> string list option

     

       93
       93
       +
         

     

       94
       94
       +
         (** Get the content location (if any) *)

     

       95
       95
       +
         val location : t -> string option

     

       96
       96
       +
         

     

       97
       97
       +
         (** Get the sub-parts (only for multipart types) *)

     

       98
       98
       +
         val sub_parts : t -> t list option

     

       99
       99
       +
         

     

       100
       100
       +
         (** Get any other requested headers (header properties) *)

     

       101
       101
       +
         val other_headers : t -> Yojson.Safe.t string_map

     

       102
       102
       +
         

     

       103
       103
       +
         (** Create a new body part *)

     

       104
       104
       +
         val v :

     

       105
       105
       +
           ?id:string ->

     

       106
       106
       +
           ?blob_id:id ->

     

       107
       107
       +
           size:uint ->

     

       108
       108
       +
           headers:Email_header.t list ->

     

       109
       109
       +
           ?name:string ->

     

       110
       110
       +
           mime_type:string ->

     

       111
       111
       +
           ?charset:string ->

     

       112
       112
       +
           ?disposition:string ->

     

       113
       113
       +
           ?cid:string ->

     

       114
       114
       +
           ?language:string list ->

     

       115
       115
       +
           ?location:string ->

     

       116
       116
       +
           ?sub_parts:t list ->

     

       117
       117
       +
           ?other_headers:Yojson.Safe.t string_map ->

     

       118
       118
       +
           unit -> t

     

       119
       119
       +
       end

     

       120
       120
       +
       

     

       121
       121
       +
       (** Represents the decoded value of a text body part.

     

       122
       122
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.4> RFC 8621, Section 4.1.4 *)

     

       123
       123
       +
       module Email_body_value : sig

     

       124
       124
       +
         type t 

     

       125
       125
       +
         

     

       126
       126
       +
         (** Get the decoded text content *)

     

       127
       127
       +
         val value : t -> string

     

       128
       128
       +
         

     

       129
       129
       +
         (** Check if there was an encoding problem *)

     

       130
       130
       +
         val has_encoding_problem : t -> bool

     

       131
       131
       +
         

     

       132
       132
       +
         (** Check if the content was truncated *)

     

       133
       133
       +
         val is_truncated : t -> bool

     

       134
       134
       +
         

     

       135
       135
       +
         (** Create a new body value *)

     

       136
       136
       +
         val v :

     

       137
       137
       +
           value:string ->

     

       138
       138
       +
           ?encoding_problem:bool ->

     

       139
       139
       +
           ?truncated:bool ->

     

       140
       140
       +
           unit -> t

     

       141
       141
       +
       end

     

       142
       142
       +
       

     

       143
       143
       +
       (** Type to represent email message flags/keywords.

     

       144
       144
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1.1> RFC 8621, Section 4.1.1 *)

     

       145
       145
       +
       module Keywords : sig

     

       146
       146
       +
         (** Represents different types of JMAP keywords *)

     

       147
       147
       +
         type keyword =

     

       148
       148
       +
           | Draft      (** "$draft": The Email is a draft the user is composing *)

     

       149
       149
       +
           | Seen       (** "$seen": The Email has been read *)

     

       150
       150
       +
           | Flagged    (** "$flagged": The Email has been flagged for urgent/special attention *)

     

       151
       151
       +
           | Answered   (** "$answered": The Email has been replied to *)

     

       152
       152
       +
           

     

       153
       153
       +
           (* Common extension keywords from RFC 5788 *)

     

       154
       154
       +
           | Forwarded  (** "$forwarded": The Email has been forwarded *)

     

       155
       155
       +
           | Phishing   (** "$phishing": The Email is likely to be phishing *)

     

       156
       156
       +
           | Junk       (** "$junk": The Email is spam/junk *)

     

       157
       157
       +
           | NotJunk    (** "$notjunk": The Email is explicitly marked as not spam/junk *)

     

       158
       158
       +
           

     

       159
       159
       +
           (* Apple Mail and other vendor extension keywords from draft-ietf-mailmaint-messageflag-mailboxattribute *)

     

       160
       160
       +
           | Notify     (** "$notify": Request to be notified when this email gets a reply *)

     

       161
       161
       +
           | Muted      (** "$muted": Email is muted (notifications disabled) *)

     

       162
       162
       +
           | Followed   (** "$followed": Email thread is followed for notifications *)

     

       163
       163
       +
           | Memo       (** "$memo": Email has a memo/note associated with it *)

     

       164
       164
       +
           | HasMemo    (** "$hasmemo": Email has a memo, annotation or note property *)

     

       165
       165
       +
           | Autosent   (** "$autosent": Email was generated or sent automatically *)

     

       166
       166
       +
           | Unsubscribed (** "$unsubscribed": User has unsubscribed from this sender *)

     

       167
       167
       +
           | CanUnsubscribe (** "$canunsubscribe": Email contains unsubscribe information *)

     

       168
       168
       +
           | Imported   (** "$imported": Email was imported from another system *)

     

       169
       169
       +
           | IsTrusted  (** "$istrusted": Email is from a trusted/verified sender *)

     

       170
       170
       +
           | MaskedEmail (** "$maskedemail": Email is to/from a masked/anonymous address *)

     

       171
       171
       +
           | New        (** "$new": Email was recently delivered *)

     

       172
       172
       +
           

     

       173
       173
       +
           (* Apple Mail flag colors (color bit flags) *)

     

       174
       174
       +
           | MailFlagBit0 (** "$MailFlagBit0": First color flag bit (red) *)

     

       175
       175
       +
           | MailFlagBit1 (** "$MailFlagBit1": Second color flag bit (orange) *)

     

       176
       176
       +
           | MailFlagBit2 (** "$MailFlagBit2": Third color flag bit (yellow) *)

     

       177
       177
       +
           | Custom of string  (** Arbitrary user-defined keyword *)

     

       178
       178
       +
       

     

       179
       179
       +
         (** A set of keywords applied to an email *)

     

       180
       180
       +
         type t = keyword list

     

       181
       181
       +
       

     

       182
       182
       +
         (** Check if an email has the draft flag *)

     

       183
       183
       +
         val is_draft : t -> bool

     

       184
       184
       +
         

     

       185
       185
       +
         (** Check if an email has been read *)

     

       186
       186
       +
         val is_seen : t -> bool

     

       187
       187
       +
         

     

       188
       188
       +
         (** Check if an email has neither been read nor is a draft *)

     

       189
       189
       +
         val is_unread : t -> bool

     

       190
       190
       +
         

     

       191
       191
       +
         (** Check if an email has been flagged *)

     

       192
       192
       +
         val is_flagged : t -> bool

     

       193
       193
       +
         

     

       194
       194
       +
         (** Check if an email has been replied to *)

     

       195
       195
       +
         val is_answered : t -> bool

     

       196
       196
       +
         

     

       197
       197
       +
         (** Check if an email has been forwarded *)

     

       198
       198
       +
         val is_forwarded : t -> bool

     

       199
       199
       +
         

     

       200
       200
       +
         (** Check if an email is marked as likely phishing *)

     

       201
       201
       +
         val is_phishing : t -> bool

     

       202
       202
       +
         

     

       203
       203
       +
         (** Check if an email is marked as junk/spam *)

     

       204
       204
       +
         val is_junk : t -> bool

     

       205
       205
       +
         

     

       206
       206
       +
         (** Check if an email is explicitly marked as not junk/spam *)

     

       207
       207
       +
         val is_not_junk : t -> bool

     

       208
       208
       +
         

     

       209
       209
       +
         (** Check if a specific custom keyword is set *)

     

       210
       210
       +
         val has_keyword : t -> string -> bool

     

       211
       211
       +
         

     

       212
       212
       +
         (** Get a list of all custom keywords (excluding system keywords) *)

     

       213
       213
       +
         val custom_keywords : t -> string list

     

       214
       214
       +
         

     

       215
       215
       +
         (** Add a keyword to the set *)

     

       216
       216
       +
         val add : t -> keyword -> t

     

       217
       217
       +
         

     

       218
       218
       +
         (** Remove a keyword from the set *)

     

       219
       219
       +
         val remove : t -> keyword -> t

     

       220
       220
       +
         

     

       221
       221
       +
         (** Create an empty keyword set *)

     

       222
       222
       +
         val empty : unit -> t

     

       223
       223
       +
         

     

       224
       224
       +
         (** Create a new keyword set with the specified keywords *)

     

       225
       225
       +
         val of_list : keyword list -> t

     

       226
       226
       +
         

     

       227
       227
       +
         (** Get the string representation of a keyword as used in the JMAP protocol *)

     

       228
       228
       +
         val to_string : keyword -> string

     

       229
       229
       +
         

     

       230
       230
       +
         (** Parse a string into a keyword *)

     

       231
       231
       +
         val of_string : string -> keyword

     

       232
       232
       +
         

     

       233
       233
       +
         (** Convert keyword set to string map representation as used in JMAP *)

     

       234
       234
       +
         val to_map : t -> bool string_map

     

       235
       235
       +
       end

     

       236
       236
       +
       

     

       237
       237
       +
       (** Email properties enum.

     

       238
       238
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1> RFC 8621, Section 4.1 *)

     

       239
       239
       +
       type email_property =

     

       240
       240
       +
         | Id               (** The id of the email *)

     

       241
       241
       +
         | BlobId           (** The id of the blob containing the raw message *)

     

       242
       242
       +
         | ThreadId         (** The id of the thread this email belongs to *)

     

       243
       243
       +
         | MailboxIds       (** The mailboxes this email belongs to *)

     

       244
       244
       +
         | Keywords         (** The keywords/flags for this email *)

     

       245
       245
       +
         | Size             (** Size of the message in bytes *)

     

       246
       246
       +
         | ReceivedAt       (** When the message was received by the server *)

     

       247
       247
       +
         | MessageId        (** Value of the Message-ID header *)

     

       248
       248
       +
         | InReplyTo        (** Value of the In-Reply-To header *)

     

       249
       249
       +
         | References       (** Value of the References header *)

     

       250
       250
       +
         | Sender           (** Value of the Sender header *)

     

       251
       251
       +
         | From             (** Value of the From header *)

     

       252
       252
       +
         | To               (** Value of the To header *)

     

       253
       253
       +
         | Cc               (** Value of the Cc header *)

     

       254
       254
       +
         | Bcc              (** Value of the Bcc header *)

     

       255
       255
       +
         | ReplyTo          (** Value of the Reply-To header *)

     

       256
       256
       +
         | Subject          (** Value of the Subject header *)

     

       257
       257
       +
         | SentAt           (** Value of the Date header *)

     

       258
       258
       +
         | HasAttachment    (** Whether the email has attachments *)

     

       259
       259
       +
         | Preview          (** Preview text of the email *)

     

       260
       260
       +
         | BodyStructure    (** MIME structure of the email *)

     

       261
       261
       +
         | BodyValues       (** Decoded body part values *)

     

       262
       262
       +
         | TextBody         (** Text body parts *)

     

       263
       263
       +
         | HtmlBody         (** HTML body parts *)

     

       264
       264
       +
         | Attachments      (** Attachments *)

     

       265
       265
       +
         | Header of string (** Specific header *)

     

       266
       266
       +
         | Other of string  (** Extension property *)

     

       267
       267
       +
       

     

       268
       268
       +
       (** Represents an Email object.

     

       269
       269
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.1> RFC 8621, Section 4.1 *)

     

       270
       270
       +
       module Email : sig

     

       271
       271
       +
         (** Email type *)

     

       272
       272
       +
         type t

     

       273
       273
       +
         

     

       274
       274
       +
         (** ID of the email *)

     

       275
       275
       +
         val id : t -> id option

     

       276
       276
       +
         

     

       277
       277
       +
         (** ID of the blob containing the raw message *)

     

       278
       278
       +
         val blob_id : t -> id option

     

       279
       279
       +
         

     

       280
       280
       +
         (** ID of the thread this email belongs to *)

     

       281
       281
       +
         val thread_id : t -> id option

     

       282
       282
       +
         

     

       283
       283
       +
         (** The set of mailbox IDs this email belongs to *)

     

       284
       284
       +
         val mailbox_ids : t -> bool id_map option

     

       285
       285
       +
         

     

       286
       286
       +
         (** The set of keywords/flags for this email *)

     

       287
       287
       +
         val keywords : t -> Keywords.t option

     

       288
       288
       +
         

     

       289
       289
       +
         (** Size of the message in bytes *)

     

       290
       290
       +
         val size : t -> uint option

     

       291
       291
       +
         

     

       292
       292
       +
         (** When the message was received by the server *)

     

       293
       293
       +
         val received_at : t -> date option

     

       294
       294
       +
         

     

       295
       295
       +
         (** Subject of the email (if requested) *)

     

       296
       296
       +
         val subject : t -> string option

     

       297
       297
       +
         

     

       298
       298
       +
         (** Preview text of the email (if requested) *)

     

       299
       299
       +
         val preview : t -> string option

     

       300
       300
       +
         

     

       301
       301
       +
         (** From addresses (if requested) *)

     

       302
       302
       +
         val from : t -> Email_address.t list option

     

       303
       303
       +
         

     

       304
       304
       +
         (** To addresses (if requested) *)

     

       305
       305
       +
         val to_ : t -> Email_address.t list option

     

       306
       306
       +
         

     

       307
       307
       +
         (** CC addresses (if requested) *)

     

       308
       308
       +
         val cc : t -> Email_address.t list option

     

       309
       309
       +
         

     

       310
       310
       +
         (** Message ID values (if requested) *)

     

       311
       311
       +
         val message_id : t -> string list option

     

       312
       312
       +
         

     

       313
       313
       +
         (** Get whether the email has attachments (if requested) *)

     

       314
       314
       +
         val has_attachment : t -> bool option

     

       315
       315
       +
         

     

       316
       316
       +
         (** Get text body parts (if requested) *)

     

       317
       317
       +
         val text_body : t -> Email_body_part.t list option

     

       318
       318
       +
         

     

       319
       319
       +
         (** Get HTML body parts (if requested) *)

     

       320
       320
       +
         val html_body : t -> Email_body_part.t list option

     

       321
       321
       +
         

     

       322
       322
       +
         (** Get attachments (if requested) *)

     

       323
       323
       +
         val attachments : t -> Email_body_part.t list option

     

       324
       324
       +
         

     

       325
       325
       +
         (** Create a new Email object from a server response or for a new email *)

     

       326
       326
       +
         val create :

     

       327
       327
       +
           ?id:id ->

     

       328
       328
       +
           ?blob_id:id ->

     

       329
       329
       +
           ?thread_id:id ->

     

       330
       330
       +
           ?mailbox_ids:bool id_map ->

     

       331
       331
       +
           ?keywords:Keywords.t ->

     

       332
       332
       +
           ?size:uint ->

     

       333
       333
       +
           ?received_at:date ->

     

       334
       334
       +
           ?subject:string ->

     

       335
       335
       +
           ?preview:string ->

     

       336
       336
       +
           ?from:Email_address.t list ->

     

       337
       337
       +
           ?to_:Email_address.t list ->

     

       338
       338
       +
           ?cc:Email_address.t list ->

     

       339
       339
       +
           ?message_id:string list ->

     

       340
       340
       +
           ?has_attachment:bool ->

     

       341
       341
       +
           ?text_body:Email_body_part.t list ->

     

       342
       342
       +
           ?html_body:Email_body_part.t list ->

     

       343
       343
       +
           ?attachments:Email_body_part.t list ->

     

       344
       344
       +
           unit -> t

     

       345
       345
       +
           

     

       346
       346
       +
         (** Create a patch object for updating email properties *)

     

       347
       347
       +
         val make_patch :

     

       348
       348
       +
           ?add_keywords:Keywords.t ->

     

       349
       349
       +
           ?remove_keywords:Keywords.t ->

     

       350
       350
       +
           ?add_mailboxes:id list ->

     

       351
       351
       +
           ?remove_mailboxes:id list ->

     

       352
       352
       +
           unit -> Jmap.Methods.patch_object

     

       353
       353
       +
         

     

       354
       354
       +
         (** Extract the ID from an email, returning a Result *)

     

       355
       355
       +
         val get_id : t -> (id, string) result

     

       356
       356
       +
         

     

       357
       357
       +
         (** Take the ID from an email (fails with an exception if not present) *)

     

       358
       358
       +
         val take_id : t -> id

     

       359
       359
       +
       end

     

       360
       360
       +
       

     

       361
       361
       +
       (** Email/import method arguments and responses.

     

       362
       362
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.8> RFC 8621, Section 4.8 *)

     

       363
       363
       +
       module Import : sig

     

       364
       364
       +
         (** Arguments for Email/import method *)

     

       365
       365
       +
         type args = {

     

       366
       366
       +
           account_id : id;

     

       367
       367
       +
           blob_ids : id list;

     

       368
       368
       +
           mailbox_ids : id id_map;

     

       369
       369
       +
           keywords : Keywords.t option;

     

       370
       370
       +
           received_at : date option;

     

       371
       371
       +
         }

     

       372
       372
       +
       

     

       373
       373
       +
         (** Create import arguments *)

     

       374
       374
       +
         val create_args :

     

       375
       375
       +
           account_id:id ->

     

       376
       376
       +
           blob_ids:id list ->

     

       377
       377
       +
           mailbox_ids:id id_map ->

     

       378
       378
       +
           ?keywords:Keywords.t ->

     

       379
       379
       +
           ?received_at:date ->

     

       380
       380
       +
           unit -> args

     

       381
       381
       +
       

     

       382
       382
       +
         (** Response for a single imported email *)

     

       383
       383
       +
         type email_import_result = {

     

       384
       384
       +
           blob_id : id;

     

       385
       385
       +
           email : Email.t;

     

       386
       386
       +
         }

     

       387
       387
       +
       

     

       388
       388
       +
         (** Create an email import result *)

     

       389
       389
       +
         val create_result :

     

       390
       390
       +
           blob_id:id ->

     

       391
       391
       +
           email:Email.t ->

     

       392
       392
       +
           unit -> email_import_result

     

       393
       393
       +
       

     

       394
       394
       +
         (** Response for Email/import method *)

     

       395
       395
       +
         type response = {

     

       396
       396
       +
           account_id : id;

     

       397
       397
       +
           created : email_import_result id_map;

     

       398
       398
       +
           not_created : Jmap.Error.Set_error.t id_map;

     

       399
       399
       +
         }

     

       400
       400
       +
       

     

       401
       401
       +
         (** Create import response *)

     

       402
       402
       +
         val create_response :

     

       403
       403
       +
           account_id:id ->

     

       404
       404
       +
           created:email_import_result id_map ->

     

       405
       405
       +
           not_created:Jmap.Error.Set_error.t id_map ->

     

       406
       406
       +
           unit -> response

     

       407
       407
       +
       end

     

       408
       408
       +
       

     

       409
       409
       +
       (** Email/parse method arguments and responses.

     

       410
       410
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.9> RFC 8621, Section 4.9 *)

     

       411
       411
       +
       module Parse : sig

     

       412
       412
       +
         (** Arguments for Email/parse method *)

     

       413
       413
       +
         type args = {

     

       414
       414
       +
           account_id : id;

     

       415
       415
       +
           blob_ids : id list;

     

       416
       416
       +
           properties : string list option;

     

       417
       417
       +
         }

     

       418
       418
       +
       

     

       419
       419
       +
         (** Create parse arguments *)

     

       420
       420
       +
         val create_args :

     

       421
       421
       +
           account_id:id ->

     

       422
       422
       +
           blob_ids:id list ->

     

       423
       423
       +
           ?properties:string list ->

     

       424
       424
       +
           unit -> args

     

       425
       425
       +
       

     

       426
       426
       +
         (** Response for a single parsed email *)

     

       427
       427
       +
         type email_parse_result = {

     

       428
       428
       +
           blob_id : id;

     

       429
       429
       +
           parsed : Email.t;

     

       430
       430
       +
         }

     

       431
       431
       +
       

     

       432
       432
       +
         (** Create an email parse result *)

     

       433
       433
       +
         val create_result :

     

       434
       434
       +
           blob_id:id ->

     

       435
       435
       +
           parsed:Email.t ->

     

       436
       436
       +
           unit -> email_parse_result

     

       437
       437
       +
       

     

       438
       438
       +
         (** Response for Email/parse method *)

     

       439
       439
       +
         type response = {

     

       440
       440
       +
           account_id : id;

     

       441
       441
       +
           parsed : email_parse_result id_map;

     

       442
       442
       +
           not_parsed : string id_map;

     

       443
       443
       +
         }

     

       444
       444
       +
       

     

       445
       445
       +
         (** Create parse response *)

     

       446
       446
       +
         val create_response :

     

       447
       447
       +
           account_id:id ->

     

       448
       448
       +
           parsed:email_parse_result id_map ->

     

       449
       449
       +
           not_parsed:string id_map ->

     

       450
       450
       +
           unit -> response

     

       451
       451
       +
       end

     

       452
       452
       +
       

     

       453
       453
       +
       (** Email import options. 

     

       454
       454
       +
           @deprecated Use Import.args instead.

     

       455
       455
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.8> RFC 8621, Section 4.8 *)

     

       456
       456
       +
       type email_import_options = {

     

       457
       457
       +
         import_to_mailboxes : id list;

     

       458
       458
       +
         import_keywords : Keywords.t option;

     

       459
       459
       +
         import_received_at : date option;

     

       460
       460
       +
       }

     

       461
       461
       +
       

     

       462
       462
       +
       (** Email/copy method arguments and responses.

     

       463
       463
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.7> RFC 8621, Section 4.7 *)

     

       464
       464
       +
       module Copy : sig

     

       465
       465
       +
         (** Arguments for Email/copy method *)

     

       466
       466
       +
         type args = {

     

       467
       467
       +
           from_account_id : id;

     

       468
       468
       +
           account_id : id;

     

       469
       469
       +
           create : (id * id id_map) id_map;

     

       470
       470
       +
           on_success_destroy_original : bool option;

     

       471
       471
       +
           destroy_from_if_in_state : string option;

     

       472
       472
       +
         }

     

       473
       473
       +
       

     

       474
       474
       +
         (** Create copy arguments *)

     

       475
       475
       +
         val create_args :

     

       476
       476
       +
           from_account_id:id ->

     

       477
       477
       +
           account_id:id ->

     

       478
       478
       +
           create:(id * id id_map) id_map ->

     

       479
       479
       +
           ?on_success_destroy_original:bool ->

     

       480
       480
       +
           ?destroy_from_if_in_state:string ->

     

       481
       481
       +
           unit -> args

     

       482
       482
       +
       

     

       483
       483
       +
         (** Response for Email/copy method *)

     

       484
       484
       +
         type response = {

     

       485
       485
       +
           from_account_id : id;

     

       486
       486
       +
           account_id : id;

     

       487
       487
       +
           created : Email.t id_map option;

     

       488
       488
       +
           not_created : Jmap.Error.Set_error.t id_map option;

     

       489
       489
       +
         }

     

       490
       490
       +
       

     

       491
       491
       +
         (** Create copy response *)

     

       492
       492
       +
         val create_response :

     

       493
       493
       +
           from_account_id:id ->

     

       494
       494
       +
           account_id:id ->

     

       495
       495
       +
           ?created:Email.t id_map ->

     

       496
       496
       +
           ?not_created:Jmap.Error.Set_error.t id_map ->

     

       497
       497
       +
           unit -> response

     

       498
       498
       +
       end

     

       499
       499
       +
       

     

       500
       500
       +
       (** Email copy options.

     

       501
       501
       +
           @deprecated Use Copy.args instead.

     

       502
       502
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-4.7> RFC 8621, Section 4.7 *)

     

       503
       503
       +
       type email_copy_options = {

     

       504
       504
       +
         copy_to_account_id : id;

     

       505
       505
       +
         copy_to_mailboxes : id list;

     

       506
       506
       +
         copy_on_success_destroy_original : bool option;

     

       507
       507
       +
       }

     

       508
       508
       +
       

     

       509
       509
       +
       (** Convert a property variant to its string representation *)

     

       510
       510
       +
       val email_property_to_string : email_property -> string

     

       511
       511
       +
       

     

       512
       512
       +
       (** Parse a string into a property variant *)

     

       513
       513
       +
       val string_to_email_property : string -> email_property

     

       514
       514
       +
       

     

       515
       515
       +
       (** Get a list of common properties useful for displaying email lists *)

     

       516
       516
       +
       val common_email_properties : email_property list

     

       517
       517
       +
       

     

       518
       518
       +
       (** Get a list of common properties for detailed email view *)

     

       519
       519
       +
       val detailed_email_properties : email_property list

+114

jmap-email/jmap_identity.mli

···

       1
       1
       +
       (** JMAP Identity.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6> RFC 8621, Section 6 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap.Types

     

       5
       5
       +
       open Jmap.Methods

     

       6
       6
       +
       

     

       7
       7
       +
       (** Identity object.

     

       8
       8
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6> RFC 8621, Section 6 *)

     

       9
       9
       +
       type t

     

       10
       10
       +
       

     

       11
       11
       +
       (** Get the identity ID (immutable, server-set) *)

     

       12
       12
       +
       val id : t -> id

     

       13
       13
       +
       

     

       14
       14
       +
       (** Get the display name (defaults to "") *)

     

       15
       15
       +
       val name : t -> string

     

       16
       16
       +
       

     

       17
       17
       +
       (** Get the email address (immutable) *)

     

       18
       18
       +
       val email : t -> string

     

       19
       19
       +
       

     

       20
       20
       +
       (** Get the reply-to addresses (if any) *)

     

       21
       21
       +
       val reply_to : t -> Jmap_email_types.Email_address.t list option

     

       22
       22
       +
       

     

       23
       23
       +
       (** Get the bcc addresses (if any) *)

     

       24
       24
       +
       val bcc : t -> Jmap_email_types.Email_address.t list option

     

       25
       25
       +
       

     

       26
       26
       +
       (** Get the plain text signature (defaults to "") *)

     

       27
       27
       +
       val text_signature : t -> string

     

       28
       28
       +
       

     

       29
       29
       +
       (** Get the HTML signature (defaults to "") *)

     

       30
       30
       +
       val html_signature : t -> string

     

       31
       31
       +
       

     

       32
       32
       +
       (** Check if this identity may be deleted (server-set) *)

     

       33
       33
       +
       val may_delete : t -> bool

     

       34
       34
       +
       

     

       35
       35
       +
       (** Create a new identity object *)

     

       36
       36
       +
       val v :

     

       37
       37
       +
         id:id ->

     

       38
       38
       +
         ?name:string ->

     

       39
       39
       +
         email:string ->

     

       40
       40
       +
         ?reply_to:Jmap_email_types.Email_address.t list ->

     

       41
       41
       +
         ?bcc:Jmap_email_types.Email_address.t list ->

     

       42
       42
       +
         ?text_signature:string ->

     

       43
       43
       +
         ?html_signature:string ->

     

       44
       44
       +
         may_delete:bool ->

     

       45
       45
       +
         unit -> t

     

       46
       46
       +
         

     

       47
       47
       +
       (** Types and functions for identity creation and updates *)

     

       48
       48
       +
       module Create : sig

     

       49
       49
       +
         type t

     

       50
       50
       +
         

     

       51
       51
       +
         (** Get the name (if specified) *)

     

       52
       52
       +
         val name : t -> string option

     

       53
       53
       +
         

     

       54
       54
       +
         (** Get the email address *)

     

       55
       55
       +
         val email : t -> string

     

       56
       56
       +
         

     

       57
       57
       +
         (** Get the reply-to addresses (if any) *)

     

       58
       58
       +
         val reply_to : t -> Jmap_email_types.Email_address.t list option

     

       59
       59
       +
         

     

       60
       60
       +
         (** Get the bcc addresses (if any) *)

     

       61
       61
       +
         val bcc : t -> Jmap_email_types.Email_address.t list option

     

       62
       62
       +
         

     

       63
       63
       +
         (** Get the plain text signature (if specified) *)

     

       64
       64
       +
         val text_signature : t -> string option

     

       65
       65
       +
         

     

       66
       66
       +
         (** Get the HTML signature (if specified) *)

     

       67
       67
       +
         val html_signature : t -> string option

     

       68
       68
       +
         

     

       69
       69
       +
         (** Create a new identity creation object *)

     

       70
       70
       +
         val v :

     

       71
       71
       +
           ?name:string ->

     

       72
       72
       +
           email:string ->

     

       73
       73
       +
           ?reply_to:Jmap_email_types.Email_address.t list ->

     

       74
       74
       +
           ?bcc:Jmap_email_types.Email_address.t list ->

     

       75
       75
       +
           ?text_signature:string ->

     

       76
       76
       +
           ?html_signature:string ->

     

       77
       77
       +
           unit -> t

     

       78
       78
       +
           

     

       79
       79
       +
         (** Server response with info about the created identity *)

     

       80
       80
       +
         module Response : sig

     

       81
       81
       +
           type t

     

       82
       82
       +
           

     

       83
       83
       +
           (** Get the server-assigned ID for the created identity *)

     

       84
       84
       +
           val id : t -> id

     

       85
       85
       +
           

     

       86
       86
       +
           (** Check if this identity may be deleted *)

     

       87
       87
       +
           val may_delete : t -> bool

     

       88
       88
       +
           

     

       89
       89
       +
           (** Create a new response object *)

     

       90
       90
       +
           val v :

     

       91
       91
       +
             id:id ->

     

       92
       92
       +
             may_delete:bool ->

     

       93
       93
       +
             unit -> t

     

       94
       94
       +
         end

     

       95
       95
       +
       end

     

       96
       96
       +
       

     

       97
       97
       +
       (** Identity object for update.

     

       98
       98
       +
           Patch object, specific structure not enforced here.

     

       99
       99
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.3> RFC 8621, Section 6.3 *)

     

       100
       100
       +
       type update = patch_object

     

       101
       101
       +
       

     

       102
       102
       +
       (** Server-set/computed info for updated identity.

     

       103
       103
       +
           Contains only changed server-set props.

     

       104
       104
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.3> RFC 8621, Section 6.3 *)

     

       105
       105
       +
       module Update_response : sig

     

       106
       106
       +
         type t

     

       107
       107
       +
         

     

       108
       108
       +
         (** Convert to a full Identity object (contains only changed server-set props) *)

     

       109
       109
       +
         val to_identity : t -> t

     

       110
       110
       +
         

     

       111
       111
       +
         (** Create from a full Identity object *)

     

       112
       112
       +
         val of_identity : t -> t

     

       113
       113
       +
       end

     

       114
       114
       +

+187

jmap-email/jmap_mailbox.mli

···

       1
       1
       +
       (** JMAP Mailbox.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap.Types

     

       5
       5
       +
       open Jmap.Methods

     

       6
       6
       +
       

     

       7
       7
       +
       (** Standard mailbox roles as defined in RFC 8621.

     

       8
       8
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)

     

       9
       9
       +
       type role =

     

       10
       10
       +
         | Inbox     (** Messages in the primary inbox *)

     

       11
       11
       +
         | Archive   (** Archived messages *)

     

       12
       12
       +
         | Drafts    (** Draft messages being composed *)

     

       13
       13
       +
         | Sent      (** Messages that have been sent *)

     

       14
       14
       +
         | Trash     (** Messages that have been deleted *)

     

       15
       15
       +
         | Junk      (** Messages determined to be spam *)

     

       16
       16
       +
         | Important (** Messages deemed important *)

     

       17
       17
       +
         | Snoozed    (** Messages snoozed for later notification/reappearance, from draft-ietf-mailmaint-messageflag-mailboxattribute *)

     

       18
       18
       +
         | Scheduled  (** Messages scheduled for sending at a later time, from draft-ietf-mailmaint-messageflag-mailboxattribute *)

     

       19
       19
       +
         | Memos      (** Messages containing memos or notes, from draft-ietf-mailmaint-messageflag-mailboxattribute *)

     

       20
       20
       +
         

     

       21
       21
       +
         | Other of string (** Custom or non-standard role *)

     

       22
       22
       +
         | None      (** No specific role assigned *)

     

       23
       23
       +
       

     

       24
       24
       +
       (** Mailbox property identifiers.

     

       25
       25
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)

     

       26
       26
       +
       type property =

     

       27
       27
       +
         | Id            (** The id of the mailbox *)

     

       28
       28
       +
         | Name          (** The name of the mailbox *)

     

       29
       29
       +
         | ParentId      (** The id of the parent mailbox *)

     

       30
       30
       +
         | Role          (** The role of the mailbox *)

     

       31
       31
       +
         | SortOrder     (** The sort order of the mailbox *)

     

       32
       32
       +
         | TotalEmails   (** The total number of emails in the mailbox *)

     

       33
       33
       +
         | UnreadEmails  (** The number of unread emails in the mailbox *)

     

       34
       34
       +
         | TotalThreads  (** The total number of threads in the mailbox *)

     

       35
       35
       +
         | UnreadThreads (** The number of unread threads in the mailbox *)

     

       36
       36
       +
         | MyRights      (** The rights the user has for the mailbox *)

     

       37
       37
       +
         | IsSubscribed  (** Whether the mailbox is subscribed to *)

     

       38
       38
       +
         | Other of string (** Any server-specific extension properties *)

     

       39
       39
       +
       

     

       40
       40
       +
       (** Mailbox access rights.

     

       41
       41
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)

     

       42
       42
       +
       type mailbox_rights = {

     

       43
       43
       +
         may_read_items : bool;

     

       44
       44
       +
         may_add_items : bool;

     

       45
       45
       +
         may_remove_items : bool;

     

       46
       46
       +
         may_set_seen : bool;

     

       47
       47
       +
         may_set_keywords : bool;

     

       48
       48
       +
         may_create_child : bool;

     

       49
       49
       +
         may_rename : bool;

     

       50
       50
       +
         may_delete : bool;

     

       51
       51
       +
         may_submit : bool;

     

       52
       52
       +
       }

     

       53
       53
       +
       

     

       54
       54
       +
       (** Mailbox object.

     

       55
       55
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)

     

       56
       56
       +
       type mailbox = {

     

       57
       57
       +
         mailbox_id : id; (** immutable, server-set *)

     

       58
       58
       +
         name : string;

     

       59
       59
       +
         parent_id : id option;

     

       60
       60
       +
         role : role option;

     

       61
       61
       +
         sort_order : uint; (* default: 0 *)

     

       62
       62
       +
         total_emails : uint; (** server-set *)

     

       63
       63
       +
         unread_emails : uint; (** server-set *)

     

       64
       64
       +
         total_threads : uint; (** server-set *)

     

       65
       65
       +
         unread_threads : uint; (** server-set *)

     

       66
       66
       +
         my_rights : mailbox_rights; (** server-set *)

     

       67
       67
       +
         is_subscribed : bool;

     

       68
       68
       +
       }

     

       69
       69
       +
       

     

       70
       70
       +
       (** Mailbox object for creation.

     

       71
       71
       +
           Excludes server-set fields.

     

       72
       72
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)

     

       73
       73
       +
       type mailbox_create = {

     

       74
       74
       +
         mailbox_create_name : string;

     

       75
       75
       +
         mailbox_create_parent_id : id option;

     

       76
       76
       +
         mailbox_create_role : role option;

     

       77
       77
       +
         mailbox_create_sort_order : uint option;

     

       78
       78
       +
         mailbox_create_is_subscribed : bool option;

     

       79
       79
       +
       }

     

       80
       80
       +
       

     

       81
       81
       +
       (** Mailbox object for update.

     

       82
       82
       +
           Patch object, specific structure not enforced here.

     

       83
       83
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5> RFC 8621, Section 2.5 *)

     

       84
       84
       +
       type mailbox_update = patch_object

     

       85
       85
       +
       

     

       86
       86
       +
       (** Server-set info for created mailbox.

     

       87
       87
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5> RFC 8621, Section 2.5 *)

     

       88
       88
       +
       type mailbox_created_info = {

     

       89
       89
       +
         mailbox_created_id : id;

     

       90
       90
       +
         mailbox_created_role : role option; (** If default used *)

     

       91
       91
       +
         mailbox_created_sort_order : uint; (** If default used *)

     

       92
       92
       +
         mailbox_created_total_emails : uint;

     

       93
       93
       +
         mailbox_created_unread_emails : uint;

     

       94
       94
       +
         mailbox_created_total_threads : uint;

     

       95
       95
       +
         mailbox_created_unread_threads : uint;

     

       96
       96
       +
         mailbox_created_my_rights : mailbox_rights;

     

       97
       97
       +
         mailbox_created_is_subscribed : bool; (** If default used *)

     

       98
       98
       +
       }

     

       99
       99
       +
       

     

       100
       100
       +
       (** Server-set/computed info for updated mailbox.

     

       101
       101
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5> RFC 8621, Section 2.5 *)

     

       102
       102
       +
       type mailbox_updated_info = mailbox (* Contains only changed server-set props *)

     

       103
       103
       +
       

     

       104
       104
       +
       (** FilterCondition for Mailbox/query.

     

       105
       105
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2.3> RFC 8621, Section 2.3 *)

     

       106
       106
       +
       type mailbox_filter_condition = {

     

       107
       107
       +
         filter_parent_id : id option option; (* Use option option for explicit null *)

     

       108
       108
       +
         filter_name : string option;

     

       109
       109
       +
         filter_role : role option option; (* Use option option for explicit null *)

     

       110
       110
       +
         filter_has_any_role : bool option;

     

       111
       111
       +
         filter_is_subscribed : bool option;

     

       112
       112
       +
       }

     

       113
       113
       +
       

     

       114
       114
       +
       (** {2 Role and Property Conversion Functions} *)

     

       115
       115
       +
       

     

       116
       116
       +
       (** Convert a role variant to its string representation *)

     

       117
       117
       +
       val role_to_string : role -> string

     

       118
       118
       +
       

     

       119
       119
       +
       (** Parse a string into a role variant *)

     

       120
       120
       +
       val string_to_role : string -> role

     

       121
       121
       +
       

     

       122
       122
       +
       (** Convert a property variant to its string representation *)

     

       123
       123
       +
       val property_to_string : property -> string

     

       124
       124
       +
       

     

       125
       125
       +
       (** Parse a string into a property variant *)

     

       126
       126
       +
       val string_to_property : string -> property

     

       127
       127
       +
       

     

       128
       128
       +
       (** Get a list of common properties useful for displaying mailboxes *)

     

       129
       129
       +
       val common_properties : property list

     

       130
       130
       +
       

     

       131
       131
       +
       (** Get a list of all standard properties *)

     

       132
       132
       +
       val all_properties : property list

     

       133
       133
       +
       

     

       134
       134
       +
       (** Check if a property is a count property (TotalEmails, UnreadEmails, etc.) *)

     

       135
       135
       +
       val is_count_property : property -> bool

     

       136
       136
       +
       

     

       137
       137
       +
       (** {2 Mailbox Creation and Manipulation} *)

     

       138
       138
       +
       

     

       139
       139
       +
       (** Create a set of default rights with all permissions *)

     

       140
       140
       +
       val default_rights : unit -> mailbox_rights

     

       141
       141
       +
       

     

       142
       142
       +
       (** Create a set of read-only rights *)

     

       143
       143
       +
       val readonly_rights : unit -> mailbox_rights

     

       144
       144
       +
       

     

       145
       145
       +
       (** Create a new mailbox object with minimal required fields *)

     

       146
       146
       +
       val create : 

     

       147
       147
       +
         name:string -> 

     

       148
       148
       +
         ?parent_id:id -> 

     

       149
       149
       +
         ?role:role -> 

     

       150
       150
       +
         ?sort_order:uint -> 

     

       151
       151
       +
         ?is_subscribed:bool -> 

     

       152
       152
       +
         unit -> mailbox_create

     

       153
       153
       +
         

     

       154
       154
       +
       (** Build a patch object for updating mailbox properties *)

     

       155
       155
       +
       val update :

     

       156
       156
       +
         ?name:string ->

     

       157
       157
       +
         ?parent_id:id option ->

     

       158
       158
       +
         ?role:role option ->

     

       159
       159
       +
         ?sort_order:uint ->

     

       160
       160
       +
         ?is_subscribed:bool ->

     

       161
       161
       +
         unit -> mailbox_update

     

       162
       162
       +
         

     

       163
       163
       +
       (** Get the list of standard role names and their string representations *)

     

       164
       164
       +
       val standard_role_names : (role * string) list

     

       165
       165
       +
       

     

       166
       166
       +
       (** {2 Filter Construction} *)

     

       167
       167
       +
       

     

       168
       168
       +
       (** Create a filter to match mailboxes with a specific role *)

     

       169
       169
       +
       val filter_has_role : role -> Jmap.Methods.Filter.t

     

       170
       170
       +
       

     

       171
       171
       +
       (** Create a filter to match mailboxes with no role *)

     

       172
       172
       +
       val filter_has_no_role : unit -> Jmap.Methods.Filter.t

     

       173
       173
       +
       

     

       174
       174
       +
       (** Create a filter to match mailboxes that are child of a given parent *)

     

       175
       175
       +
       val filter_has_parent : id -> Jmap.Methods.Filter.t

     

       176
       176
       +
       

     

       177
       177
       +
       (** Create a filter to match mailboxes at the root level (no parent) *)

     

       178
       178
       +
       val filter_is_root : unit -> Jmap.Methods.Filter.t

     

       179
       179
       +
       

     

       180
       180
       +
       (** Create a filter to match subscribed mailboxes *)

     

       181
       181
       +
       val filter_is_subscribed : unit -> Jmap.Methods.Filter.t

     

       182
       182
       +
       

     

       183
       183
       +
       (** Create a filter to match unsubscribed mailboxes *)

     

       184
       184
       +
       val filter_is_not_subscribed : unit -> Jmap.Methods.Filter.t

     

       185
       185
       +
       

     

       186
       186
       +
       (** Create a filter to match mailboxes by name (using case-insensitive substring matching) *)

     

       187
       187
       +
       val filter_name_contains : string -> Jmap.Methods.Filter.t

+89

jmap-email/jmap_search_snippet.mli

···

       1
       1
       +
       (** JMAP Search Snippet.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5> RFC 8621, Section 5 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap.Types

     

       5
       5
       +
       open Jmap.Methods

     

       6
       6
       +
       

     

       7
       7
       +
       (** SearchSnippet object.

     

       8
       8
       +
           Provides highlighted snippets of emails matching search criteria.

     

       9
       9
       +
           Note: Does not have an 'id' property; the key is the emailId.

     

       10
       10
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5> RFC 8621, Section 5 *)

     

       11
       11
       +
       module SearchSnippet : sig

     

       12
       12
       +
         type t

     

       13
       13
       +
       

     

       14
       14
       +
         (** Get the email ID this snippet is for *)

     

       15
       15
       +
         val email_id : t -> id

     

       16
       16
       +
         

     

       17
       17
       +
         (** Get the highlighted subject snippet (if matched) *)

     

       18
       18
       +
         val subject : t -> string option

     

       19
       19
       +
         

     

       20
       20
       +
         (** Get the highlighted preview snippet (if matched) *)

     

       21
       21
       +
         val preview : t -> string option

     

       22
       22
       +
         

     

       23
       23
       +
         (** Create a new SearchSnippet object *)

     

       24
       24
       +
         val v : 

     

       25
       25
       +
           email_id:id -> 

     

       26
       26
       +
           ?subject:string -> 

     

       27
       27
       +
           ?preview:string -> 

     

       28
       28
       +
           unit -> t

     

       29
       29
       +
       end

     

       30
       30
       +
       

     

       31
       31
       +
       (** {1 SearchSnippet Methods} *)

     

       32
       32
       +
       

     

       33
       33
       +
       (** Arguments for SearchSnippet/get.

     

       34
       34
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5.1> RFC 8621, Section 5.1 *)

     

       35
       35
       +
       module Get_args : sig

     

       36
       36
       +
         type t

     

       37
       37
       +
         

     

       38
       38
       +
         (** The account ID *)

     

       39
       39
       +
         val account_id : t -> id

     

       40
       40
       +
         

     

       41
       41
       +
         (** The filter to use for the search *)

     

       42
       42
       +
         val filter : t -> Filter.t

     

       43
       43
       +
         

     

       44
       44
       +
         (** Email IDs to return snippets for. If null, all matching emails are included *)

     

       45
       45
       +
         val email_ids : t -> id list option

     

       46
       46
       +
         

     

       47
       47
       +
         (** Creation arguments *)

     

       48
       48
       +
         val v :

     

       49
       49
       +
           account_id:id ->

     

       50
       50
       +
           filter:Filter.t ->

     

       51
       51
       +
           ?email_ids:id list ->

     

       52
       52
       +
           unit -> t

     

       53
       53
       +
       end

     

       54
       54
       +
       

     

       55
       55
       +
       (** Response for SearchSnippet/get.

     

       56
       56
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5.1> RFC 8621, Section 5.1 *)

     

       57
       57
       +
       module Get_response : sig

     

       58
       58
       +
         type t

     

       59
       59
       +
         

     

       60
       60
       +
         (** The account ID *)

     

       61
       61
       +
         val account_id : t -> id

     

       62
       62
       +
         

     

       63
       63
       +
         (** The search state string (for caching) *)

     

       64
       64
       +
         val list : t -> SearchSnippet.t id_map

     

       65
       65
       +
         

     

       66
       66
       +
         (** IDs requested that weren't found *)

     

       67
       67
       +
         val not_found : t -> id list

     

       68
       68
       +
         

     

       69
       69
       +
         (** Creation *)

     

       70
       70
       +
         val v :

     

       71
       71
       +
           account_id:id ->

     

       72
       72
       +
           list:SearchSnippet.t id_map ->

     

       73
       73
       +
           not_found:id list ->

     

       74
       74
       +
           unit -> t

     

       75
       75
       +
       end

     

       76
       76
       +
       

     

       77
       77
       +
       (** {1 Helper Functions} *)

     

       78
       78
       +
       

     

       79
       79
       +
       (** Helper to extract all matched keywords from a snippet.

     

       80
       80
       +
           This parses highlighted portions from the snippet to get the actual search terms. *)

     

       81
       81
       +
       val extract_matched_terms : string -> string list

     

       82
       82
       +
       

     

       83
       83
       +
       (** Helper to create a filter that searches in email body text.

     

       84
       84
       +
           This is commonly used for SearchSnippet/get requests. *)

     

       85
       85
       +
       val create_body_text_filter : string -> Filter.t

     

       86
       86
       +
       

     

       87
       87
       +
       (** Helper to create a filter that searches across multiple email fields.

     

       88
       88
       +
           This searches subject, body, and headers for the given text. *)

     

       89
       89
       +
       val create_fulltext_filter : string -> Filter.t

+136

jmap-email/jmap_submission.mli

···

       1
       1
       +
       (** JMAP Email Submission.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap.Types

     

       5
       5
       +
       open Jmap.Methods

     

       6
       6
       +
       

     

       7
       7
       +
       (** Address object for Envelope.

     

       8
       8
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)

     

       9
       9
       +
       type envelope_address = {

     

       10
       10
       +
         env_addr_email : string;

     

       11
       11
       +
         env_addr_parameters : Yojson.Safe.t string_map option;

     

       12
       12
       +
       }

     

       13
       13
       +
       

     

       14
       14
       +
       (** Envelope object.

     

       15
       15
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)

     

       16
       16
       +
       type envelope = {

     

       17
       17
       +
         env_mail_from : envelope_address;

     

       18
       18
       +
         env_rcpt_to : envelope_address list;

     

       19
       19
       +
       }

     

       20
       20
       +
       

     

       21
       21
       +
       (** Delivery status for a recipient.

     

       22
       22
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)

     

       23
       23
       +
       type delivery_status = {

     

       24
       24
       +
         delivery_smtp_reply : string;

     

       25
       25
       +
         delivery_delivered : [ `Queued | `Yes | `No | `Unknown ];

     

       26
       26
       +
         delivery_displayed : [ `Yes | `Unknown ];

     

       27
       27
       +
       }

     

       28
       28
       +
       

     

       29
       29
       +
       (** EmailSubmission object.

     

       30
       30
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)

     

       31
       31
       +
       type email_submission = {

     

       32
       32
       +
         email_sub_id : id; (** immutable, server-set *)

     

       33
       33
       +
         identity_id : id; (** immutable *)

     

       34
       34
       +
         email_id : id; (** immutable *)

     

       35
       35
       +
         thread_id : id; (** immutable, server-set *)

     

       36
       36
       +
         envelope : envelope option; (** immutable *)

     

       37
       37
       +
         send_at : utc_date; (** immutable, server-set *)

     

       38
       38
       +
         undo_status : [ `Pending | `Final | `Canceled ];

     

       39
       39
       +
         delivery_status : delivery_status string_map option; (** server-set *)

     

       40
       40
       +
         dsn_blob_ids : id list; (** server-set *)

     

       41
       41
       +
         mdn_blob_ids : id list; (** server-set *)

     

       42
       42
       +
       }

     

       43
       43
       +
       

     

       44
       44
       +
       (** EmailSubmission object for creation.

     

       45
       45
       +
           Excludes server-set fields.

     

       46
       46
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)

     

       47
       47
       +
       type email_submission_create = {

     

       48
       48
       +
         email_sub_create_identity_id : id;

     

       49
       49
       +
         email_sub_create_email_id : id;

     

       50
       50
       +
         email_sub_create_envelope : envelope option;

     

       51
       51
       +
       }

     

       52
       52
       +
       

     

       53
       53
       +
       (** EmailSubmission object for update.

     

       54
       54
       +
           Only undoStatus can be updated (to 'canceled').

     

       55
       55
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7> RFC 8621, Section 7 *)

     

       56
       56
       +
       type email_submission_update = patch_object

     

       57
       57
       +
       

     

       58
       58
       +
       (** Server-set info for created email submission.

     

       59
       59
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)

     

       60
       60
       +
       type email_submission_created_info = {

     

       61
       61
       +
         email_sub_created_id : id;

     

       62
       62
       +
         email_sub_created_thread_id : id;

     

       63
       63
       +
         email_sub_created_send_at : utc_date;

     

       64
       64
       +
       }

     

       65
       65
       +
       

     

       66
       66
       +
       (** Server-set/computed info for updated email submission.

     

       67
       67
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)

     

       68
       68
       +
       type email_submission_updated_info = email_submission (* Contains only changed server-set props *)

     

       69
       69
       +
       

     

       70
       70
       +
       (** FilterCondition for EmailSubmission/query.

     

       71
       71
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.3> RFC 8621, Section 7.3 *)

     

       72
       72
       +
       type email_submission_filter_condition = {

     

       73
       73
       +
         filter_identity_ids : id list option;

     

       74
       74
       +
         filter_email_ids : id list option;

     

       75
       75
       +
         filter_thread_ids : id list option;

     

       76
       76
       +
         filter_undo_status : [ `Pending | `Final | `Canceled ] option;

     

       77
       77
       +
         filter_before : utc_date option;

     

       78
       78
       +
         filter_after : utc_date option;

     

       79
       79
       +
       }

     

       80
       80
       +
       

     

       81
       81
       +
       (** EmailSubmission/get: Args type (specialized from ['record Get_args.t]). *)

     

       82
       82
       +
       module Email_submission_get_args : sig

     

       83
       83
       +
         type t = email_submission Get_args.t

     

       84
       84
       +
       end

     

       85
       85
       +
       

     

       86
       86
       +
       (** EmailSubmission/get: Response type (specialized from ['record Get_response.t]). *)

     

       87
       87
       +
       module Email_submission_get_response : sig

     

       88
       88
       +
         type t = email_submission Get_response.t

     

       89
       89
       +
       end

     

       90
       90
       +
       

     

       91
       91
       +
       (** EmailSubmission/changes: Args type (specialized from [Changes_args.t]). *)

     

       92
       92
       +
       module Email_submission_changes_args : sig

     

       93
       93
       +
         type t = Changes_args.t

     

       94
       94
       +
       end

     

       95
       95
       +
       

     

       96
       96
       +
       (** EmailSubmission/changes: Response type (specialized from [Changes_response.t]). *)

     

       97
       97
       +
       module Email_submission_changes_response : sig

     

       98
       98
       +
         type t = Changes_response.t

     

       99
       99
       +
       end

     

       100
       100
       +
       

     

       101
       101
       +
       (** EmailSubmission/query: Args type (specialized from [Query_args.t]). *)

     

       102
       102
       +
       module Email_submission_query_args : sig

     

       103
       103
       +
         type t = Query_args.t

     

       104
       104
       +
       end

     

       105
       105
       +
       

     

       106
       106
       +
       (** EmailSubmission/query: Response type (specialized from [Query_response.t]). *)

     

       107
       107
       +
       module Email_submission_query_response : sig

     

       108
       108
       +
         type t = Query_response.t

     

       109
       109
       +
       end

     

       110
       110
       +
       

     

       111
       111
       +
       (** EmailSubmission/queryChanges: Args type (specialized from [Query_changes_args.t]). *)

     

       112
       112
       +
       module Email_submission_query_changes_args : sig

     

       113
       113
       +
         type t = Query_changes_args.t

     

       114
       114
       +
       end

     

       115
       115
       +
       

     

       116
       116
       +
       (** EmailSubmission/queryChanges: Response type (specialized from [Query_changes_response.t]). *)

     

       117
       117
       +
       module Email_submission_query_changes_response : sig

     

       118
       118
       +
         type t = Query_changes_response.t

     

       119
       119
       +
       end

     

       120
       120
       +
       

     

       121
       121
       +
       (** EmailSubmission/set: Args type (specialized from [('c, 'u) set_args]).

     

       122
       122
       +
           Includes onSuccess arguments.

     

       123
       123
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5> RFC 8621, Section 7.5 *)

     

       124
       124
       +
       type email_submission_set_args = {

     

       125
       125
       +
         set_account_id : id;

     

       126
       126
       +
         set_if_in_state : string option;

     

       127
       127
       +
         set_create : email_submission_create id_map option;

     

       128
       128
       +
         set_update : email_submission_update id_map option;

     

       129
       129
       +
         set_destroy : id list option;

     

       130
       130
       +
         set_on_success_destroy_email : id list option;

     

       131
       131
       +
       }

     

       132
       132
       +
       

     

       133
       133
       +
       (** EmailSubmission/set: Response type (specialized from [('c, 'u) Set_response.t]). *)

     

       134
       134
       +
       module Email_submission_set_response : sig

     

       135
       135
       +
         type t = (email_submission_created_info, email_submission_updated_info) Set_response.t

     

       136
       136
       +
       end

+131

jmap-email/jmap_thread.mli

···

       1
       1
       +
       (** JMAP Thread.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-3> RFC 8621, Section 3 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap.Types

     

       5
       5
       +
       open Jmap.Methods

     

       6
       6
       +
       

     

       7
       7
       +
       (** Thread object.

     

       8
       8
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-3> RFC 8621, Section 3 *)

     

       9
       9
       +
       module Thread : sig

     

       10
       10
       +
         type t

     

       11
       11
       +
       

     

       12
       12
       +
         (** Get the thread ID (server-set, immutable) *)

     

       13
       13
       +
         val id : t -> id

     

       14
       14
       +
         

     

       15
       15
       +
         (** Get the IDs of emails in the thread (server-set) *)

     

       16
       16
       +
         val email_ids : t -> id list

     

       17
       17
       +
         

     

       18
       18
       +
         (** Create a new Thread object *)

     

       19
       19
       +
         val v : id:id -> email_ids:id list -> t

     

       20
       20
       +
       end

     

       21
       21
       +
       

     

       22
       22
       +
       (** Thread properties that can be requested in Thread/get.

     

       23
       23
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-3.1> RFC 8621, Section 3.1 *)

     

       24
       24
       +
       type property =

     

       25
       25
       +
         | Id        (** The Thread id *)

     

       26
       26
       +
         | EmailIds  (** The list of email IDs in the Thread *)

     

       27
       27
       +
       

     

       28
       28
       +
       (** Convert a property variant to its string representation *)

     

       29
       29
       +
       val property_to_string : property -> string

     

       30
       30
       +
       

     

       31
       31
       +
       (** Parse a string into a property variant *)

     

       32
       32
       +
       val string_to_property : string -> property

     

       33
       33
       +
       

     

       34
       34
       +
       (** Get a list of all standard Thread properties *)

     

       35
       35
       +
       val all_properties : property list

     

       36
       36
       +
       

     

       37
       37
       +
       (** {1 Thread Methods} *)

     

       38
       38
       +
       

     

       39
       39
       +
       (** Arguments for Thread/get - extends standard get arguments.

     

       40
       40
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-3.1> RFC 8621, Section 3.1 *)

     

       41
       41
       +
       module Get_args : sig

     

       42
       42
       +
         type t

     

       43
       43
       +
       

     

       44
       44
       +
         val account_id : t -> id

     

       45
       45
       +
         val ids : t -> id list option

     

       46
       46
       +
         val properties : t -> string list option

     

       47
       47
       +
       

     

       48
       48
       +
         val v :

     

       49
       49
       +
           account_id:id ->

     

       50
       50
       +
           ?ids:id list ->

     

       51
       51
       +
           ?properties:string list ->

     

       52
       52
       +
           unit -> t

     

       53
       53
       +
       end

     

       54
       54
       +
       

     

       55
       55
       +
       (** Response for Thread/get - extends standard get response.

     

       56
       56
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-3.1> RFC 8621, Section 3.1 *)

     

       57
       57
       +
       module Get_response : sig

     

       58
       58
       +
         type t

     

       59
       59
       +
       

     

       60
       60
       +
         val account_id : t -> id

     

       61
       61
       +
         val state : t -> string

     

       62
       62
       +
         val list : t -> Thread.t list

     

       63
       63
       +
         val not_found : t -> id list

     

       64
       64
       +
       

     

       65
       65
       +
         val v :

     

       66
       66
       +
           account_id:id ->

     

       67
       67
       +
           state:string ->

     

       68
       68
       +
           list:Thread.t list ->

     

       69
       69
       +
           not_found:id list ->

     

       70
       70
       +
           unit -> t

     

       71
       71
       +
       end

     

       72
       72
       +
       

     

       73
       73
       +
       (** Arguments for Thread/changes - extends standard changes arguments.

     

       74
       74
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-3.2> RFC 8621, Section 3.2 *)

     

       75
       75
       +
       module Changes_args : sig

     

       76
       76
       +
         type t

     

       77
       77
       +
       

     

       78
       78
       +
         val account_id : t -> id

     

       79
       79
       +
         val since_state : t -> string

     

       80
       80
       +
         val max_changes : t -> uint option

     

       81
       81
       +
       

     

       82
       82
       +
         val v :

     

       83
       83
       +
           account_id:id ->

     

       84
       84
       +
           since_state:string ->

     

       85
       85
       +
           ?max_changes:uint ->

     

       86
       86
       +
           unit -> t

     

       87
       87
       +
       end

     

       88
       88
       +
       

     

       89
       89
       +
       (** Response for Thread/changes - extends standard changes response.

     

       90
       90
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-3.2> RFC 8621, Section 3.2 *)

     

       91
       91
       +
       module Changes_response : sig

     

       92
       92
       +
         type t

     

       93
       93
       +
       

     

       94
       94
       +
         val account_id : t -> id

     

       95
       95
       +
         val old_state : t -> string

     

       96
       96
       +
         val new_state : t -> string

     

       97
       97
       +
         val has_more_changes : t -> bool

     

       98
       98
       +
         val created : t -> id list

     

       99
       99
       +
         val updated : t -> id list

     

       100
       100
       +
         val destroyed : t -> id list

     

       101
       101
       +
       

     

       102
       102
       +
         val v :

     

       103
       103
       +
           account_id:id ->

     

       104
       104
       +
           old_state:string ->

     

       105
       105
       +
           new_state:string ->

     

       106
       106
       +
           has_more_changes:bool ->

     

       107
       107
       +
           created:id list ->

     

       108
       108
       +
           updated:id list ->

     

       109
       109
       +
           destroyed:id list ->

     

       110
       110
       +
           unit -> t

     

       111
       111
       +
       end

     

       112
       112
       +
       

     

       113
       113
       +
       (** {1 Helper Functions} *)

     

       114
       114
       +
       

     

       115
       115
       +
       (** Create a filter to find threads with specific email ID *)

     

       116
       116
       +
       val filter_has_email : id -> Filter.t

     

       117
       117
       +
       

     

       118
       118
       +
       (** Create a filter to find threads with emails from a specific sender *)

     

       119
       119
       +
       val filter_from : string -> Filter.t

     

       120
       120
       +
       

     

       121
       121
       +
       (** Create a filter to find threads with emails to a specific recipient *)

     

       122
       122
       +
       val filter_to : string -> Filter.t

     

       123
       123
       +
       

     

       124
       124
       +
       (** Create a filter to find threads with specific subject *)

     

       125
       125
       +
       val filter_subject : string -> Filter.t

     

       126
       126
       +
       

     

       127
       127
       +
       (** Create a filter to find threads with emails received before a date *)

     

       128
       128
       +
       val filter_before : date -> Filter.t

     

       129
       129
       +
       

     

       130
       130
       +
       (** Create a filter to find threads with emails received after a date *)

     

       131
       131
       +
       val filter_after : date -> Filter.t

+102

jmap-email/jmap_vacation.mli

···

       1
       1
       +
       (** JMAP Vacation Response.

     

       2
       2
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8> RFC 8621, Section 8 *)

     

       3
       3
       +
       

     

       4
       4
       +
       open Jmap.Types

     

       5
       5
       +
       open Jmap.Methods

     

       6
       6
       +
       open Jmap.Error

     

       7
       7
       +
       

     

       8
       8
       +
       (** VacationResponse object.

     

       9
       9
       +
           Note: id is always "singleton".

     

       10
       10
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8> RFC 8621, Section 8 *)

     

       11
       11
       +
       module Vacation_response : sig

     

       12
       12
       +
         type t

     

       13
       13
       +
         

     

       14
       14
       +
         (** Id of the vacation response (immutable, server-set, MUST be "singleton") *)

     

       15
       15
       +
         val id : t -> id

     

       16
       16
       +
         val is_enabled : t -> bool

     

       17
       17
       +
         val from_date : t -> utc_date option

     

       18
       18
       +
         val to_date : t -> utc_date option

     

       19
       19
       +
         val subject : t -> string option

     

       20
       20
       +
         val text_body : t -> string option

     

       21
       21
       +
         val html_body : t -> string option

     

       22
       22
       +
         

     

       23
       23
       +
         val v :

     

       24
       24
       +
           id:id ->

     

       25
       25
       +
           is_enabled:bool ->

     

       26
       26
       +
           ?from_date:utc_date ->

     

       27
       27
       +
           ?to_date:utc_date ->

     

       28
       28
       +
           ?subject:string ->

     

       29
       29
       +
           ?text_body:string ->

     

       30
       30
       +
           ?html_body:string ->

     

       31
       31
       +
           unit ->

     

       32
       32
       +
           t

     

       33
       33
       +
       end

     

       34
       34
       +
       

     

       35
       35
       +
       (** VacationResponse object for update.

     

       36
       36
       +
           Patch object, specific structure not enforced here.

     

       37
       37
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8.2> RFC 8621, Section 8.2 *)

     

       38
       38
       +
       type vacation_response_update = patch_object

     

       39
       39
       +
       

     

       40
       40
       +
       (** VacationResponse/get: Args type (specialized from ['record get_args]). *)

     

       41
       41
       +
       module Vacation_response_get_args : sig

     

       42
       42
       +
         type t = Vacation_response.t Get_args.t

     

       43
       43
       +
         

     

       44
       44
       +
         val v :

     

       45
       45
       +
           account_id:id ->

     

       46
       46
       +
           ?ids:id list ->

     

       47
       47
       +
           ?properties:string list ->

     

       48
       48
       +
           unit ->

     

       49
       49
       +
           t

     

       50
       50
       +
       end

     

       51
       51
       +
       

     

       52
       52
       +
       (** VacationResponse/get: Response type (specialized from ['record get_response]). *)

     

       53
       53
       +
       module Vacation_response_get_response : sig 

     

       54
       54
       +
         type t = Vacation_response.t Get_response.t

     

       55
       55
       +
         

     

       56
       56
       +
         val v :

     

       57
       57
       +
           account_id:id ->

     

       58
       58
       +
           state:string ->

     

       59
       59
       +
           list:Vacation_response.t list ->

     

       60
       60
       +
           not_found:id list ->

     

       61
       61
       +
           unit ->

     

       62
       62
       +
           t

     

       63
       63
       +
       end

     

       64
       64
       +
       

     

       65
       65
       +
       (** VacationResponse/set: Args type.

     

       66
       66
       +
           Only allows update, id must be "singleton".

     

       67
       67
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8.2> RFC 8621, Section 8.2 *)

     

       68
       68
       +
       module Vacation_response_set_args : sig

     

       69
       69
       +
         type t

     

       70
       70
       +
         

     

       71
       71
       +
         val account_id : t -> id

     

       72
       72
       +
         val if_in_state : t -> string option

     

       73
       73
       +
         val update : t -> vacation_response_update id_map option

     

       74
       74
       +
         

     

       75
       75
       +
         val v :

     

       76
       76
       +
           account_id:id ->

     

       77
       77
       +
           ?if_in_state:string ->

     

       78
       78
       +
           ?update:vacation_response_update id_map ->

     

       79
       79
       +
           unit ->

     

       80
       80
       +
           t

     

       81
       81
       +
       end

     

       82
       82
       +
       

     

       83
       83
       +
       (** VacationResponse/set: Response type.

     

       84
       84
       +
           @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8.2> RFC 8621, Section 8.2 *)

     

       85
       85
       +
       module Vacation_response_set_response : sig

     

       86
       86
       +
         type t

     

       87
       87
       +
         

     

       88
       88
       +
         val account_id : t -> id

     

       89
       89
       +
         val old_state : t -> string option

     

       90
       90
       +
         val new_state : t -> string

     

       91
       91
       +
         val updated : t -> Vacation_response.t option id_map option

     

       92
       92
       +
         val not_updated : t -> Set_error.t id_map option

     

       93
       93
       +
         

     

       94
       94
       +
         val v :

     

       95
       95
       +
           account_id:id ->

     

       96
       96
       +
           ?old_state:string ->

     

       97
       97
       +
           new_state:string ->

     

       98
       98
       +
           ?updated:Vacation_response.t option id_map ->

     

       99
       99
       +
           ?not_updated:Set_error.t id_map ->

     

       100
       100
       +
           unit ->

     

       101
       101
       +
           t

     

       102
       102
       +
       end

+35

jmap-email.opam

···

       1
       1
       +
       opam-version: "2.0"

     

       2
       2
       +
       name: "jmap-email"

     

       3
       3
       +
       version: "~dev"

     

       4
       4
       +
       synopsis: "JMAP Email extensions library (RFC 8621)"

     

       5
       5
       +
       description: """

     

       6
       6
       +
       OCaml implementation of the JMAP Mail extensions protocol as defined in RFC 8621.

     

       7
       7
       +
       Provides type definitions and structures for working with email in JMAP.

     

       8
       8
       +
       """

     

       9
       9
       +
       maintainer: ["user@example.com"]

     

       10
       10
       +
       authors: ["Example User"]

     

       11
       11
       +
       license: "MIT"

     

       12
       12
       +
       homepage: "https://github.com/example/jmap"

     

       13
       13
       +
       bug-reports: "https://github.com/example/jmap/issues"

     

       14
       14
       +
       depends: [

     

       15
       15
       +
         "ocaml" {>= "4.08.0"}

     

       16
       16
       +
         "dune" {>= "3.0"}

     

       17
       17
       +
         "jmap"

     

       18
       18
       +
         "yojson"

     

       19
       19
       +
         "uri"

     

       20
       20
       +
         "odoc" {with-doc}

     

       21
       21
       +
       ]

     

       22
       22
       +
       build: [

     

       23
       23
       +
         ["dune" "subst"] {dev}

     

       24
       24
       +
         [

     

       25
       25
       +
           "dune"

     

       26
       26
       +
           "build"

     

       27
       27
       +
           "-p"

     

       28
       28
       +
           name

     

       29
       29
       +
           "-j"

     

       30
       30
       +
           jobs

     

       31
       31
       +
           "@install"

     

       32
       32
       +
           "@runtest" {with-test}

     

       33
       33
       +
           "@doc" {with-doc}

     

       34
       34
       +
         ]

     

       35
       35
       +
       ]

+62

jmap-unix/README.md

···

       1
       1
       +
       # JMAP Unix Implementation

     

       2
       2
       +
       

     

       3
       3
       +
       This library provides Unix-specific implementation for the core JMAP protocol.

     

       4
       4
       +
       

     

       5
       5
       +
       ## Overview

     

       6
       6
       +
       

     

       7
       7
       +
       Jmap_unix provides the implementation needed to make actual connections to JMAP servers

     

       8
       8
       +
       using OCaml's Unix module. It handles:

     

       9
       9
       +
       

     

       10
       10
       +
       - HTTP connections to JMAP endpoints

     

       11
       11
       +
       - Authentication

     

       12
       12
       +
       - Session discovery

     

       13
       13
       +
       - Request/response handling

     

       14
       14
       +
       - Blob upload/download

     

       15
       15
       +
       - High-level email operations (Jmap_unix.Email)

     

       16
       16
       +
       

     

       17
       17
       +
       ## Usage

     

       18
       18
       +
       

     

       19
       19
       +
       ```ocaml

     

       20
       20
       +
       open Jmap

     

       21
       21
       +
       open Jmap_unix

     

       22
       22
       +
       

     

       23
       23
       +
       (* Create a connection to a JMAP server *)

     

       24
       24
       +
       let credentials = Basic("username", "password") in

     

       25
       25
       +
       let (ctx, session) = Jmap_unix.connect ~host:"jmap.example.com" ~credentials in

     

       26
       26
       +
       

     

       27
       27
       +
       (* Use the connection for JMAP requests *)

     

       28
       28
       +
       let response = Jmap_unix.request ctx request in

     

       29
       29
       +
       

     

       30
       30
       +
       (* Close the connection when done *)

     

       31
       31
       +
       Jmap_unix.close ctx

     

       32
       32
       +
       ```

     

       33
       33
       +
       

     

       34
       34
       +
       ## Email Operations

     

       35
       35
       +
       

     

       36
       36
       +
       The Email module provides high-level operations for working with emails:

     

       37
       37
       +
       

     

       38
       38
       +
       ```ocaml

     

       39
       39
       +
       open Jmap

     

       40
       40
       +
       open Jmap.Unix

     

       41
       41
       +
       

     

       42
       42
       +
       (* Get an email *)

     

       43
       43
       +
       let email = Email.get_email ctx ~account_id ~email_id ()

     

       44
       44
       +
       

     

       45
       45
       +
       (* Search for unread emails *)

     

       46
       46
       +
       let filter = Jmap_email.Email_filter.unread ()

     

       47
       47
       +
       let (ids, emails) = Email.search_emails ctx ~account_id ~filter ()

     

       48
       48
       +
       

     

       49
       49
       +
       (* Mark emails as read *)

     

       50
       50
       +
       Email.mark_as_seen ctx ~account_id ~email_ids:["email1"; "email2"] ()

     

       51
       51
       +
       

     

       52
       52
       +
       (* Move emails to another mailbox *)

     

       53
       53
       +
       Email.move_emails ctx ~account_id ~email_ids ~mailbox_id ()

     

       54
       54
       +
       ```

     

       55
       55
       +
       

     

       56
       56
       +
       ## Dependencies

     

       57
       57
       +
       

     

       58
       58
       +
       - jmap (core library)

     

       59
       59
       +
       - jmap-email (email types and helpers)

     

       60
       60
       +
       - yojson

     

       61
       61
       +
       - uri

     

       62
       62
       +
       - unix

jmap-unix/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name jmap_unix)

     

       3
       3
       +
        (public_name jmap-unix)

     

       4
       4
       +
        (libraries jmap jmap-email yojson uri unix)

     

       5
       5
       +
        (modules_without_implementation jmap_unix)

     

       6
       6
       +
        (modules jmap_unix))

+359

jmap-unix/jmap_unix.mli

···

       1
       1
       +
       (** Unix-specific JMAP client implementation interface.

     

       2
       2
       +
       

     

       3
       3
       +
           This module provides functions to interact with a JMAP server using

     

       4
       4
       +
           Unix sockets for network communication.

     

       5
       5
       +
           

     

       6
       6
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-4> RFC 8620, Section 4

     

       7
       7
       +
       *)

     

       8
       8
       +
       

     

       9
       9
       +
       (** Configuration options for a JMAP client context *)

     

       10
       10
       +
       type client_config = {

     

       11
       11
       +
         connect_timeout : float option;        (** Connection timeout in seconds *)

     

       12
       12
       +
         request_timeout : float option;        (** Request timeout in seconds *)

     

       13
       13
       +
         max_concurrent_requests : int option;  (** Maximum concurrent requests *)

     

       14
       14
       +
         max_request_size : int option;         (** Maximum request size in bytes *)

     

       15
       15
       +
         user_agent : string option;            (** User-Agent header value *)

     

       16
       16
       +
         authentication_header : string option; (** Custom Authentication header name *)

     

       17
       17
       +
       }

     

       18
       18
       +
       

     

       19
       19
       +
       (** Authentication method options *)

     

       20
       20
       +
       type auth_method = 

     

       21
       21
       +
         | Basic of string * string                  (** Basic auth with username and password *)

     

       22
       22
       +
         | Bearer of string                          (** Bearer token auth *)

     

       23
       23
       +
         | Custom of (string * string)               (** Custom header name and value *)

     

       24
       24
       +
         | Session_cookie of (string * string)       (** Session cookie name and value *)

     

       25
       25
       +
         | No_auth                                   (** No authentication *)

     

       26
       26
       +
       

     

       27
       27
       +
       (** Represents an active JMAP connection context. Opaque type. *)

     

       28
       28
       +
       type context

     

       29
       29
       +
       

     

       30
       30
       +
       (** Represents an active EventSource connection. Opaque type. *)

     

       31
       31
       +
       type event_source_connection

     

       32
       32
       +
       

     

       33
       33
       +
       (** A request builder for constructing and sending JMAP requests *)

     

       34
       34
       +
       type request_builder

     

       35
       35
       +
       

     

       36
       36
       +
       (** Create default configuration options *)

     

       37
       37
       +
       val default_config : unit -> client_config

     

       38
       38
       +
       

     

       39
       39
       +
       (** Create a client context with the specified configuration

     

       40
       40
       +
           @return The context object used for JMAP API calls

     

       41
       41
       +
       *)

     

       42
       42
       +
       val create_client : 

     

       43
       43
       +
         ?config:client_config -> 

     

       44
       44
       +
         unit -> 

     

       45
       45
       +
         context

     

       46
       46
       +
       

     

       47
       47
       +
       (** Connect to a JMAP server and retrieve the session.

     

       48
       48
       +
           This handles discovery (if needed) and authentication.

     

       49
       49
       +
           @param ctx The client context.

     

       50
       50
       +
           @param ?session_url Optional direct URL to the Session resource.

     

       51
       51
       +
           @param ?username Optional username (e.g., email address) for discovery.

     

       52
       52
       +
           @param ?auth_method Authentication method to use (default Basic).

     

       53
       53
       +
           @param credentials Authentication credentials.

     

       54
       54
       +
           @return A result with either (context, session) or an error.

     

       55
       55
       +
       *)

     

       56
       56
       +
       val connect : 

     

       57
       57
       +
         context ->

     

       58
       58
       +
         ?session_url:Uri.t ->

     

       59
       59
       +
         ?username:string ->

     

       60
       60
       +
         host:string -> 

     

       61
       61
       +
         ?port:int -> 

     

       62
       62
       +
         ?auth_method:auth_method ->

     

       63
       63
       +
         unit -> 

     

       64
       64
       +
         (context * Jmap.Session.Session.t) Jmap.Error.result

     

       65
       65
       +
       

     

       66
       66
       +
       (** Create a request builder for constructing a JMAP request.

     

       67
       67
       +
           @param ctx The client context.

     

       68
       68
       +
           @return A request builder object.

     

       69
       69
       +
       *)

     

       70
       70
       +
       val build : context -> request_builder

     

       71
       71
       +
       

     

       72
       72
       +
       (** Set the using capabilities for a request.

     

       73
       73
       +
           @param builder The request builder.

     

       74
       74
       +
           @param capabilities List of capability URIs to use.

     

       75
       75
       +
           @return The updated request builder.

     

       76
       76
       +
       *)

     

       77
       77
       +
       val using : request_builder -> string list -> request_builder

     

       78
       78
       +
       

     

       79
       79
       +
       (** Add a method call to a request builder.

     

       80
       80
       +
           @param builder The request builder.

     

       81
       81
       +
           @param name Method name (e.g., "Email/get").

     

       82
       82
       +
           @param args Method arguments.

     

       83
       83
       +
           @param id Method call ID.

     

       84
       84
       +
           @return The updated request builder.

     

       85
       85
       +
       *)

     

       86
       86
       +
       val add_method_call : 

     

       87
       87
       +
         request_builder -> 

     

       88
       88
       +
         string -> 

     

       89
       89
       +
         Yojson.Safe.t -> 

     

       90
       90
       +
         string -> 

     

       91
       91
       +
         request_builder

     

       92
       92
       +
       

     

       93
       93
       +
       (** Create a reference to a previous method call result.

     

       94
       94
       +
           @param result_of Method call ID to reference.

     

       95
       95
       +
           @param name Path in the response.

     

       96
       96
       +
           @return A ResultReference to use in another method call.

     

       97
       97
       +
       *)

     

       98
       98
       +
       val create_reference : string -> string -> Jmap.Wire.Result_reference.t

     

       99
       99
       +
       

     

       100
       100
       +
       (** Execute a request and return the response.

     

       101
       101
       +
           @param builder The request builder to execute.

     

       102
       102
       +
           @return The JMAP response from the server.

     

       103
       103
       +
       *)

     

       104
       104
       +
       val execute : request_builder -> Jmap.Wire.Response.t Jmap.Error.result 

     

       105
       105
       +
       

     

       106
       106
       +
       (** Perform a JMAP API request.

     

       107
       107
       +
           @param ctx The connection context.

     

       108
       108
       +
           @param request The JMAP request object.

     

       109
       109
       +
           @return The JMAP response from the server.

     

       110
       110
       +
       *)

     

       111
       111
       +
       val request : context -> Jmap.Wire.Request.t -> Jmap.Wire.Response.t Jmap.Error.result

     

       112
       112
       +
       

     

       113
       113
       +
       (** Upload binary data.

     

       114
       114
       +
           @param ctx The connection context.

     

       115
       115
       +
           @param account_id The target account ID.

     

       116
       116
       +
           @param content_type The MIME type of the data.

     

       117
       117
       +
           @param data_stream A stream providing the binary data chunks.

     

       118
       118
       +
           @return A result with either an upload response or an error.

     

       119
       119
       +
       *)

     

       120
       120
       +
       val upload : 

     

       121
       121
       +
         context -> 

     

       122
       122
       +
         account_id:Jmap.Types.id -> 

     

       123
       123
       +
         content_type:string -> 

     

       124
       124
       +
         data_stream:string Seq.t -> 

     

       125
       125
       +
         Jmap.Binary.Upload_response.t Jmap.Error.result

     

       126
       126
       +
       

     

       127
       127
       +
       (** Download binary data.

     

       128
       128
       +
           @param ctx The connection context.

     

       129
       129
       +
           @param account_id The account ID.

     

       130
       130
       +
           @param blob_id The blob ID to download.

     

       131
       131
       +
           @param ?content_type The desired Content-Type for the download response.

     

       132
       132
       +
           @param ?name The desired filename for the download response.

     

       133
       133
       +
           @return A result with either a stream of data chunks or an error.

     

       134
       134
       +
       *)

     

       135
       135
       +
       val download : 

     

       136
       136
       +
         context -> 

     

       137
       137
       +
         account_id:Jmap.Types.id -> 

     

       138
       138
       +
         blob_id:Jmap.Types.id -> 

     

       139
       139
       +
         ?content_type:string -> 

     

       140
       140
       +
         ?name:string -> 

     

       141
       141
       +
         (string Seq.t) Jmap.Error.result

     

       142
       142
       +
       

     

       143
       143
       +
       (** Copy blobs between accounts.

     

       144
       144
       +
           @param ctx The connection context.

     

       145
       145
       +
           @param from_account_id Source account ID.

     

       146
       146
       +
           @param account_id Destination account ID.

     

       147
       147
       +
           @param blob_ids List of blob IDs to copy.

     

       148
       148
       +
           @return A result with either the copy response or an error.

     

       149
       149
       +
       *)

     

       150
       150
       +
       val copy_blobs :

     

       151
       151
       +
         context ->

     

       152
       152
       +
         from_account_id:Jmap.Types.id ->

     

       153
       153
       +
         account_id:Jmap.Types.id ->

     

       154
       154
       +
         blob_ids:Jmap.Types.id list ->

     

       155
       155
       +
         Jmap.Binary.Blob_copy_response.t Jmap.Error.result

     

       156
       156
       +
       

     

       157
       157
       +
       (** Connect to the EventSource for push notifications.

     

       158
       158
       +
           @param ctx The connection context.

     

       159
       159
       +
           @param ?types List of types to subscribe to (default "*").

     

       160
       160
       +
           @param ?close_after Request server to close after first state event.

     

       161
       161
       +
           @param ?ping Request ping interval in seconds (default 0).

     

       162
       162
       +
           @return A result with either a tuple of connection handle and event stream, or an error.

     

       163
       163
       +
           @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.3> RFC 8620, Section 7.3 *)

     

       164
       164
       +
       val connect_event_source : 

     

       165
       165
       +
         context -> 

     

       166
       166
       +
         ?types:string list -> 

     

       167
       167
       +
         ?close_after:[`State | `No] -> 

     

       168
       168
       +
         ?ping:Jmap.Types.uint ->

     

       169
       169
       +
         (event_source_connection * 

     

       170
       170
       +
          ([`State of Jmap.Push.State_change.t | `Ping of Jmap.Push.Event_source_ping_data.t ] Seq.t)) Jmap.Error.result

     

       171
       171
       +
       

     

       172
       172
       +
       (** Create a websocket connection for JMAP over WebSocket.

     

       173
       173
       +
           @param ctx The connection context.

     

       174
       174
       +
           @return A result with either a websocket connection or an error.

     

       175
       175
       +
           @see <https://www.rfc-editor.org/rfc/rfc8887.html> RFC 8887 *)

     

       176
       176
       +
       val connect_websocket :

     

       177
       177
       +
         context ->

     

       178
       178
       +
         event_source_connection Jmap.Error.result

     

       179
       179
       +
       

     

       180
       180
       +
       (** Send a message over a websocket connection.

     

       181
       181
       +
           @param conn The websocket connection.

     

       182
       182
       +
           @param request The JMAP request to send.

     

       183
       183
       +
           @return A result with either the response or an error.

     

       184
       184
       +
       *)

     

       185
       185
       +
       val websocket_send :

     

       186
       186
       +
         event_source_connection ->

     

       187
       187
       +
         Jmap.Wire.Request.t ->

     

       188
       188
       +
         Jmap.Wire.Response.t Jmap.Error.result

     

       189
       189
       +
       

     

       190
       190
       +
       (** Close an EventSource or WebSocket connection.

     

       191
       191
       +
           @param conn The connection handle.

     

       192
       192
       +
           @return A result with either unit or an error.

     

       193
       193
       +
       *)

     

       194
       194
       +
       val close_connection : event_source_connection -> unit Jmap.Error.result

     

       195
       195
       +
       

     

       196
       196
       +
       (** Close the JMAP connection context. 

     

       197
       197
       +
           @return A result with either unit or an error.

     

       198
       198
       +
       *)

     

       199
       199
       +
       val close : context -> unit Jmap.Error.result

     

       200
       200
       +
       

     

       201
       201
       +
       (** {2 Helper Methods for Common Tasks} *)

     

       202
       202
       +
       

     

       203
       203
       +
       (** Helper to get a single object by ID.

     

       204
       204
       +
           @param ctx The context.

     

       205
       205
       +
           @param method_name The get method (e.g., "Email/get").

     

       206
       206
       +
           @param account_id The account ID.

     

       207
       207
       +
           @param object_id The ID of the object to get.

     

       208
       208
       +
           @param ?properties Optional list of properties to fetch.

     

       209
       209
       +
           @return A result with either the object as JSON or an error.

     

       210
       210
       +
       *)

     

       211
       211
       +
       val get_object :

     

       212
       212
       +
         context ->

     

       213
       213
       +
         method_name:string ->

     

       214
       214
       +
         account_id:Jmap.Types.id ->

     

       215
       215
       +
         object_id:Jmap.Types.id ->

     

       216
       216
       +
         ?properties:string list ->

     

       217
       217
       +
         Yojson.Safe.t Jmap.Error.result

     

       218
       218
       +
       

     

       219
       219
       +
       (** Helper to set up the connection with minimal options.

     

       220
       220
       +
           @param host The JMAP server hostname.

     

       221
       221
       +
           @param username Username for basic auth.

     

       222
       222
       +
           @param password Password for basic auth.

     

       223
       223
       +
           @return A result with either (context, session) or an error.

     

       224
       224
       +
       *)

     

       225
       225
       +
       val quick_connect :

     

       226
       226
       +
         host:string ->

     

       227
       227
       +
         username:string ->

     

       228
       228
       +
         password:string ->

     

       229
       229
       +
         (context * Jmap.Session.Session.t) Jmap.Error.result

     

       230
       230
       +
       

     

       231
       231
       +
       (** Perform a Core/echo request to test connectivity.

     

       232
       232
       +
           @param ctx The JMAP connection context.

     

       233
       233
       +
           @param ?data Optional data to echo back.

     

       234
       234
       +
           @return A result with either the response or an error.

     

       235
       235
       +
       *)

     

       236
       236
       +
       val echo : 

     

       237
       237
       +
         context -> 

     

       238
       238
       +
         ?data:Yojson.Safe.t -> 

     

       239
       239
       +
         unit -> 

     

       240
       240
       +
         Yojson.Safe.t Jmap.Error.result

     

       241
       241
       +
       

     

       242
       242
       +
       (** {2 Email Operations} *)

     

       243
       243
       +
       

     

       244
       244
       +
       (** High-level email operations that map to JMAP email methods *)

     

       245
       245
       +
       module Email : sig

     

       246
       246
       +
         open Jmap_email.Types

     

       247
       247
       +
         

     

       248
       248
       +
         (** Get an email by ID 

     

       249
       249
       +
             @param ctx The JMAP client context

     

       250
       250
       +
             @param account_id The account ID

     

       251
       251
       +
             @param email_id The email ID to fetch

     

       252
       252
       +
             @param ?properties Optional list of properties to fetch

     

       253
       253
       +
             @return The email object or an error

     

       254
       254
       +
         *)

     

       255
       255
       +
         val get_email : 

     

       256
       256
       +
           context -> 

     

       257
       257
       +
           account_id:Jmap.Types.id -> 

     

       258
       258
       +
           email_id:Jmap.Types.id -> 

     

       259
       259
       +
           ?properties:string list -> 

     

       260
       260
       +
           unit -> 

     

       261
       261
       +
           Email.t Jmap.Error.result

     

       262
       262
       +
         

     

       263
       263
       +
         (** Search for emails using a filter

     

       264
       264
       +
             @param ctx The JMAP client context

     

       265
       265
       +
             @param account_id The account ID

     

       266
       266
       +
             @param filter The search filter

     

       267
       267
       +
             @param ?sort Optional sort criteria (default received date newest first)

     

       268
       268
       +
             @param ?limit Optional maximum number of results

     

       269
       269
       +
             @param ?properties Optional properties to fetch for the matching emails

     

       270
       270
       +
             @return The list of matching email IDs and optionally the email objects

     

       271
       271
       +
         *)

     

       272
       272
       +
         val search_emails :

     

       273
       273
       +
           context ->

     

       274
       274
       +
           account_id:Jmap.Types.id ->

     

       275
       275
       +
           filter:Jmap.Methods.Filter.t ->

     

       276
       276
       +
           ?sort:Jmap.Methods.Comparator.t list ->

     

       277
       277
       +
           ?limit:Jmap.Types.uint ->

     

       278
       278
       +
           ?position:int ->

     

       279
       279
       +
           ?properties:string list ->

     

       280
       280
       +
           unit ->

     

       281
       281
       +
           (Jmap.Types.id list * Email.t list option) Jmap.Error.result

     

       282
       282
       +
           

     

       283
       283
       +
         (** Mark multiple emails with a keyword

     

       284
       284
       +
             @param ctx The JMAP client context

     

       285
       285
       +
             @param account_id The account ID

     

       286
       286
       +
             @param email_ids List of email IDs to update

     

       287
       287
       +
             @param keyword The keyword to add

     

       288
       288
       +
             @return The result of the operation

     

       289
       289
       +
         *)

     

       290
       290
       +
         val mark_emails :

     

       291
       291
       +
           context ->

     

       292
       292
       +
           account_id:Jmap.Types.id ->

     

       293
       293
       +
           email_ids:Jmap.Types.id list ->

     

       294
       294
       +
           keyword:Keywords.keyword ->

     

       295
       295
       +
           unit ->

     

       296
       296
       +
           unit Jmap.Error.result

     

       297
       297
       +
           

     

       298
       298
       +
         (** Mark emails as seen/read

     

       299
       299
       +
             @param ctx The JMAP client context

     

       300
       300
       +
             @param account_id The account ID

     

       301
       301
       +
             @param email_ids List of email IDs to mark

     

       302
       302
       +
             @return The result of the operation

     

       303
       303
       +
         *)

     

       304
       304
       +
         val mark_as_seen :

     

       305
       305
       +
           context ->

     

       306
       306
       +
           account_id:Jmap.Types.id ->

     

       307
       307
       +
           email_ids:Jmap.Types.id list ->

     

       308
       308
       +
           unit ->

     

       309
       309
       +
           unit Jmap.Error.result

     

       310
       310
       +
           

     

       311
       311
       +
         (** Mark emails as unseen/unread

     

       312
       312
       +
             @param ctx The JMAP client context

     

       313
       313
       +
             @param account_id The account ID

     

       314
       314
       +
             @param email_ids List of email IDs to mark

     

       315
       315
       +
             @return The result of the operation

     

       316
       316
       +
         *)

     

       317
       317
       +
         val mark_as_unseen :

     

       318
       318
       +
           context ->

     

       319
       319
       +
           account_id:Jmap.Types.id ->

     

       320
       320
       +
           email_ids:Jmap.Types.id list ->

     

       321
       321
       +
           unit ->

     

       322
       322
       +
           unit Jmap.Error.result

     

       323
       323
       +
         

     

       324
       324
       +
         (** Move emails to a different mailbox

     

       325
       325
       +
             @param ctx The JMAP client context

     

       326
       326
       +
             @param account_id The account ID

     

       327
       327
       +
             @param email_ids List of email IDs to move

     

       328
       328
       +
             @param mailbox_id Destination mailbox ID

     

       329
       329
       +
             @param ?remove_from_mailboxes Optional list of source mailbox IDs to remove from

     

       330
       330
       +
             @return The result of the operation

     

       331
       331
       +
         *)

     

       332
       332
       +
         val move_emails :

     

       333
       333
       +
           context ->

     

       334
       334
       +
           account_id:Jmap.Types.id ->

     

       335
       335
       +
           email_ids:Jmap.Types.id list ->

     

       336
       336
       +
           mailbox_id:Jmap.Types.id ->

     

       337
       337
       +
           ?remove_from_mailboxes:Jmap.Types.id list ->

     

       338
       338
       +
           unit ->

     

       339
       339
       +
           unit Jmap.Error.result

     

       340
       340
       +
         

     

       341
       341
       +
         (** Import an RFC822 message

     

       342
       342
       +
             @param ctx The JMAP client context

     

       343
       343
       +
             @param account_id The account ID

     

       344
       344
       +
             @param rfc822 Raw message content

     

       345
       345
       +
             @param mailbox_ids Mailboxes to add the message to

     

       346
       346
       +
             @param ?keywords Optional keywords to set

     

       347
       347
       +
             @param ?received_at Optional received timestamp

     

       348
       348
       +
             @return The ID of the imported email

     

       349
       349
       +
         *)

     

       350
       350
       +
         val import_email :

     

       351
       351
       +
           context ->

     

       352
       352
       +
           account_id:Jmap.Types.id ->

     

       353
       353
       +
           rfc822:string ->

     

       354
       354
       +
           mailbox_ids:Jmap.Types.id list ->

     

       355
       355
       +
           ?keywords:Keywords.t ->

     

       356
       356
       +
           ?received_at:Jmap.Types.date ->

     

       357
       357
       +
           unit ->

     

       358
       358
       +
           Jmap.Types.id Jmap.Error.result

     

       359
       359
       +
       end

+21

jmap-unix.opam

···

       1
       1
       +
       opam-version: "2.0"

     

       2
       2
       +
       name: "jmap-unix"

     

       3
       3
       +
       version: "~dev"

     

       4
       4
       +
       synopsis: "JMAP Unix implementation"

     

       5
       5
       +
       description: "Unix-specific implementation of the JMAP protocol (RFC8620)"

     

       6
       6
       +
       maintainer: ["maintainer@example.com"]

     

       7
       7
       +
       authors: ["JMAP OCaml Team"]

     

       8
       8
       +
       license: "MIT"

     

       9
       9
       +
       homepage: "https://github.com/example/jmap-ocaml"

     

       10
       10
       +
       bug-reports: "https://github.com/example/jmap-ocaml/issues"

     

       11
       11
       +
       depends: [

     

       12
       12
       +
         "ocaml" {>= "4.08.0"}

     

       13
       13
       +
         "dune" {>= "2.0.0"}

     

       14
       14
       +
         "jmap"

     

       15
       15
       +
         "yojson" {>= "1.7.0"}

     

       16
       16
       +
         "uri" {>= "4.0.0"}

     

       17
       17
       +
         "unix"

     

       18
       18
       +
       ]

     

       19
       19
       +
       build: [

     

       20
       20
       +
         ["dune" "build" "-p" name "-j" jobs]

     

       21
       21
       +
       ]

-31

jmap.opam

···

       1
       1
       -
       # This file is generated by dune, edit dune-project instead

     

       2
       2
       -
       opam-version: "2.0"

     

       3
       3
       -
       synopsis: "JMAP protocol"

     

       4
       4
       -
       description: "This is all still a work in progress"

     

       5
       5
       -
       maintainer: ["anil@recoil.org"]

     

       6
       6
       -
       authors: ["Anil Madhavapeddy"]

     

       7
       7
       -
       license: "ISC"

     

       8
       8
       -
       homepage: "https://github.com/avsm/jmap"

     

       9
       9
       -
       bug-reports: "https://github.com/avsm/jmap/issues"

     

       10
       10
       -
       depends: [

     

       11
       11
       -
         "dune" {>= "3.17"}

     

       12
       12
       -
         "ocaml" {>= "5.2.0"}

     

       13
       13
       -
         "ezjsonm"

     

       14
       14
       -
         "ptime"

     

       15
       15
       -
         "odoc" {with-doc}

     

       16
       16
       -
       ]

     

       17
       17
       -
       build: [

     

       18
       18
       -
         ["dune" "subst"] {dev}

     

       19
       19
       -
         [

     

       20
       20
       -
           "dune"

     

       21
       21
       -
           "build"

     

       22
       22
       -
           "-p"

     

       23
       23
       -
           name

     

       24
       24
       -
           "-j"

     

       25
       25
       -
           jobs

     

       26
       26
       -
           "@install"

     

       27
       27
       -
           "@runtest" {with-test}

     

       28
       28
       -
           "@doc" {with-doc}

     

       29
       29
       -
         ]

     

       30
       30
       -
       ]

     

       31
       31
       -
       dev-repo: "git+https://github.com/avsm/jmap.git"

-4

lib/dune

···

       1
       1
       -
       (library

     

       2
       2
       -
         (name jmap)

     

       3
       3
       -
         (public_name jmap)

     

       4
       4
       -
         (libraries ezjsonm ptime))

lib/jmap.ml

This is a binary file and will not be displayed.

lib/jmap.mli

This is a binary file and will not be displayed.

+896

spec/draft-ietf-mailmaint-messageflag-mailboxattribute-02.txt

···

       1
       1
       +
       

     

       2
       2
       +
       

     

       3
       3
       +
       

     

       4
       4
       +
       

     

       5
       5
       +
       MailMaint                                              N.M. Jenkins, Ed.

     

       6
       6
       +
       Internet-Draft                                                  Fastmail

     

       7
       7
       +
       Intended status: Informational                            D. Eggert, Ed.

     

       8
       8
       +
       Expires: 21 August 2025                                        Apple Inc

     

       9
       9
       +
                                                               17 February 2025

     

       10
       10
       +
       

     

       11
       11
       +
       

     

       12
       12
       +
        Registration of further IMAP/JMAP keywords and mailbox attribute names

     

       13
       13
       +
                 draft-ietf-mailmaint-messageflag-mailboxattribute-02

     

       14
       14
       +
       

     

       15
       15
       +
       Abstract

     

       16
       16
       +
       

     

       17
       17
       +
          This document defines a number of keywords that have been in use by

     

       18
       18
       +
          Fastmail and Apple respectively for some time.  It defines their

     

       19
       19
       +
          intended use.  Additionally some mailbox names with special meaning

     

       20
       20
       +
          have been in use by Fastmail, and this document defines their

     

       21
       21
       +
          intended use.  This document registers all of these names with IANA

     

       22
       22
       +
          to avoid name collisions.

     

       23
       23
       +
       

     

       24
       24
       +
       Status of This Memo

     

       25
       25
       +
       

     

       26
       26
       +
          This Internet-Draft is submitted in full conformance with the

     

       27
       27
       +
          provisions of BCP 78 and BCP 79.

     

       28
       28
       +
       

     

       29
       29
       +
          Internet-Drafts are working documents of the Internet Engineering

     

       30
       30
       +
          Task Force (IETF).  Note that other groups may also distribute

     

       31
       31
       +
          working documents as Internet-Drafts.  The list of current Internet-

     

       32
       32
       +
          Drafts is at https://datatracker.ietf.org/drafts/current/.

     

       33
       33
       +
       

     

       34
       34
       +
          Internet-Drafts are draft documents valid for a maximum of six months

     

       35
       35
       +
          and may be updated, replaced, or obsoleted by other documents at any

     

       36
       36
       +
          time.  It is inappropriate to use Internet-Drafts as reference

     

       37
       37
       +
          material or to cite them other than as "work in progress."

     

       38
       38
       +
       

     

       39
       39
       +
          This Internet-Draft will expire on 21 August 2025.

     

       40
       40
       +
       

     

       41
       41
       +
       Copyright Notice

     

       42
       42
       +
       

     

       43
       43
       +
          Copyright (c) 2025 IETF Trust and the persons identified as the

     

       44
       44
       +
          document authors.  All rights reserved.

     

       45
       45
       +
       

     

       46
       46
       +
       

     

       47
       47
       +
       

     

       48
       48
       +
       

     

       49
       49
       +
       

     

       50
       50
       +
       

     

       51
       51
       +
       

     

       52
       52
       +
       

     

       53
       53
       +
       

     

       54
       54
       +
       

     

       55
       55
       +
       

     

       56
       56
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 1]

     

       57
       57
       +
       

     

       58
       58
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       59
       59
       +
       

     

       60
       60
       +
       

     

       61
       61
       +
          This document is subject to BCP 78 and the IETF Trust's Legal

     

       62
       62
       +
          Provisions Relating to IETF Documents (https://trustee.ietf.org/

     

       63
       63
       +
          license-info) in effect on the date of publication of this document.

     

       64
       64
       +
          Please review these documents carefully, as they describe your rights

     

       65
       65
       +
          and restrictions with respect to this document.  Code Components

     

       66
       66
       +
          extracted from this document must include Revised BSD License text as

     

       67
       67
       +
          described in Section 4.e of the Trust Legal Provisions and are

     

       68
       68
       +
          provided without warranty as described in the Revised BSD License.

     

       69
       69
       +
       

     

       70
       70
       +
       Table of Contents

     

       71
       71
       +
       

     

       72
       72
       +
          1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3

     

       73
       73
       +
          2.  Requirements Language . . . . . . . . . . . . . . . . . . . .   4

     

       74
       74
       +
          3.  Flag Colors . . . . . . . . . . . . . . . . . . . . . . . . .   4

     

       75
       75
       +
            3.1.  Definition of the MailFlagBit Message Keyword . . . . . .   4

     

       76
       76
       +
            3.2.  Implementation Notes  . . . . . . . . . . . . . . . . . .   5

     

       77
       77
       +
          4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5

     

       78
       78
       +
            4.1.  IMAP/JMAP Keyword Registrations . . . . . . . . . . . . .   5

     

       79
       79
       +
              4.1.1.  $notify keyword registration  . . . . . . . . . . . .   5

     

       80
       80
       +
              4.1.2.  $muted keyword registration . . . . . . . . . . . . .   6

     

       81
       81
       +
              4.1.3.  $followed keyword registration  . . . . . . . . . . .   7

     

       82
       82
       +
              4.1.4.  $memo keyword registration  . . . . . . . . . . . . .   7

     

       83
       83
       +
              4.1.5.  $hasmemo keyword registration . . . . . . . . . . . .   8

     

       84
       84
       +
              4.1.6.  Attachment Detection  . . . . . . . . . . . . . . . .   8

     

       85
       85
       +
              4.1.7.  $autosent keyword registration  . . . . . . . . . . .   9

     

       86
       86
       +
              4.1.8.  $unsubscribed keyword registration  . . . . . . . . .  10

     

       87
       87
       +
              4.1.9.  $canunsubscribe keyword registration  . . . . . . . .  10

     

       88
       88
       +
              4.1.10. $imported keyword registration  . . . . . . . . . . .  11

     

       89
       89
       +
              4.1.11. $istrusted keyword registration . . . . . . . . . . .  11

     

       90
       90
       +
              4.1.12. $maskedemail keyword registration . . . . . . . . . .  12

     

       91
       91
       +
              4.1.13. $new keyword registration . . . . . . . . . . . . . .  12

     

       92
       92
       +
              4.1.14. $MailFlagBit0 keyword registration  . . . . . . . . .  13

     

       93
       93
       +
              4.1.15. $MailFlagBit1 keyword registration  . . . . . . . . .  13

     

       94
       94
       +
              4.1.16. $MailFlagBit2 keyword registration  . . . . . . . . .  13

     

       95
       95
       +
            4.2.  IMAP Mailbox Name Attributes Registrations  . . . . . . .  14

     

       96
       96
       +
              4.2.1.  Snoozed mailbox name attribute registration . . . . .  14

     

       97
       97
       +
              4.2.2.  Scheduled mailbox name attribute registration . . . .  14

     

       98
       98
       +
              4.2.3.  Memos mailbox name attribute registration . . . . . .  14

     

       99
       99
       +
          5.  Security Considerations . . . . . . . . . . . . . . . . . . .  15

     

       100
       100
       +
          6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  15

     

       101
       101
       +
            6.1.  Normative References  . . . . . . . . . . . . . . . . . .  15

     

       102
       102
       +
          Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  15

     

       103
       103
       +
       

     

       104
       104
       +
       

     

       105
       105
       +
       

     

       106
       106
       +
       

     

       107
       107
       +
       

     

       108
       108
       +
       

     

       109
       109
       +
       

     

       110
       110
       +
       

     

       111
       111
       +
       

     

       112
       112
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 2]

     

       113
       113
       +
       

     

       114
       114
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       115
       115
       +
       

     

       116
       116
       +
       

     

       117
       117
       +
       1.  Introduction

     

       118
       118
       +
       

     

       119
       119
       +
          The Internet Message Access Protocol (IMAP) specification [RFC9051]

     

       120
       120
       +
          defines the use of message keywords, and an "IMAP Keywords" registry

     

       121
       121
       +
          is created in [RFC5788].  Similarly [RFC8457] creates an "IMAP

     

       122
       122
       +
          Mailbox Name Attributes Registry".

     

       123
       123
       +
       

     

       124
       124
       +
          This document does the following:

     

       125
       125
       +
       

     

       126
       126
       +
          *  Defines 16 message keywords

     

       127
       127
       +
       

     

       128
       128
       +
             -  $notify

     

       129
       129
       +
       

     

       130
       130
       +
             -  $muted

     

       131
       131
       +
       

     

       132
       132
       +
             -  $followed

     

       133
       133
       +
       

     

       134
       134
       +
             -  $memo

     

       135
       135
       +
       

     

       136
       136
       +
             -  $hasmemo

     

       137
       137
       +
       

     

       138
       138
       +
             -  $hasattachment

     

       139
       139
       +
       

     

       140
       140
       +
             -  $hasnoattachment

     

       141
       141
       +
       

     

       142
       142
       +
             -  $autosent

     

       143
       143
       +
       

     

       144
       144
       +
             -  $unsubscribed

     

       145
       145
       +
       

     

       146
       146
       +
             -  $canunsubscribe

     

       147
       147
       +
       

     

       148
       148
       +
             -  $imported

     

       149
       149
       +
       

     

       150
       150
       +
             -  $istrusted

     

       151
       151
       +
       

     

       152
       152
       +
             -  $maskedemail

     

       153
       153
       +
       

     

       154
       154
       +
             -  $new

     

       155
       155
       +
       

     

       156
       156
       +
             -  $MailFlagBit0

     

       157
       157
       +
       

     

       158
       158
       +
             -  $MailFlagBit1

     

       159
       159
       +
       

     

       160
       160
       +
             -  $MailFlagBit2

     

       161
       161
       +
       

     

       162
       162
       +
          *  Defines 3 mailbox name attributes

     

       163
       163
       +
       

     

       164
       164
       +
             -  Snoozed

     

       165
       165
       +
       

     

       166
       166
       +
       

     

       167
       167
       +
       

     

       168
       168
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 3]

     

       169
       169
       +
       

     

       170
       170
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       171
       171
       +
       

     

       172
       172
       +
       

     

       173
       173
       +
             -  Scheduled

     

       174
       174
       +
       

     

       175
       175
       +
             -  Memos

     

       176
       176
       +
       

     

       177
       177
       +
          *  Registers these in the "IMAP Keywords" registry and "IMAP Mailbox

     

       178
       178
       +
             Name Attributes" registry respectively.

     

       179
       179
       +
       

     

       180
       180
       +
       2.  Requirements Language

     

       181
       181
       +
       

     

       182
       182
       +
          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

     

       183
       183
       +
          "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and

     

       184
       184
       +
          "OPTIONAL" in this document are to be interpreted as described in BCP

     

       185
       185
       +
          14 [RFC2119] [RFC8174] when, and only when, they appear in all

     

       186
       186
       +
          capitals, as shown here.

     

       187
       187
       +
       

     

       188
       188
       +
       3.  Flag Colors

     

       189
       189
       +
       

     

       190
       190
       +
          The Internet Message Access Protocol (IMAP) specification [RFC9051]

     

       191
       191
       +
          defines a \Flagged system flag to mark a message for urgent/special

     

       192
       192
       +
          attention.  The new keywords defined in Sections 4.1.14, 4.1.15, and

     

       193
       193
       +
          4.1.16 allow such a flagged message to have that flag be of one of 7

     

       194
       194
       +
          colors.

     

       195
       195
       +
       

     

       196
       196
       +
       3.1.  Definition of the MailFlagBit Message Keyword

     

       197
       197
       +
       

     

       198
       198
       +
          The 3 flag color keywords $MailFlagBit0, $MailFlagBit1, and

     

       199
       199
       +
          $MailFlagBit2 make up a bit pattern that define the color of the flag

     

       200
       200
       +
          as such:

     

       201
       201
       +
       

     

       202
       202
       +
                           +=======+=======+=======+========+

     

       203
       203
       +
                           | Bit 0 | Bit 1 | Bit 2 | Color  |

     

       204
       204
       +
                           +=======+=======+=======+========+

     

       205
       205
       +
                           | 0     | 0     | 0     | red    |

     

       206
       206
       +
                           +-------+-------+-------+--------+

     

       207
       207
       +
                           | 1     | 0     | 0     | orange |

     

       208
       208
       +
                           +-------+-------+-------+--------+

     

       209
       209
       +
                           | 0     | 1     | 0     | yellow |

     

       210
       210
       +
                           +-------+-------+-------+--------+

     

       211
       211
       +
                           | 1     | 1     | 1     | green  |

     

       212
       212
       +
                           +-------+-------+-------+--------+

     

       213
       213
       +
                           | 0     | 0     | 1     | blue   |

     

       214
       214
       +
                           +-------+-------+-------+--------+

     

       215
       215
       +
                           | 1     | 0     | 1     | purple |

     

       216
       216
       +
                           +-------+-------+-------+--------+

     

       217
       217
       +
                           | 0     | 1     | 1     | gray   |

     

       218
       218
       +
                           +-------+-------+-------+--------+

     

       219
       219
       +
       

     

       220
       220
       +
                                  Table 1: Flag Colors

     

       221
       221
       +
       

     

       222
       222
       +
       

     

       223
       223
       +
       

     

       224
       224
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 4]

     

       225
       225
       +
       

     

       226
       226
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       227
       227
       +
       

     

       228
       228
       +
       

     

       229
       229
       +
          These flags SHOULD be ignored if the \Flagged system flag is not set.

     

       230
       230
       +
          If the \Flagged system flag is set, the flagged status MAY be

     

       231
       231
       +
          displayed to the user in the color corresponding to the combination

     

       232
       232
       +
          of the 3 flag color keywords.

     

       233
       233
       +
       

     

       234
       234
       +
       3.2.  Implementation Notes

     

       235
       235
       +
       

     

       236
       236
       +
          A mail client that is aware of these flag color keywords SHOULD clear

     

       237
       237
       +
          all 3 flag color keywords when the user unflags the message, i.e.

     

       238
       238
       +
          when unsetting the \Flagged system flag, all 3 flag color keywords

     

       239
       239
       +
          SHOULD also be unset.

     

       240
       240
       +
       

     

       241
       241
       +
          A mail client SHOULD NOT set any of these flags unless the \Flagged

     

       242
       242
       +
          system flag is already set or is being set.

     

       243
       243
       +
       

     

       244
       244
       +
          Servers MAY unset these flag color keywords when a client unsets the

     

       245
       245
       +
          \Flagged system flag.

     

       246
       246
       +
       

     

       247
       247
       +
       4.  IANA Considerations

     

       248
       248
       +
       

     

       249
       249
       +
          3 IMAP/JMAP keywords are registered in the IMAP/JMAP keywords

     

       250
       250
       +
          registry, as established in RFC5788.

     

       251
       251
       +
       

     

       252
       252
       +
       4.1.  IMAP/JMAP Keyword Registrations

     

       253
       253
       +
       

     

       254
       254
       +
       4.1.1.  $notify keyword registration

     

       255
       255
       +
       

     

       256
       256
       +
          IMAP/JMAP keyword name:  $notify

     

       257
       257
       +
          Purpose:  Indicate to the client that a notification should be shown

     

       258
       258
       +
             for this message.

     

       259
       259
       +
          Private or Shared on a server:  SHARED

     

       260
       260
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       261
       261
       +
             keyword can cause automatic action.  On supporting clients, when a

     

       262
       262
       +
             new message is added to the mailstore with this keyword, the

     

       263
       263
       +
             client should show the user a notification.

     

       264
       264
       +
             Mail clients commonly show notifications for new mail, but often

     

       265
       265
       +
             the only option is to show a notification for every message that

     

       266
       266
       +
             arrives in the inbox.  This keyword allows the user to create

     

       267
       267
       +
             rules (or the server to automatically determine) specific messages

     

       268
       268
       +
             that should show a notification.

     

       269
       269
       +
             Notifications for these messages may be in addition to

     

       270
       270
       +
             notifications for messages matching other criteria, according to

     

       271
       271
       +
             user preference set on the client.

     

       272
       272
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       273
       273
       +
       

     

       274
       274
       +
       

     

       275
       275
       +
       

     

       276
       276
       +
       

     

       277
       277
       +
       

     

       278
       278
       +
       

     

       279
       279
       +
       

     

       280
       280
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 5]

     

       281
       281
       +
       

     

       282
       282
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       283
       283
       +
       

     

       284
       284
       +
       

     

       285
       285
       +
             server on delivery when a message meets criteria such that the

     

       286
       286
       +
             user should be shown a notification.  It may be cleared by a

     

       287
       287
       +
             client when the user opens, archives, or otherwise interacts with

     

       288
       288
       +
             the message.  Other clients connected to the same account may

     

       289
       289
       +
             choose to automatically close the notification if the flag is

     

       290
       290
       +
             cleared.

     

       291
       291
       +
          Related keywords:  None

     

       292
       292
       +
          Related IMAP capabilities:  None

     

       293
       293
       +
          Security considerations:  None

     

       294
       294
       +
          Published specification:  This document

     

       295
       295
       +
          Intended usage:  COMMON

     

       296
       296
       +
          Scope:  BOTH

     

       297
       297
       +
          Owner/Change controller:  IESG

     

       298
       298
       +
       

     

       299
       299
       +
       4.1.2.  $muted keyword registration

     

       300
       300
       +
       

     

       301
       301
       +
          IMAP/JMAP keyword name:  $muted

     

       302
       302
       +
          Purpose:  Indicate to the server that the user is not interested in

     

       303
       303
       +
             future replies to a particular thread.

     

       304
       304
       +
          Private or Shared on a server:  SHARED

     

       305
       305
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       306
       306
       +
             keyword can cause automatic action.  On supporting servers, when a

     

       307
       307
       +
             new message arrives that is in the same thread as a message with

     

       308
       308
       +
             this keyword the server may automatically process it in some way

     

       309
       309
       +
             to deprioritise it for the user, for example by moving it to the

     

       310
       310
       +
             archive or trash, or marking it read.  The exact action, whether

     

       311
       311
       +
             this is customisable by the user, and interaction with user rules

     

       312
       312
       +
             is vendor specific.

     

       313
       313
       +
             A message is defined to be in the same thread as another if the

     

       314
       314
       +
             server assigns them both the same thread id, as defined in

     

       315
       315
       +
             [RFC8474] Section 5.2 for IMAP or [RFC8621], Section 3 for JMAP.

     

       316
       316
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       317
       317
       +
             client when the user indicates they wish to mute or unmute a

     

       318
       318
       +
             thread.  When unmuting a thread, the client must remove the

     

       319
       319
       +
             keyword from every message in the thread that has it.

     

       320
       320
       +
          Related keywords:  Mutually exclusive with $followed.  If both are

     

       321
       321
       +
             specified on a thread, servers MUST behave as though only

     

       322
       322
       +
             $followed were set.

     

       323
       323
       +
          Related IMAP capabilities:  None

     

       324
       324
       +
          Security considerations:  Muting a thread can mean a user won't see a

     

       325
       325
       +
             reply.  If someone compromises a user's account, they may mute

     

       326
       326
       +
             threads where they don't want the user to see the reply, for

     

       327
       327
       +
             example when sending phishing to the user's contacts.  There are

     

       328
       328
       +
             many other ways an attacker with access to the user's mailbox can

     

       329
       329
       +
             also achieve this however, so this is not greatly increasing the

     

       330
       330
       +
             attack surface.

     

       331
       331
       +
          Published specification:  This document

     

       332
       332
       +
          Intended usage:  COMMON

     

       333
       333
       +
       

     

       334
       334
       +
       

     

       335
       335
       +
       

     

       336
       336
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 6]

     

       337
       337
       +
       

     

       338
       338
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       339
       339
       +
       

     

       340
       340
       +
       

     

       341
       341
       +
          Scope:  BOTH

     

       342
       342
       +
          Owner/Change controller:  IESG

     

       343
       343
       +
       

     

       344
       344
       +
       4.1.3.  $followed keyword registration

     

       345
       345
       +
       

     

       346
       346
       +
          IMAP/JMAP keyword name:  $followed

     

       347
       347
       +
          Purpose:  Indicate to the server that the user is particularly

     

       348
       348
       +
             interested in future replies to a particular thread.

     

       349
       349
       +
          Private or Shared on a server:  SHARED

     

       350
       350
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       351
       351
       +
             keyword can cause automatic action.  On supporting servers, when a

     

       352
       352
       +
             new message arrives that is in the same thread as a message with

     

       353
       353
       +
             this keyword the server may automatically process it in some way

     

       354
       354
       +
             to prioritise it for the user, for example by ignoring rules that

     

       355
       355
       +
             would make it skip the inbox, or automatically adding the $notify

     

       356
       356
       +
             keyword.  The exact action, whether this is customisable by the

     

       357
       357
       +
             user, and interaction with user rules is vendor specific.

     

       358
       358
       +
             A message is defined to be in the same thread as another if the

     

       359
       359
       +
             server assigns them both the same thread id, as defined in

     

       360
       360
       +
             [RFC8474] Section 5.2 for IMAP or [RFC8621], Section 3 for JMAP.

     

       361
       361
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       362
       362
       +
             client when the user indicates they wish to follow or unfollow a

     

       363
       363
       +
             thread.  When unfollowing a thread, the client must remove the

     

       364
       364
       +
             keyword from every message in the thread that has it.

     

       365
       365
       +
          Related keywords:  Mutually exclusive with $muted.  If both are

     

       366
       366
       +
             specified on a thread, servers MUST behave as though only

     

       367
       367
       +
             $followed were set.

     

       368
       368
       +
          Related IMAP capabilities:  None

     

       369
       369
       +
          Security considerations:  None

     

       370
       370
       +
          Published specification:  This document

     

       371
       371
       +
          Intended usage:  COMMON

     

       372
       372
       +
          Scope:  BOTH

     

       373
       373
       +
          Owner/Change controller:  IESG

     

       374
       374
       +
       

     

       375
       375
       +
       4.1.4.  $memo keyword registration

     

       376
       376
       +
       

     

       377
       377
       +
          IMAP/JMAP keyword name:  $memo

     

       378
       378
       +
          Purpose:  Indicate to the client that a message is a note-to-self

     

       379
       379
       +
             from the user regarding another message in the same thread.

     

       380
       380
       +
          Private or Shared on a server:  SHARED

     

       381
       381
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       382
       382
       +
             keyword is advisory.

     

       383
       383
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       384
       384
       +
             client when creating such a message.  The message should otherwise

     

       385
       385
       +
             be contructed like a reply to the message to which this memo is

     

       386
       386
       +
             attached (i.e. appropriate Subject and Reply-To headers set).  In

     

       387
       387
       +
             supporting clients, messages with this flag may be presented

     

       388
       388
       +
             differently to the user, attached to the message the memo is

     

       389
       389
       +
       

     

       390
       390
       +
       

     

       391
       391
       +
       

     

       392
       392
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 7]

     

       393
       393
       +
       

     

       394
       394
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       395
       395
       +
       

     

       396
       396
       +
       

     

       397
       397
       +
             commenting on, and may offer the user the ability to edit or

     

       398
       398
       +
             delete the memo.  (As messages are immutable, editing requires

     

       399
       399
       +
             replacing the message.)

     

       400
       400
       +
          Related keywords:  The $hasmemo keyword should be set/cleared at the

     

       401
       401
       +
             same time.

     

       402
       402
       +
          Related IMAP capabilities:  None

     

       403
       403
       +
          Security considerations:  None

     

       404
       404
       +
          Published specification:  This document

     

       405
       405
       +
          Intended usage:  COMMON

     

       406
       406
       +
          Scope:  BOTH

     

       407
       407
       +
          Owner/Change controller:  IESG

     

       408
       408
       +
       

     

       409
       409
       +
       4.1.5.  $hasmemo keyword registration

     

       410
       410
       +
       

     

       411
       411
       +
          IMAP/JMAP keyword name:  $hasmemo

     

       412
       412
       +
          Purpose:  Indicate to the client that a message has an associated

     

       413
       413
       +
             memo with the $memo keyword.

     

       414
       414
       +
          Private or Shared on a server:  SHARED

     

       415
       415
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       416
       416
       +
             keyword is advisory.

     

       417
       417
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       418
       418
       +
             client when creating a memo.  The memo gets the $memo keyword, the

     

       419
       419
       +
             message it is a note for gets the $hasmemo keyword.  This keyword

     

       420
       420
       +
             can help in searching for messages with memos, or deciding whether

     

       421
       421
       +
             to fetch the whole thread to look for memos when loading a

     

       422
       422
       +
             mailbox.

     

       423
       423
       +
          Related keywords:  A message with the $memo keyword should be

     

       424
       424
       +
             created/destroyed at the same time.

     

       425
       425
       +
          Related IMAP capabilities:  None

     

       426
       426
       +
          Security considerations:  None

     

       427
       427
       +
          Published specification:  This document

     

       428
       428
       +
          Intended usage:  COMMON

     

       429
       429
       +
          Scope:  BOTH

     

       430
       430
       +
          Owner/Change controller:  IESG

     

       431
       431
       +
       

     

       432
       432
       +
       4.1.6.  Attachment Detection

     

       433
       433
       +
       

     

       434
       434
       +
          The $hasattachment and $hasnoattachment are mutually exclusive.  A

     

       435
       435
       +
          message SHOULD NOT contain both keywords.

     

       436
       436
       +
       

     

       437
       437
       +
       4.1.6.1.  $hasattachment keyword registration

     

       438
       438
       +
       

     

       439
       439
       +
          IMAP/JMAP keyword name:  $hasattachment

     

       440
       440
       +
          Purpose:  Indicate to the client that a message has an attachment.

     

       441
       441
       +
          Private or Shared on a server:  SHARED

     

       442
       442
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       443
       443
       +
             keyword is advisory.

     

       444
       444
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       445
       445
       +
       

     

       446
       446
       +
       

     

       447
       447
       +
       

     

       448
       448
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 8]

     

       449
       449
       +
       

     

       450
       450
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       451
       451
       +
       

     

       452
       452
       +
       

     

       453
       453
       +
             server on messages it determines have an attachment.  This can

     

       454
       454
       +
             help mailbox clients indicate this to the user without having to

     

       455
       455
       +
             fetch the full message body structure.  Over JMAP, the

     

       456
       456
       +
             "hasAttachment" Email property should indicate the same value.

     

       457
       457
       +
          Related keywords:  $hasnoattachment

     

       458
       458
       +
          Related IMAP capabilities:  None

     

       459
       459
       +
          Security considerations:  None

     

       460
       460
       +
          Published specification:  This document

     

       461
       461
       +
          Intended usage:  COMMON

     

       462
       462
       +
          Scope:  BOTH

     

       463
       463
       +
          Owner/Change controller:  IESG

     

       464
       464
       +
       

     

       465
       465
       +
       4.1.6.2.  $hasnoattachment keyword registration

     

       466
       466
       +
       

     

       467
       467
       +
          IMAP/JMAP keyword name:  $hasnoattachment

     

       468
       468
       +
          Purpose:  Indicate to the client that a message does not have an

     

       469
       469
       +
             attachment.

     

       470
       470
       +
          Private or Shared on a server:  SHARED

     

       471
       471
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       472
       472
       +
             keyword is advisory.

     

       473
       473
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       474
       474
       +
             server on messages it determines does NOT have an attachment.

     

       475
       475
       +
             Over JMAP, the "hasNoAttachment" Email property should indicate

     

       476
       476
       +
             the same value.  This keyword is needed in addition to the

     

       477
       477
       +
             $hasattachment keyword, as a client cannot otherwise determine

     

       478
       478
       +
             whether the server has processed the message for the presence of

     

       479
       479
       +
             an attachment.  In other words, the absence of the $hasattachment

     

       480
       480
       +
             keyword for a message does not tell a client whether the message

     

       481
       481
       +
             actually contains an attachment, as the client has no information

     

       482
       482
       +
             on whether the server has processed the message.

     

       483
       483
       +
          Related keywords:  None

     

       484
       484
       +
          Related IMAP capabilities:  None

     

       485
       485
       +
          Security considerations:  None

     

       486
       486
       +
          Published specification:  This document

     

       487
       487
       +
          Intended usage:  COMMON

     

       488
       488
       +
          Scope:  BOTH

     

       489
       489
       +
          Owner/Change controller:  IESG

     

       490
       490
       +
       

     

       491
       491
       +
       4.1.7.  $autosent keyword registration

     

       492
       492
       +
       

     

       493
       493
       +
          IMAP/JMAP keyword name:  $autosent

     

       494
       494
       +
          Purpose:  Indicate to the client that a message was sent

     

       495
       495
       +
             automatically as a response due to a user rule or setting.

     

       496
       496
       +
          Private or Shared on a server:  SHARED

     

       497
       497
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       498
       498
       +
             keyword is advisory.

     

       499
       499
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       500
       500
       +
       

     

       501
       501
       +
       

     

       502
       502
       +
       

     

       503
       503
       +
       

     

       504
       504
       +
       Jenkins & Eggert         Expires 21 August 2025                 [Page 9]

     

       505
       505
       +
       

     

       506
       506
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       507
       507
       +
       

     

       508
       508
       +
       

     

       509
       509
       +
             server on the user's copy of their vacation response and other

     

       510
       510
       +
             automated messages sent on behalf of the user.  Clients may use

     

       511
       511
       +
             this to indicate to the user that this message was sent

     

       512
       512
       +
             automatically, as if they have forgotten the rule or vacation

     

       513
       513
       +
             response is set up they may be surprised to see it among their

     

       514
       514
       +
             sent items.

     

       515
       515
       +
          Related keywords:  None

     

       516
       516
       +
          Related IMAP capabilities:  None

     

       517
       517
       +
          Security considerations:  None

     

       518
       518
       +
          Published specification:  This document

     

       519
       519
       +
          Intended usage:  COMMON

     

       520
       520
       +
          Scope:  BOTH

     

       521
       521
       +
          Owner/Change controller:  IESG

     

       522
       522
       +
       

     

       523
       523
       +
       4.1.8.  $unsubscribed keyword registration

     

       524
       524
       +
       

     

       525
       525
       +
          IMAP/JMAP keyword name:  $unsubscribed

     

       526
       526
       +
          Purpose:  Indicate to the client that it has unsubscribed from the

     

       527
       527
       +
             thread this message is on.

     

       528
       528
       +
          Private or Shared on a server:  SHARED

     

       529
       529
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       530
       530
       +
             keyword is advisory.

     

       531
       531
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       532
       532
       +
             client on a message after attempting to unsubscribe from the

     

       533
       533
       +
             mailing list this message came from (e.g., after attempting

     

       534
       534
       +
             RFC8058 one-click List-Unsubscribe).  It allows clients to remind

     

       535
       535
       +
             the user that they have unsubscribed if they open the message

     

       536
       536
       +
             again.

     

       537
       537
       +
          Related keywords:  None

     

       538
       538
       +
          Related IMAP capabilities:  None

     

       539
       539
       +
          Security considerations:  None

     

       540
       540
       +
          Published specification:  This document

     

       541
       541
       +
          Intended usage:  COMMON

     

       542
       542
       +
          Scope:  BOTH

     

       543
       543
       +
          Owner/Change controller:  IESG

     

       544
       544
       +
       

     

       545
       545
       +
       4.1.9.  $canunsubscribe keyword registration

     

       546
       546
       +
       

     

       547
       547
       +
          IMAP/JMAP keyword name:  $canunsubscribe

     

       548
       548
       +
          Purpose:  Indicate to the client that this message has an

     

       549
       549
       +
             RFC8058-compliant List-Unsubscribe header.

     

       550
       550
       +
          Private or Shared on a server:  SHARED

     

       551
       551
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       552
       552
       +
             keyword is advisory.

     

       553
       553
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       554
       554
       +
       

     

       555
       555
       +
       

     

       556
       556
       +
       

     

       557
       557
       +
       

     

       558
       558
       +
       

     

       559
       559
       +
       

     

       560
       560
       +
       Jenkins & Eggert         Expires 21 August 2025                [Page 10]

     

       561
       561
       +
       

     

       562
       562
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       563
       563
       +
       

     

       564
       564
       +
       

     

       565
       565
       +
             server on messages with an RFC8058-compliant List-Unsubscribe

     

       566
       566
       +
             header.  It may only do so if the message passes vendor-specific

     

       567
       567
       +
             reputation checks.  It is intended to indicate to clients that

     

       568
       568
       +
             they may be able to do a one-click unsubscribe, without them

     

       569
       569
       +
             having to fetch the List-Unsubscribe header to determine themself.

     

       570
       570
       +
          Related keywords:  None

     

       571
       571
       +
          Related IMAP capabilities:  None

     

       572
       572
       +
          Security considerations:  None

     

       573
       573
       +
          Published specification:  This document

     

       574
       574
       +
          Intended usage:  COMMON

     

       575
       575
       +
          Scope:  BOTH

     

       576
       576
       +
          Owner/Change controller:  IESG

     

       577
       577
       +
       

     

       578
       578
       +
       4.1.10.  $imported keyword registration

     

       579
       579
       +
       

     

       580
       580
       +
          IMAP/JMAP keyword name:  $imported

     

       581
       581
       +
          Purpose:  Indicate to the client that this message was imported from

     

       582
       582
       +
             another mailbox.

     

       583
       583
       +
          Private or Shared on a server:  SHARED

     

       584
       584
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       585
       585
       +
             keyword is advisory.

     

       586
       586
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       587
       587
       +
             server on messages in imports from another mailbox.

     

       588
       588
       +
          Related keywords:  None

     

       589
       589
       +
          Related IMAP capabilities:  None

     

       590
       590
       +
          Security considerations:  None

     

       591
       591
       +
          Published specification:  This document

     

       592
       592
       +
          Intended usage:  COMMON

     

       593
       593
       +
          Scope:  BOTH

     

       594
       594
       +
          Owner/Change controller:  IESG

     

       595
       595
       +
       

     

       596
       596
       +
       4.1.11.  $istrusted keyword registration

     

       597
       597
       +
       

     

       598
       598
       +
          IMAP/JMAP keyword name:  $istrusted

     

       599
       599
       +
          Purpose:  Indicate to the client that the authenticity of the from

     

       600
       600
       +
             name and email address have been verified with complete confidence

     

       601
       601
       +
             by the server.

     

       602
       602
       +
          Private or Shared on a server:  SHARED

     

       603
       603
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       604
       604
       +
             keyword is advisory.  Clients may show a verification mark (often

     

       605
       605
       +
             a tick icon) on messages with this keyword to indicate their

     

       606
       606
       +
             trusted status to the user.

     

       607
       607
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       608
       608
       +
             server on messages it delivers where it wishes to confirm to the

     

       609
       609
       +
             user that this is a legitimate email they can trust.  It is

     

       610
       610
       +
             usually only used for the mailbox provider's own messages to the

     

       611
       611
       +
             customer, where they can know with absolute certainty that the

     

       612
       612
       +
             friendly from name and email address are legitimate.

     

       613
       613
       +
       

     

       614
       614
       +
       

     

       615
       615
       +
       

     

       616
       616
       +
       Jenkins & Eggert         Expires 21 August 2025                [Page 11]

     

       617
       617
       +
       

     

       618
       618
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       619
       619
       +
       

     

       620
       620
       +
       

     

       621
       621
       +
          Related keywords:  None

     

       622
       622
       +
          Related IMAP capabilities:  None

     

       623
       623
       +
          Security considerations:  Servers should make sure this keyword is

     

       624
       624
       +
             only set for messages that really are trusted!

     

       625
       625
       +
          Published specification:  This document

     

       626
       626
       +
          Intended usage:  COMMON

     

       627
       627
       +
          Scope:  BOTH

     

       628
       628
       +
          Owner/Change controller:  IESG

     

       629
       629
       +
       

     

       630
       630
       +
       4.1.12.  $maskedemail keyword registration

     

       631
       631
       +
       

     

       632
       632
       +
          IMAP/JMAP keyword name:  $maskedemail

     

       633
       633
       +
          Purpose:  Indicate to the client that the message was received via an

     

       634
       634
       +
             alias created for an individual sender.

     

       635
       635
       +
          Private or Shared on a server:  SHARED

     

       636
       636
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       637
       637
       +
             keyword is advisory.  Clients may show an icon to indicate to the

     

       638
       638
       +
             user this was received via a masked email address - an alias

     

       639
       639
       +
             created for a specific sender to hide the user's real email

     

       640
       640
       +
             address.

     

       641
       641
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       642
       642
       +
             server on messages it delivers that arrived via such an alias.

     

       643
       643
       +
          Related keywords:  None

     

       644
       644
       +
          Related IMAP capabilities:  None

     

       645
       645
       +
          Security considerations:  None

     

       646
       646
       +
          Published specification:  This document

     

       647
       647
       +
          Intended usage:  LIMITED

     

       648
       648
       +
          Scope:  BOTH

     

       649
       649
       +
          Owner/Change controller:  IESG

     

       650
       650
       +
       

     

       651
       651
       +
       4.1.13.  $new keyword registration

     

       652
       652
       +
       

     

       653
       653
       +
          IMAP/JMAP keyword name:  $new

     

       654
       654
       +
          Purpose:  Indicate to the client that a message should be made more

     

       655
       655
       +
             prominent to the user due to a recent action.

     

       656
       656
       +
          Private or Shared on a server:  SHARED

     

       657
       657
       +
          Is it an advisory keyword or may it cause an automatic action:  This 

     

       658
       658
       +
             keyword is advisory.  Clients may show the status of the message.

     

       659
       659
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       660
       660
       +
             server on messages after awakening them from snooze.  Clients

     

       661
       661
       +
             should clear the keyword when the message is opened.

     

       662
       662
       +
          Related keywords:  None

     

       663
       663
       +
          Related IMAP capabilities:  None

     

       664
       664
       +
          Security considerations:  None

     

       665
       665
       +
          Published specification:  This document

     

       666
       666
       +
          Intended usage:  LIMITED

     

       667
       667
       +
          Scope:  BOTH

     

       668
       668
       +
          Owner/Change controller:  IESG

     

       669
       669
       +
       

     

       670
       670
       +
       

     

       671
       671
       +
       

     

       672
       672
       +
       Jenkins & Eggert         Expires 21 August 2025                [Page 12]

     

       673
       673
       +
       

     

       674
       674
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       675
       675
       +
       

     

       676
       676
       +
       

     

       677
       677
       +
       4.1.14.  $MailFlagBit0 keyword registration

     

       678
       678
       +
       

     

       679
       679
       +
          IMAP/JMAP keyword name:  $MailFlagBit0

     

       680
       680
       +
          Purpose:  0 bit part of a 3-bit bitmask that defines the color of the

     

       681
       681
       +
             flag when the has the system flag \Flagged set.  See Section 3 for

     

       682
       682
       +
             details.

     

       683
       683
       +
          Private or Shared on a server:  SHARED

     

       684
       684
       +
          Is it an advisory keyword or may it cause an automatic action:  No

     

       685
       685
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       686
       686
       +
             client as the result of a user action to "flag" a message for

     

       687
       687
       +
             urgent/special attention.

     

       688
       688
       +
          Related keywords:  $MailFlagBit1, $MailFlagBit2

     

       689
       689
       +
          Related IMAP capabilities:  None

     

       690
       690
       +
          Security considerations:  None

     

       691
       691
       +
          Published specification:  This document

     

       692
       692
       +
          Intended usage:  COMMON

     

       693
       693
       +
          Owner/Change controller:  IESG

     

       694
       694
       +
       

     

       695
       695
       +
       4.1.15.  $MailFlagBit1 keyword registration

     

       696
       696
       +
       

     

       697
       697
       +
          IMAP/JMAP keyword name:  $MailFlagBit1

     

       698
       698
       +
          Purpose:  0 bit part of a 3-bit bitmask that defines the color of the

     

       699
       699
       +
             flag when the has the system flag \Flagged set.  See Section 3 for

     

       700
       700
       +
             details.

     

       701
       701
       +
          Private or Shared on a server:  SHARED

     

       702
       702
       +
          Is it an advisory keyword or may it cause an automatic action:  No

     

       703
       703
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       704
       704
       +
             client as the result of a user action to "flag" a message for

     

       705
       705
       +
             urgent/special attention.

     

       706
       706
       +
          Related keywords:  $MailFlagBit0, $MailFlagBit2

     

       707
       707
       +
          Related IMAP capabilities:  None

     

       708
       708
       +
          Security considerations:  None

     

       709
       709
       +
          Published specification:  This document

     

       710
       710
       +
          Intended usage:  COMMON

     

       711
       711
       +
          Owner/Change controller:  IESG

     

       712
       712
       +
       

     

       713
       713
       +
       4.1.16.  $MailFlagBit2 keyword registration

     

       714
       714
       +
       

     

       715
       715
       +
          IMAP/JMAP keyword name:  $MailFlagBit2

     

       716
       716
       +
          Purpose:  0 bit part of a 3-bit bitmask that defines the color of the

     

       717
       717
       +
             flag when the has the system flag \Flagged set.  See Section 3 for

     

       718
       718
       +
             details.

     

       719
       719
       +
          Private or Shared on a server:  SHARED

     

       720
       720
       +
          Is it an advisory keyword or may it cause an automatic action:  No

     

       721
       721
       +
          When/by whom the keyword is set/cleared:  This keyword is set by a

     

       722
       722
       +
             client as the result of a user action to "flag" a message for

     

       723
       723
       +
             urgent/special attention.

     

       724
       724
       +
          Related keywords:  $MailFlagBit0, $MailFlagBit1

     

       725
       725
       +
       

     

       726
       726
       +
       

     

       727
       727
       +
       

     

       728
       728
       +
       Jenkins & Eggert         Expires 21 August 2025                [Page 13]

     

       729
       729
       +
       

     

       730
       730
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       731
       731
       +
       

     

       732
       732
       +
       

     

       733
       733
       +
          Related IMAP capabilities:  None

     

       734
       734
       +
          Security considerations:  None

     

       735
       735
       +
          Published specification:  This document

     

       736
       736
       +
          Intended usage:  COMMON

     

       737
       737
       +
          Owner/Change controller:  IESG

     

       738
       738
       +
       

     

       739
       739
       +
       4.2.  IMAP Mailbox Name Attributes Registrations

     

       740
       740
       +
       

     

       741
       741
       +
          This section lists mailbox name attributes to be registered with the

     

       742
       742
       +
          "IMAP Mailbox Name Attributes" created with [RFC8457].

     

       743
       743
       +
       

     

       744
       744
       +
          Note that none of the attribute names in this seciton have an implied

     

       745
       745
       +
          backslash.  This sets them apart from those specified in Section 2 of

     

       746
       746
       +
          [RFC6154].

     

       747
       747
       +
       

     

       748
       748
       +
       4.2.1.  Snoozed mailbox name attribute registration

     

       749
       749
       +
       

     

       750
       750
       +
          Attribute Name:  Snoozed

     

       751
       751
       +
          Description:  Messages that have been snoozed are moved to this

     

       752
       752
       +
             mailbox until the "awaken" time, when they are moved out of it

     

       753
       753
       +
             again automatically by the server.

     

       754
       754
       +
          Reference:  This document.

     

       755
       755
       +
          Usage Notes:  Snooze functionality is common among services but not

     

       756
       756
       +
             yet standardised.  This attribute marks the mailbox where snoozed

     

       757
       757
       +
             messages may be found, but does not on its own provide a way for

     

       758
       758
       +
             clients to snooze messages.

     

       759
       759
       +
       

     

       760
       760
       +
       4.2.2.  Scheduled mailbox name attribute registration

     

       761
       761
       +
       

     

       762
       762
       +
          Attribute Name:  Scheduled

     

       763
       763
       +
          Description:  Messages that have been scheduled to send at a later

     

       764
       764
       +
             time.  Once the server has sent them at the scheduled time, they

     

       765
       765
       +
             will automatically be deleted or moved from this mailbox by the

     

       766
       766
       +
             server (probably to the \Sent mailbox).

     

       767
       767
       +
          Reference:  This document.

     

       768
       768
       +
          Usage Notes:  Scheduled sending functionality is common among

     

       769
       769
       +
             services but not yet standardised.  This attribute marks the

     

       770
       770
       +
             mailbox where scheduled messages may be found, but does not on its

     

       771
       771
       +
             own provide a way for clients to schedule messages for sending.

     

       772
       772
       +
       

     

       773
       773
       +
       4.2.3.  Memos mailbox name attribute registration

     

       774
       774
       +
       

     

       775
       775
       +
          Attribute Name:  Memos

     

       776
       776
       +
          Description:  Messages that have the $memo keyword.  Clients creating

     

       777
       777
       +
             memos are recommended to store them in this mailbox.  This allows

     

       778
       778
       +
             them to more easily be hidden from the user as "messages", and

     

       779
       779
       +
             presented only as memos instead.

     

       780
       780
       +
          Reference:  This document.

     

       781
       781
       +
       

     

       782
       782
       +
       

     

       783
       783
       +
       

     

       784
       784
       +
       Jenkins & Eggert         Expires 21 August 2025                [Page 14]

     

       785
       785
       +
       

     

       786
       786
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       787
       787
       +
       

     

       788
       788
       +
       

     

       789
       789
       +
          Usage Notes:  None.

     

       790
       790
       +
       

     

       791
       791
       +
       5.  Security Considerations

     

       792
       792
       +
       

     

       793
       793
       +
          This document should not affect the security of the Internet.

     

       794
       794
       +
       

     

       795
       795
       +
       6.  References

     

       796
       796
       +
       

     

       797
       797
       +
       6.1.  Normative References

     

       798
       798
       +
       

     

       799
       799
       +
          [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate

     

       800
       800
       +
                     Requirement Levels", BCP 14, RFC 2119,

     

       801
       801
       +
                     DOI 10.17487/RFC2119, March 1997,

     

       802
       802
       +
                     <https://www.rfc-editor.org/info/rfc2119>.

     

       803
       803
       +
       

     

       804
       804
       +
          [RFC6154]  Leiba, B. and J. Nicolson, "IMAP LIST Extension for

     

       805
       805
       +
                     Special-Use Mailboxes", RFC 6154, DOI 10.17487/RFC6154,

     

       806
       806
       +
                     March 2011, <https://www.rfc-editor.org/info/rfc6154>.

     

       807
       807
       +
       

     

       808
       808
       +
          [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC

     

       809
       809
       +
                     2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,

     

       810
       810
       +
                     May 2017, <https://www.rfc-editor.org/info/rfc8174>.

     

       811
       811
       +
       

     

       812
       812
       +
          [RFC8457]  Leiba, B., Ed., "IMAP "$Important" Keyword and

     

       813
       813
       +
                     "\Important" Special-Use Attribute", RFC 8457,

     

       814
       814
       +
                     DOI 10.17487/RFC8457, September 2018,

     

       815
       815
       +
                     <https://www.rfc-editor.org/info/rfc8457>.

     

       816
       816
       +
       

     

       817
       817
       +
          [RFC8474]  Gondwana, B., Ed., "IMAP Extension for Object

     

       818
       818
       +
                     Identifiers", RFC 8474, DOI 10.17487/RFC8474, September

     

       819
       819
       +
                     2018, <https://www.rfc-editor.org/info/rfc8474>.

     

       820
       820
       +
       

     

       821
       821
       +
          [RFC8621]  Jenkins, N. and C. Newman, "The JSON Meta Application

     

       822
       822
       +
                     Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621,

     

       823
       823
       +
                     August 2019, <https://www.rfc-editor.org/info/rfc8621>.

     

       824
       824
       +
       

     

       825
       825
       +
          [RFC9051]  Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message

     

       826
       826
       +
                     Access Protocol (IMAP) - Version 4rev2", RFC 9051,

     

       827
       827
       +
                     DOI 10.17487/RFC9051, August 2021,

     

       828
       828
       +
                     <https://www.rfc-editor.org/info/rfc9051>.

     

       829
       829
       +
       

     

       830
       830
       +
          [RFC5788]  Melnikov, A. and D. Cridland, "IMAP4 Keyword Registry",

     

       831
       831
       +
                     RFC 5788, DOI 10.17487/RFC5788, March 2010,

     

       832
       832
       +
                     <https://www.rfc-editor.org/info/rfc5788>.

     

       833
       833
       +
       

     

       834
       834
       +
       Authors' Addresses

     

       835
       835
       +
       

     

       836
       836
       +
       

     

       837
       837
       +
       

     

       838
       838
       +
       

     

       839
       839
       +
       

     

       840
       840
       +
       Jenkins & Eggert         Expires 21 August 2025                [Page 15]

     

       841
       841
       +
       

     

       842
       842
       +
       Internet-Draft   Further IMAP/JMAP keywords & attributes   February 2025

     

       843
       843
       +
       

     

       844
       844
       +
       

     

       845
       845
       +
          Neil Jenkins (editor)

     

       846
       846
       +
          Fastmail

     

       847
       847
       +
          PO Box 234, Collins St West

     

       848
       848
       +
          Melbourne  VIC 8007

     

       849
       849
       +
          Australia

     

       850
       850
       +
          Email: neilj@fastmailteam.com

     

       851
       851
       +
          URI:   https://www.fastmail.com

     

       852
       852
       +
       

     

       853
       853
       +
       

     

       854
       854
       +
          Daniel Eggert (editor)

     

       855
       855
       +
          Apple Inc

     

       856
       856
       +
          One Apple Park Way

     

       857
       857
       +
          Cupertino,  CA 95014

     

       858
       858
       +
          United States of America

     

       859
       859
       +
          Email: deggert@apple.com

     

       860
       860
       +
          URI:   https://www.apple.com

     

       861
       861
       +
       

     

       862
       862
       +
       

     

       863
       863
       +
       

     

       864
       864
       +
       

     

       865
       865
       +
       

     

       866
       866
       +
       

     

       867
       867
       +
       

     

       868
       868
       +
       

     

       869
       869
       +
       

     

       870
       870
       +
       

     

       871
       871
       +
       

     

       872
       872
       +
       

     

       873
       873
       +
       

     

       874
       874
       +
       

     

       875
       875
       +
       

     

       876
       876
       +
       

     

       877
       877
       +
       

     

       878
       878
       +
       

     

       879
       879
       +
       

     

       880
       880
       +
       

     

       881
       881
       +
       

     

       882
       882
       +
       

     

       883
       883
       +
       

     

       884
       884
       +
       

     

       885
       885
       +
       

     

       886
       886
       +
       

     

       887
       887
       +
       

     

       888
       888
       +
       

     

       889
       889
       +
       

     

       890
       890
       +
       

     

       891
       891
       +
       

     

       892
       892
       +
       

     

       893
       893
       +
       

     

       894
       894
       +
       

     

       895
       895
       +
       

     

       896
       896
       +
       Jenkins & Eggert         Expires 21 August 2025                [Page 16]

+6051

spec/rfc8621.txt

···

       1
       1
       +
       

     

       2
       2
       +
       

     

       3
       3
       +
       

     

       4
       4
       +
       

     

       5
       5
       +
       

     

       6
       6
       +
       

     

       7
       7
       +
       Internet Engineering Task Force (IETF)                        N. Jenkins

     

       8
       8
       +
       Request for Comments: 8621                                      Fastmail

     

       9
       9
       +
       Updates: 5788                                                  C. Newman

     

       10
       10
       +
       Category: Standards Track                                         Oracle

     

       11
       11
       +
       ISSN: 2070-1721                                              August 2019

     

       12
       12
       +
       

     

       13
       13
       +
       

     

       14
       14
       +
                  The JSON Meta Application Protocol (JMAP) for Mail

     

       15
       15
       +
       

     

       16
       16
       +
       Abstract

     

       17
       17
       +
       

     

       18
       18
       +
          This document specifies a data model for synchronising email data

     

       19
       19
       +
          with a server using the JSON Meta Application Protocol (JMAP).

     

       20
       20
       +
          Clients can use this to efficiently search, access, organise, and

     

       21
       21
       +
          send messages, and to get push notifications for fast

     

       22
       22
       +
          resynchronisation when new messages are delivered or a change is made

     

       23
       23
       +
          in another client.

     

       24
       24
       +
       

     

       25
       25
       +
       Status of This Memo

     

       26
       26
       +
       

     

       27
       27
       +
          This is an Internet Standards Track document.

     

       28
       28
       +
       

     

       29
       29
       +
          This document is a product of the Internet Engineering Task Force

     

       30
       30
       +
          (IETF).  It represents the consensus of the IETF community.  It has

     

       31
       31
       +
          received public review and has been approved for publication by the

     

       32
       32
       +
          Internet Engineering Steering Group (IESG).  Further information on

     

       33
       33
       +
          Internet Standards is available in Section 2 of RFC 7841.

     

       34
       34
       +
       

     

       35
       35
       +
          Information about the current status of this document, any errata,

     

       36
       36
       +
          and how to provide feedback on it may be obtained at

     

       37
       37
       +
          https://www.rfc-editor.org/info/rfc8621.

     

       38
       38
       +
       

     

       39
       39
       +
       Copyright Notice

     

       40
       40
       +
       

     

       41
       41
       +
          Copyright (c) 2019 IETF Trust and the persons identified as the

     

       42
       42
       +
          document authors.  All rights reserved.

     

       43
       43
       +
       

     

       44
       44
       +
          This document is subject to BCP 78 and the IETF Trust's Legal

     

       45
       45
       +
          Provisions Relating to IETF Documents

     

       46
       46
       +
          (https://trustee.ietf.org/license-info) in effect on the date of

     

       47
       47
       +
          publication of this document.  Please review these documents

     

       48
       48
       +
          carefully, as they describe your rights and restrictions with respect

     

       49
       49
       +
          to this document.  Code Components extracted from this document must

     

       50
       50
       +
          include Simplified BSD License text as described in Section 4.e of

     

       51
       51
       +
          the Trust Legal Provisions and are provided without warranty as

     

       52
       52
       +
          described in the Simplified BSD License.

     

       53
       53
       +
       

     

       54
       54
       +
       

     

       55
       55
       +
       

     

       56
       56
       +
       

     

       57
       57
       +
       

     

       58
       58
       +
       Jenkins & Newman             Standards Track                    [Page 1]

     

       59
       59
       +
       

     

       60
       60
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       61
       61
       +
       

     

       62
       62
       +
       

     

       63
       63
       +
       Table of Contents

     

       64
       64
       +
       

     

       65
       65
       +
          1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4

     

       66
       66
       +
            1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   4

     

       67
       67
       +
            1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   5

     

       68
       68
       +
            1.3.  Additions to the Capabilities Object  . . . . . . . . . .   5

     

       69
       69
       +
              1.3.1.  urn:ietf:params:jmap:mail . . . . . . . . . . . . . .   5

     

       70
       70
       +
              1.3.2.  urn:ietf:params:jmap:submission . . . . . . . . . . .   7

     

       71
       71
       +
              1.3.3.  urn:ietf:params:jmap:vacationresponse . . . . . . . .   8

     

       72
       72
       +
            1.4.  Data Type Support in Different Accounts . . . . . . . . .   8

     

       73
       73
       +
            1.5.  Push  . . . . . . . . . . . . . . . . . . . . . . . . . .   8

     

       74
       74
       +
              1.5.1.  Example . . . . . . . . . . . . . . . . . . . . . . .   9

     

       75
       75
       +
            1.6.  Ids . . . . . . . . . . . . . . . . . . . . . . . . . . .   9

     

       76
       76
       +
          2.  Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . .   9

     

       77
       77
       +
            2.1.  Mailbox/get . . . . . . . . . . . . . . . . . . . . . . .  14

     

       78
       78
       +
            2.2.  Mailbox/changes . . . . . . . . . . . . . . . . . . . . .  14

     

       79
       79
       +
            2.3.  Mailbox/query . . . . . . . . . . . . . . . . . . . . . .  14

     

       80
       80
       +
            2.4.  Mailbox/queryChanges  . . . . . . . . . . . . . . . . . .  15

     

       81
       81
       +
            2.5.  Mailbox/set . . . . . . . . . . . . . . . . . . . . . . .  16

     

       82
       82
       +
            2.6.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  17

     

       83
       83
       +
          3.  Threads . . . . . . . . . . . . . . . . . . . . . . . . . . .  20

     

       84
       84
       +
            3.1.  Thread/get  . . . . . . . . . . . . . . . . . . . . . . .  22

     

       85
       85
       +
              3.1.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  22

     

       86
       86
       +
            3.2.  Thread/changes  . . . . . . . . . . . . . . . . . . . . .  22

     

       87
       87
       +
          4.  Emails  . . . . . . . . . . . . . . . . . . . . . . . . . . .  22

     

       88
       88
       +
            4.1.  Properties of the Email Object  . . . . . . . . . . . . .  23

     

       89
       89
       +
              4.1.1.  Metadata  . . . . . . . . . . . . . . . . . . . . . .  24

     

       90
       90
       +
              4.1.2.  Header Fields Parsed Forms  . . . . . . . . . . . . .  26

     

       91
       91
       +
              4.1.3.  Header Fields Properties  . . . . . . . . . . . . . .  32

     

       92
       92
       +
              4.1.4.  Body Parts  . . . . . . . . . . . . . . . . . . . . .  35

     

       93
       93
       +
            4.2.  Email/get . . . . . . . . . . . . . . . . . . . . . . . .  42

     

       94
       94
       +
              4.2.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  44

     

       95
       95
       +
            4.3.  Email/changes . . . . . . . . . . . . . . . . . . . . . .  45

     

       96
       96
       +
            4.4.  Email/query . . . . . . . . . . . . . . . . . . . . . . .  45

     

       97
       97
       +
              4.4.1.  Filtering . . . . . . . . . . . . . . . . . . . . . .  46

     

       98
       98
       +
              4.4.2.  Sorting . . . . . . . . . . . . . . . . . . . . . . .  49

     

       99
       99
       +
              4.4.3.  Thread Collapsing . . . . . . . . . . . . . . . . . .  50

     

       100
       100
       +
            4.5.  Email/queryChanges  . . . . . . . . . . . . . . . . . . .  51

     

       101
       101
       +
            4.6.  Email/set . . . . . . . . . . . . . . . . . . . . . . . .  51

     

       102
       102
       +
            4.7.  Email/copy  . . . . . . . . . . . . . . . . . . . . . . .  53

     

       103
       103
       +
            4.8.  Email/import  . . . . . . . . . . . . . . . . . . . . . .  54

     

       104
       104
       +
            4.9.  Email/parse . . . . . . . . . . . . . . . . . . . . . . .  56

     

       105
       105
       +
            4.10. Examples  . . . . . . . . . . . . . . . . . . . . . . . .  58

     

       106
       106
       +
          5.  Search Snippets . . . . . . . . . . . . . . . . . . . . . . .  68

     

       107
       107
       +
            5.1.  SearchSnippet/get . . . . . . . . . . . . . . . . . . . .  69

     

       108
       108
       +
            5.2.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  71

     

       109
       109
       +
       

     

       110
       110
       +
       

     

       111
       111
       +
       

     

       112
       112
       +
       

     

       113
       113
       +
       

     

       114
       114
       +
       Jenkins & Newman             Standards Track                    [Page 2]

     

       115
       115
       +
       

     

       116
       116
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       117
       117
       +
       

     

       118
       118
       +
       

     

       119
       119
       +
          6.  Identities  . . . . . . . . . . . . . . . . . . . . . . . . .  72

     

       120
       120
       +
            6.1.  Identity/get  . . . . . . . . . . . . . . . . . . . . . .  73

     

       121
       121
       +
            6.2.  Identity/changes  . . . . . . . . . . . . . . . . . . . .  73

     

       122
       122
       +
            6.3.  Identity/set  . . . . . . . . . . . . . . . . . . . . . .  73

     

       123
       123
       +
            6.4.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  73

     

       124
       124
       +
          7.  Email Submission  . . . . . . . . . . . . . . . . . . . . . .  74

     

       125
       125
       +
            7.1.  EmailSubmission/get . . . . . . . . . . . . . . . . . . .  80

     

       126
       126
       +
            7.2.  EmailSubmission/changes . . . . . . . . . . . . . . . . .  80

     

       127
       127
       +
            7.3.  EmailSubmission/query . . . . . . . . . . . . . . . . . .  80

     

       128
       128
       +
            7.4.  EmailSubmission/queryChanges  . . . . . . . . . . . . . .  81

     

       129
       129
       +
            7.5.  EmailSubmission/set . . . . . . . . . . . . . . . . . . .  81

     

       130
       130
       +
              7.5.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  84

     

       131
       131
       +
          8.  Vacation Response . . . . . . . . . . . . . . . . . . . . . .  86

     

       132
       132
       +
            8.1.  VacationResponse/get  . . . . . . . . . . . . . . . . . .  87

     

       133
       133
       +
            8.2.  VacationResponse/set  . . . . . . . . . . . . . . . . . .  88

     

       134
       134
       +
          9.  Security Considerations . . . . . . . . . . . . . . . . . . .  88

     

       135
       135
       +
            9.1.  EmailBodyPart Value . . . . . . . . . . . . . . . . . . .  88

     

       136
       136
       +
            9.2.  HTML Email Display  . . . . . . . . . . . . . . . . . . .  88

     

       137
       137
       +
            9.3.  Multiple Part Display . . . . . . . . . . . . . . . . . .  91

     

       138
       138
       +
            9.4.  Email Submission  . . . . . . . . . . . . . . . . . . . .  91

     

       139
       139
       +
            9.5.  Partial Account Access  . . . . . . . . . . . . . . . . .  92

     

       140
       140
       +
            9.6.  Permission to Send from an Address  . . . . . . . . . . .  92

     

       141
       141
       +
          10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  93

     

       142
       142
       +
            10.1.  JMAP Capability Registration for "mail"  . . . . . . . .  93

     

       143
       143
       +
            10.2.  JMAP Capability Registration for "submission"  . . . . .  93

     

       144
       144
       +
            10.3.  JMAP Capability Registration for "vacationresponse"  . .  94

     

       145
       145
       +
            10.4.  IMAP and JMAP Keywords Registry  . . . . . . . . . . . .  94

     

       146
       146
       +
              10.4.1.  Registration of JMAP Keyword "$draft"  . . . . . . .  95

     

       147
       147
       +
              10.4.2.  Registration of JMAP Keyword "$seen" . . . . . . . .  96

     

       148
       148
       +
              10.4.3.  Registration of JMAP Keyword "$flagged"  . . . . . .  97

     

       149
       149
       +
              10.4.4.  Registration of JMAP Keyword "$answered" . . . . . .  98

     

       150
       150
       +
              10.4.5.  Registration of "$recent" Keyword  . . . . . . . . .  99

     

       151
       151
       +
            10.5.  IMAP Mailbox Name Attributes Registry  . . . . . . . . .  99

     

       152
       152
       +
              10.5.1.  Registration of "inbox" Role . . . . . . . . . . . .  99

     

       153
       153
       +
            10.6.  JMAP Error Codes Registry  . . . . . . . . . . . . . . . 100

     

       154
       154
       +
              10.6.1.  mailboxHasChild  . . . . . . . . . . . . . . . . . . 100

     

       155
       155
       +
              10.6.2.  mailboxHasEmail  . . . . . . . . . . . . . . . . . . 100

     

       156
       156
       +
              10.6.3.  blobNotFound . . . . . . . . . . . . . . . . . . . . 100

     

       157
       157
       +
              10.6.4.  tooManyKeywords  . . . . . . . . . . . . . . . . . . 101

     

       158
       158
       +
              10.6.5.  tooManyMailboxes . . . . . . . . . . . . . . . . . . 101

     

       159
       159
       +
              10.6.6.  invalidEmail . . . . . . . . . . . . . . . . . . . . 101

     

       160
       160
       +
              10.6.7.  tooManyRecipients  . . . . . . . . . . . . . . . . . 102

     

       161
       161
       +
              10.6.8.  noRecipients . . . . . . . . . . . . . . . . . . . . 102

     

       162
       162
       +
              10.6.9.  invalidRecipients  . . . . . . . . . . . . . . . . . 102

     

       163
       163
       +
              10.6.10. forbiddenMailFrom  . . . . . . . . . . . . . . . . . 103

     

       164
       164
       +
              10.6.11. forbiddenFrom  . . . . . . . . . . . . . . . . . . . 103

     

       165
       165
       +
              10.6.12. forbiddenToSend  . . . . . . . . . . . . . . . . . . 103

     

       166
       166
       +
       

     

       167
       167
       +
       

     

       168
       168
       +
       

     

       169
       169
       +
       

     

       170
       170
       +
       Jenkins & Newman             Standards Track                    [Page 3]

     

       171
       171
       +
       

     

       172
       172
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       173
       173
       +
       

     

       174
       174
       +
       

     

       175
       175
       +
          11. References  . . . . . . . . . . . . . . . . . . . . . . . . . 104

     

       176
       176
       +
            11.1.  Normative References . . . . . . . . . . . . . . . . . . 104

     

       177
       177
       +
            11.2.  Informative References . . . . . . . . . . . . . . . . . 107

     

       178
       178
       +
          Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . . 108

     

       179
       179
       +
       

     

       180
       180
       +
       1.  Introduction

     

       181
       181
       +
       

     

       182
       182
       +
          The JSON Meta Application Protocol (JMAP) [RFC8620] is a generic

     

       183
       183
       +
          protocol for synchronising data, such as mail, calendars, or contacts

     

       184
       184
       +
          between a client and a server.  It is optimised for mobile and web

     

       185
       185
       +
          environments and aims to provide a consistent interface to different

     

       186
       186
       +
          data types.

     

       187
       187
       +
       

     

       188
       188
       +
          This specification defines a data model for accessing a mail store

     

       189
       189
       +
          over JMAP, allowing you to query, read, organise, and submit mail for

     

       190
       190
       +
          sending.

     

       191
       191
       +
       

     

       192
       192
       +
          The data model is designed to allow a server to provide consistent

     

       193
       193
       +
          access to the same data via IMAP [RFC3501] as well as JMAP.  As in

     

       194
       194
       +
          IMAP, a message must belong to a mailbox; however, in JMAP, its id

     

       195
       195
       +
          does not change if you move it between mailboxes, and the server may

     

       196
       196
       +
          allow it to belong to multiple mailboxes simultaneously (often

     

       197
       197
       +
          exposed in a user agent as labels rather than folders).

     

       198
       198
       +
       

     

       199
       199
       +
          As in IMAP, messages may also be assigned zero or more keywords:

     

       200
       200
       +
          short arbitrary strings.  These are primarily intended to store

     

       201
       201
       +
          metadata to inform client display, such as unread status or whether a

     

       202
       202
       +
          message has been replied to.  An IANA registry allows common

     

       203
       203
       +
          semantics to be shared between clients and extended easily in the

     

       204
       204
       +
          future.

     

       205
       205
       +
       

     

       206
       206
       +
          A message and its replies are linked on the server by a common Thread

     

       207
       207
       +
          id.  Clients may fetch the list of messages with a particular Thread

     

       208
       208
       +
          id to more easily present a threaded or conversational interface.

     

       209
       209
       +
       

     

       210
       210
       +
          Permissions for message access happen on a per-mailbox basis.

     

       211
       211
       +
          Servers may give the user restricted permissions for certain

     

       212
       212
       +
          mailboxes, for example, if another user's inbox has been shared as

     

       213
       213
       +
          read-only with them.

     

       214
       214
       +
       

     

       215
       215
       +
       1.1.  Notational Conventions

     

       216
       216
       +
       

     

       217
       217
       +
          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

     

       218
       218
       +
          "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and

     

       219
       219
       +
          "OPTIONAL" in this document are to be interpreted as described in

     

       220
       220
       +
          BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all

     

       221
       221
       +
          capitals, as shown here.

     

       222
       222
       +
       

     

       223
       223
       +
       

     

       224
       224
       +
       

     

       225
       225
       +
       

     

       226
       226
       +
       Jenkins & Newman             Standards Track                    [Page 4]

     

       227
       227
       +
       

     

       228
       228
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       229
       229
       +
       

     

       230
       230
       +
       

     

       231
       231
       +
          Type signatures, examples, and property descriptions in this document

     

       232
       232
       +
          follow the conventions established in Section 1.1 of [RFC8620].  Data

     

       233
       233
       +
          types defined in the core specification are also used in this

     

       234
       234
       +
          document.

     

       235
       235
       +
       

     

       236
       236
       +
          Servers MUST support all properties specified for the new data types

     

       237
       237
       +
          defined in this document.

     

       238
       238
       +
       

     

       239
       239
       +
       1.2.  Terminology

     

       240
       240
       +
       

     

       241
       241
       +
          This document uses the same terminology as in the core JMAP

     

       242
       242
       +
          specification.

     

       243
       243
       +
       

     

       244
       244
       +
          The terms Mailbox, Thread, Email, SearchSnippet, EmailSubmission and

     

       245
       245
       +
          VacationResponse (with that specific capitalisation) are used to

     

       246
       246
       +
          refer to the data types defined in this document and instances of

     

       247
       247
       +
          those data types.

     

       248
       248
       +
       

     

       249
       249
       +
          The term message refers to a document in Internet Message Format, as

     

       250
       250
       +
          described in [RFC5322].  The Email data type represents messages in

     

       251
       251
       +
          the mail store and associated metadata.

     

       252
       252
       +
       

     

       253
       253
       +
       1.3.  Additions to the Capabilities Object

     

       254
       254
       +
       

     

       255
       255
       +
          The capabilities object is returned as part of the JMAP Session

     

       256
       256
       +
          object; see [RFC8620], Section 2.

     

       257
       257
       +
       

     

       258
       258
       +
          This document defines three additional capability URIs.

     

       259
       259
       +
       

     

       260
       260
       +
       1.3.1.  urn:ietf:params:jmap:mail

     

       261
       261
       +
       

     

       262
       262
       +
          This represents support for the Mailbox, Thread, Email, and

     

       263
       263
       +
          SearchSnippet data types and associated API methods.  The value of

     

       264
       264
       +
          this property in the JMAP session "capabilities" property is an empty

     

       265
       265
       +
          object.

     

       266
       266
       +
       

     

       267
       267
       +
          The value of this property in an account's "accountCapabilities"

     

       268
       268
       +
          property is an object that MUST contain the following information on

     

       269
       269
       +
          server capabilities and permissions for that account:

     

       270
       270
       +
       

     

       271
       271
       +
          o  maxMailboxesPerEmail: "UnsignedInt|null"

     

       272
       272
       +
       

     

       273
       273
       +
             The maximum number of Mailboxes (see Section 2) that can be can

     

       274
       274
       +
             assigned to a single Email object (see Section 4).  This MUST be

     

       275
       275
       +
             an integer >= 1, or null for no limit (or rather, the limit is

     

       276
       276
       +
             always the number of Mailboxes in the account).

     

       277
       277
       +
       

     

       278
       278
       +
       

     

       279
       279
       +
       

     

       280
       280
       +
       

     

       281
       281
       +
       

     

       282
       282
       +
       Jenkins & Newman             Standards Track                    [Page 5]

     

       283
       283
       +
       

     

       284
       284
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       285
       285
       +
       

     

       286
       286
       +
       

     

       287
       287
       +
          o  maxMailboxDepth: "UnsignedInt|null"

     

       288
       288
       +
       

     

       289
       289
       +
             The maximum depth of the Mailbox hierarchy (i.e., one more than

     

       290
       290
       +
             the maximum number of ancestors a Mailbox may have), or null for

     

       291
       291
       +
             no limit.

     

       292
       292
       +
       

     

       293
       293
       +
          o  maxSizeMailboxName: "UnsignedInt"

     

       294
       294
       +
       

     

       295
       295
       +
             The maximum length, in (UTF-8) octets, allowed for the name of a

     

       296
       296
       +
             Mailbox.  This MUST be at least 100, although it is recommended

     

       297
       297
       +
             servers allow more.

     

       298
       298
       +
       

     

       299
       299
       +
          o  maxSizeAttachmentsPerEmail: "UnsignedInt"

     

       300
       300
       +
       

     

       301
       301
       +
             The maximum total size of attachments, in octets, allowed for a

     

       302
       302
       +
             single Email object.  A server MAY still reject the import or

     

       303
       303
       +
             creation of an Email with a lower attachment size total (for

     

       304
       304
       +
             example, if the body includes several megabytes of text, causing

     

       305
       305
       +
             the size of the encoded MIME structure to be over some server-

     

       306
       306
       +
             defined limit).

     

       307
       307
       +
       

     

       308
       308
       +
             Note that this limit is for the sum of unencoded attachment sizes.

     

       309
       309
       +
             Users are generally not knowledgeable about encoding overhead,

     

       310
       310
       +
             etc., nor should they need to be, so marketing and help materials

     

       311
       311
       +
             normally tell them the "max size attachments".  This is the

     

       312
       312
       +
             unencoded size they see on their hard drive, so this capability

     

       313
       313
       +
             matches that and allows the client to consistently enforce what

     

       314
       314
       +
             the user understands as the limit.

     

       315
       315
       +
       

     

       316
       316
       +
             The server may separately have a limit for the total size of the

     

       317
       317
       +
             message [RFC5322], created by combining the attachments (often

     

       318
       318
       +
             base64 encoded) with the message headers and bodies.  For example,

     

       319
       319
       +
             suppose the server advertises "maxSizeAttachmentsPerEmail:

     

       320
       320
       +
             50000000" (50 MB).  The enforced server limit may be for a message

     

       321
       321
       +
             size of 70000000 octets.  Even with base64 encoding and a 2 MB

     

       322
       322
       +
             HTML body, 50 MB attachments would fit under this limit.

     

       323
       323
       +
       

     

       324
       324
       +
          o  emailQuerySortOptions: "String[]"

     

       325
       325
       +
       

     

       326
       326
       +
             A list of all the values the server supports for the "property"

     

       327
       327
       +
             field of the Comparator object in an "Email/query" sort (see

     

       328
       328
       +
             Section 4.4.2).  This MAY include properties the client does not

     

       329
       329
       +
             recognise (for example, custom properties specified in a vendor

     

       330
       330
       +
             extension).  Clients MUST ignore any unknown properties in the

     

       331
       331
       +
             list.

     

       332
       332
       +
       

     

       333
       333
       +
       

     

       334
       334
       +
       

     

       335
       335
       +
       

     

       336
       336
       +
       

     

       337
       337
       +
       

     

       338
       338
       +
       Jenkins & Newman             Standards Track                    [Page 6]

     

       339
       339
       +
       

     

       340
       340
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       341
       341
       +
       

     

       342
       342
       +
       

     

       343
       343
       +
          o  mayCreateTopLevelMailbox: "Boolean"

     

       344
       344
       +
       

     

       345
       345
       +
             If true, the user may create a Mailbox (see Section 2) in this

     

       346
       346
       +
             account with a null parentId.  (Permission for creating a child of

     

       347
       347
       +
             an existing Mailbox is given by the "myRights" property on that

     

       348
       348
       +
             Mailbox.)

     

       349
       349
       +
       

     

       350
       350
       +
       1.3.2.  urn:ietf:params:jmap:submission

     

       351
       351
       +
       

     

       352
       352
       +
          This represents support for the Identity and EmailSubmission data

     

       353
       353
       +
          types and associated API methods.  The value of this property in the

     

       354
       354
       +
          JMAP session "capabilities" property is an empty object.

     

       355
       355
       +
       

     

       356
       356
       +
          The value of this property in an account's "accountCapabilities"

     

       357
       357
       +
          property is an object that MUST contain the following information on

     

       358
       358
       +
          server capabilities and permissions for that account:

     

       359
       359
       +
       

     

       360
       360
       +
          o  maxDelayedSend: "UnsignedInt"

     

       361
       361
       +
       

     

       362
       362
       +
             The number in seconds of the maximum delay the server supports in

     

       363
       363
       +
             sending (see the EmailSubmission object description).  This is 0

     

       364
       364
       +
             if the server does not support delayed send.

     

       365
       365
       +
       

     

       366
       366
       +
          o  submissionExtensions: "String[String[]]"

     

       367
       367
       +
       

     

       368
       368
       +
             The set of SMTP submission extensions supported by the server,

     

       369
       369
       +
             which the client may use when creating an EmailSubmission object

     

       370
       370
       +
             (see Section 7).  Each key in the object is the "ehlo-name", and

     

       371
       371
       +
             the value is a list of "ehlo-args".

     

       372
       372
       +
       

     

       373
       373
       +
             A JMAP implementation that talks to a submission server [RFC6409]

     

       374
       374
       +
             SHOULD have a configuration setting that allows an administrator

     

       375
       375
       +
             to modify the set of submission EHLO capabilities it may expose on

     

       376
       376
       +
             this property.  This allows a JMAP server to easily add access to

     

       377
       377
       +
             a new submission extension without code changes.  By default, the

     

       378
       378
       +
             JMAP server should hide EHLO capabilities that have to do with the

     

       379
       379
       +
             transport mechanism and thus are only relevant to the JMAP server

     

       380
       380
       +
             (for example, PIPELINING, CHUNKING, or STARTTLS).

     

       381
       381
       +
       

     

       382
       382
       +
             Examples of Submission extensions to include:

     

       383
       383
       +
       

     

       384
       384
       +
             *  FUTURERELEASE [RFC4865]

     

       385
       385
       +
       

     

       386
       386
       +
             *  SIZE [RFC1870]

     

       387
       387
       +
       

     

       388
       388
       +
             *  DSN [RFC3461]

     

       389
       389
       +
       

     

       390
       390
       +
             *  DELIVERYBY [RFC2852]

     

       391
       391
       +
       

     

       392
       392
       +
       

     

       393
       393
       +
       

     

       394
       394
       +
       Jenkins & Newman             Standards Track                    [Page 7]

     

       395
       395
       +
       

     

       396
       396
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       397
       397
       +
       

     

       398
       398
       +
       

     

       399
       399
       +
             *  MT-PRIORITY [RFC6710]

     

       400
       400
       +
       

     

       401
       401
       +
             A JMAP server MAY advertise an extension and implement the

     

       402
       402
       +
             semantics of that extension locally on the JMAP server even if a

     

       403
       403
       +
             submission server used by JMAP doesn't implement it.

     

       404
       404
       +
       

     

       405
       405
       +
             The full IANA registry of submission extensions can be found at

     

       406
       406
       +
             <https://www.iana.org/assignments/mail-parameters>.

     

       407
       407
       +
       

     

       408
       408
       +
       1.3.3.  urn:ietf:params:jmap:vacationresponse

     

       409
       409
       +
       

     

       410
       410
       +
          This represents support for the VacationResponse data type and

     

       411
       411
       +
          associated API methods.  The value of this property is an empty

     

       412
       412
       +
          object in both the JMAP session "capabilities" property and an

     

       413
       413
       +
          account's "accountCapabilities" property.

     

       414
       414
       +
       

     

       415
       415
       +
       1.4.  Data Type Support in Different Accounts

     

       416
       416
       +
       

     

       417
       417
       +
          The server MUST include the appropriate capability strings as keys in

     

       418
       418
       +
          the "accountCapabilities" property of any account with which the user

     

       419
       419
       +
          may use the data types represented by that URI.  Supported data types

     

       420
       420
       +
          may differ between accounts the user has access to.  For example, in

     

       421
       421
       +
          the user's personal account, they may have access to all three sets

     

       422
       422
       +
          of data, but in a shared account, they may only have data for

     

       423
       423
       +
          "urn:ietf:params:jmap:mail".  This means they can access

     

       424
       424
       +
          Mailbox/Thread/Email data in the shared account but are not allowed

     

       425
       425
       +
          to send as that account (and so do not have access to Identity/

     

       426
       426
       +
          EmailSubmission objects) or view/set its VacationResponse.

     

       427
       427
       +
       

     

       428
       428
       +
       1.5.  Push

     

       429
       429
       +
       

     

       430
       430
       +
          Servers MUST support the JMAP push mechanisms, as specified in

     

       431
       431
       +
          [RFC8620], Section 7, to receive notifications when the state changes

     

       432
       432
       +
          for any of the types defined in this specification.

     

       433
       433
       +
       

     

       434
       434
       +
          In addition, servers that implement the "urn:ietf:params:jmap:mail"

     

       435
       435
       +
          capability MUST support pushing state changes for a type called

     

       436
       436
       +
          "EmailDelivery".  There are no methods to act on this type; it only

     

       437
       437
       +
          exists as part of the push mechanism.  The state string for this MUST

     

       438
       438
       +
          change whenever a new Email is added to the store, but it SHOULD NOT

     

       439
       439
       +
          change upon any other change to the Email objects, for example, if

     

       440
       440
       +
          one is marked as read or deleted.

     

       441
       441
       +
       

     

       442
       442
       +
          Clients in battery-constrained environments may wish to delay

     

       443
       443
       +
          fetching changes initiated by the user but fetch new Emails

     

       444
       444
       +
          immediately so they can notify the user.  To do this, they can

     

       445
       445
       +
          register for pushes for the EmailDelivery type rather than the Email

     

       446
       446
       +
          type (as defined in Section 4).

     

       447
       447
       +
       

     

       448
       448
       +
       

     

       449
       449
       +
       

     

       450
       450
       +
       Jenkins & Newman             Standards Track                    [Page 8]

     

       451
       451
       +
       

     

       452
       452
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       453
       453
       +
       

     

       454
       454
       +
       

     

       455
       455
       +
       1.5.1.  Example

     

       456
       456
       +
       

     

       457
       457
       +
          The client has registered for push notifications (see [RFC8620]) just

     

       458
       458
       +
          for the EmailDelivery type.  The user marks an Email as read on

     

       459
       459
       +
          another device, causing the state string for the Email type to

     

       460
       460
       +
          change; however, as nothing new was added to the store, the

     

       461
       461
       +
          EmailDelivery state does not change and nothing is pushed to the

     

       462
       462
       +
          client.  A new message arrives in the user's inbox, again causing the

     

       463
       463
       +
          Email state to change.  This time, the EmailDelivery state also

     

       464
       464
       +
          changes, and a StateChange object is pushed to the client with the

     

       465
       465
       +
          new state string.  The client may then resync to fetch the new Email

     

       466
       466
       +
          immediately.

     

       467
       467
       +
       

     

       468
       468
       +
       1.6.  Ids

     

       469
       469
       +
       

     

       470
       470
       +
          If a JMAP Mail server also provides an IMAP interface to the data and

     

       471
       471
       +
          supports IMAP Extension for Object Identifiers [RFC8474], the ids

     

       472
       472
       +
          SHOULD be the same for Mailbox, Thread, and Email objects in JMAP.

     

       473
       473
       +
       

     

       474
       474
       +
       2.  Mailboxes

     

       475
       475
       +
       

     

       476
       476
       +
          A Mailbox represents a named set of Email objects.  This is the

     

       477
       477
       +
          primary mechanism for organising messages within an account.  It is

     

       478
       478
       +
          analogous to a folder or a label in other systems.  A Mailbox may

     

       479
       479
       +
          perform a certain role in the system; see below for more details.

     

       480
       480
       +
       

     

       481
       481
       +
          For compatibility with IMAP, an Email MUST belong to one or more

     

       482
       482
       +
          Mailboxes.  The Email id does not change if the Email changes

     

       483
       483
       +
          Mailboxes.

     

       484
       484
       +
       

     

       485
       485
       +
          A *Mailbox* object has the following properties:

     

       486
       486
       +
       

     

       487
       487
       +
          o  id: "Id" (immutable; server-set)

     

       488
       488
       +
       

     

       489
       489
       +
             The id of the Mailbox.

     

       490
       490
       +
       

     

       491
       491
       +
          o  name: "String"

     

       492
       492
       +
       

     

       493
       493
       +
             User-visible name for the Mailbox, e.g., "Inbox".  This MUST be a

     

       494
       494
       +
             Net-Unicode string [RFC5198] of at least 1 character in length,

     

       495
       495
       +
             subject to the maximum size given in the capability object.  There

     

       496
       496
       +
             MUST NOT be two sibling Mailboxes with both the same parent and

     

       497
       497
       +
             the same name.  Servers MAY reject names that violate server

     

       498
       498
       +
             policy (e.g., names containing a slash (/) or control characters).

     

       499
       499
       +
       

     

       500
       500
       +
       

     

       501
       501
       +
       

     

       502
       502
       +
       

     

       503
       503
       +
       

     

       504
       504
       +
       

     

       505
       505
       +
       

     

       506
       506
       +
       Jenkins & Newman             Standards Track                    [Page 9]

     

       507
       507
       +
       

     

       508
       508
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       509
       509
       +
       

     

       510
       510
       +
       

     

       511
       511
       +
          o  parentId: "Id|null" (default: null)

     

       512
       512
       +
       

     

       513
       513
       +
             The Mailbox id for the parent of this Mailbox, or null if this

     

       514
       514
       +
             Mailbox is at the top level.  Mailboxes form acyclic graphs

     

       515
       515
       +
             (forests) directed by the child-to-parent relationship.  There

     

       516
       516
       +
             MUST NOT be a loop.

     

       517
       517
       +
       

     

       518
       518
       +
          o  role: "String|null" (default: null)

     

       519
       519
       +
       

     

       520
       520
       +
             Identifies Mailboxes that have a particular common purpose (e.g.,

     

       521
       521
       +
             the "inbox"), regardless of the "name" property (which may be

     

       522
       522
       +
             localised).

     

       523
       523
       +
       

     

       524
       524
       +
             This value is shared with IMAP (exposed in IMAP via the SPECIAL-

     

       525
       525
       +
             USE extension [RFC6154]).  However, unlike in IMAP, a Mailbox MUST

     

       526
       526
       +
             only have a single role, and there MUST NOT be two Mailboxes in

     

       527
       527
       +
             the same account with the same role.  Servers providing IMAP

     

       528
       528
       +
             access to the same data are encouraged to enforce these extra

     

       529
       529
       +
             restrictions in IMAP as well.  Otherwise, modifying the IMAP

     

       530
       530
       +
             attributes to ensure compliance when exposing the data over JMAP

     

       531
       531
       +
             is implementation dependent.

     

       532
       532
       +
       

     

       533
       533
       +
             The value MUST be one of the Mailbox attribute names listed in the

     

       534
       534
       +
             IANA "IMAP Mailbox Name Attributes" registry at

     

       535
       535
       +
             <https://www.iana.org/assignments/imap-mailbox-name-attributes/>,

     

       536
       536
       +
             as established in [RFC8457], converted to lowercase.  New roles

     

       537
       537
       +
             may be established here in the future.

     

       538
       538
       +
       

     

       539
       539
       +
             An account is not required to have Mailboxes with any particular

     

       540
       540
       +
             roles.

     

       541
       541
       +
       

     

       542
       542
       +
          o  sortOrder: "UnsignedInt" (default: 0)

     

       543
       543
       +
       

     

       544
       544
       +
             Defines the sort order of Mailboxes when presented in the client's

     

       545
       545
       +
             UI, so it is consistent between devices.  The number MUST be an

     

       546
       546
       +
             integer in the range 0 <= sortOrder < 2^31.

     

       547
       547
       +
       

     

       548
       548
       +
             A Mailbox with a lower order should be displayed before a Mailbox

     

       549
       549
       +
             with a higher order (that has the same parent) in any Mailbox

     

       550
       550
       +
             listing in the client's UI.  Mailboxes with equal order SHOULD be

     

       551
       551
       +
             sorted in alphabetical order by name.  The sorting should take

     

       552
       552
       +
             into account locale-specific character order convention.

     

       553
       553
       +
       

     

       554
       554
       +
          o  totalEmails: "UnsignedInt" (server-set)

     

       555
       555
       +
       

     

       556
       556
       +
             The number of Emails in this Mailbox.

     

       557
       557
       +
       

     

       558
       558
       +
       

     

       559
       559
       +
       

     

       560
       560
       +
       

     

       561
       561
       +
       

     

       562
       562
       +
       Jenkins & Newman             Standards Track                   [Page 10]

     

       563
       563
       +
       

     

       564
       564
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       565
       565
       +
       

     

       566
       566
       +
       

     

       567
       567
       +
          o  unreadEmails: "UnsignedInt" (server-set)

     

       568
       568
       +
       

     

       569
       569
       +
             The number of Emails in this Mailbox that have neither the "$seen"

     

       570
       570
       +
             keyword nor the "$draft" keyword.

     

       571
       571
       +
       

     

       572
       572
       +
          o  totalThreads: "UnsignedInt" (server-set)

     

       573
       573
       +
       

     

       574
       574
       +
             The number of Threads where at least one Email in the Thread is in

     

       575
       575
       +
             this Mailbox.

     

       576
       576
       +
       

     

       577
       577
       +
          o  unreadThreads: "UnsignedInt" (server-set)

     

       578
       578
       +
       

     

       579
       579
       +
             An indication of the number of "unread" Threads in the Mailbox.

     

       580
       580
       +
       

     

       581
       581
       +
             For compatibility with existing implementations, the way "unread

     

       582
       582
       +
             Threads" is determined is not mandated in this document.  The

     

       583
       583
       +
             simplest solution to implement is simply the number of Threads

     

       584
       584
       +
             where at least one Email in the Thread is both in this Mailbox and

     

       585
       585
       +
             has neither the "$seen" nor "$draft" keywords.

     

       586
       586
       +
       

     

       587
       587
       +
             However, a quality implementation will return the number of unread

     

       588
       588
       +
             items the user would see if they opened that Mailbox.  A Thread is

     

       589
       589
       +
             shown as unread if it contains any unread Emails that will be

     

       590
       590
       +
             displayed when the Thread is opened.  Therefore, "unreadThreads"

     

       591
       591
       +
             should be the number of Threads where at least one Email in the

     

       592
       592
       +
             Thread has neither the "$seen" nor the "$draft" keyword AND at

     

       593
       593
       +
             least one Email in the Thread is in this Mailbox.  Note that the

     

       594
       594
       +
             unread Email does not need to be the one in this Mailbox.  In

     

       595
       595
       +
             addition, the trash Mailbox (that is, a Mailbox whose "role" is

     

       596
       596
       +
             "trash") requires special treatment:

     

       597
       597
       +
       

     

       598
       598
       +
             1.  Emails that are *only* in the trash (and no other Mailbox) are

     

       599
       599
       +
                 ignored when calculating the "unreadThreads" count of other

     

       600
       600
       +
                 Mailboxes.

     

       601
       601
       +
       

     

       602
       602
       +
             2.  Emails that are *not* in the trash are ignored when

     

       603
       603
       +
                 calculating the "unreadThreads" count for the trash Mailbox.

     

       604
       604
       +
       

     

       605
       605
       +
             The result of this is that Emails in the trash are treated as

     

       606
       606
       +
             though they are in a separate Thread for the purposes of unread

     

       607
       607
       +
             counts.  It is expected that clients will hide Emails in the trash

     

       608
       608
       +
             when viewing a Thread in another Mailbox, and vice versa.  This

     

       609
       609
       +
             allows you to delete a single Email to the trash out of a Thread.

     

       610
       610
       +
       

     

       611
       611
       +
             For example, suppose you have an account where the entire contents

     

       612
       612
       +
             is a single Thread with 2 Emails: an unread Email in the trash and

     

       613
       613
       +
             a read Email in the inbox.  The "unreadThreads" count would be 1

     

       614
       614
       +
             for the trash and 0 for the inbox.

     

       615
       615
       +
       

     

       616
       616
       +
       

     

       617
       617
       +
       

     

       618
       618
       +
       Jenkins & Newman             Standards Track                   [Page 11]

     

       619
       619
       +
       

     

       620
       620
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       621
       621
       +
       

     

       622
       622
       +
       

     

       623
       623
       +
          o  myRights: "MailboxRights" (server-set)

     

       624
       624
       +
       

     

       625
       625
       +
             The set of rights (Access Control Lists (ACLs)) the user has in

     

       626
       626
       +
             relation to this Mailbox.  These are backwards compatible with

     

       627
       627
       +
             IMAP ACLs, as defined in [RFC4314].  A *MailboxRights* object has

     

       628
       628
       +
             the following properties:

     

       629
       629
       +
       

     

       630
       630
       +
             *  mayReadItems: "Boolean"

     

       631
       631
       +
       

     

       632
       632
       +
                If true, the user may use this Mailbox as part of a filter in

     

       633
       633
       +
                an "Email/query" call, and the Mailbox may be included in the

     

       634
       634
       +
                "mailboxIds" property of Email objects.  Email objects may be

     

       635
       635
       +
                fetched if they are in *at least one* Mailbox with this

     

       636
       636
       +
                permission.  If a sub-Mailbox is shared but not the parent

     

       637
       637
       +
                Mailbox, this may be false.  Corresponds to IMAP ACLs "lr" (if

     

       638
       638
       +
                mapping from IMAP, both are required for this to be true).

     

       639
       639
       +
       

     

       640
       640
       +
             *  mayAddItems: "Boolean"

     

       641
       641
       +
       

     

       642
       642
       +
                The user may add mail to this Mailbox (by either creating a new

     

       643
       643
       +
                Email or moving an existing one).  Corresponds to IMAP ACL "i".

     

       644
       644
       +
       

     

       645
       645
       +
             *  mayRemoveItems: "Boolean"

     

       646
       646
       +
       

     

       647
       647
       +
                The user may remove mail from this Mailbox (by either changing

     

       648
       648
       +
                the Mailboxes of an Email or destroying the Email).

     

       649
       649
       +
                Corresponds to IMAP ACLs "te" (if mapping from IMAP, both are

     

       650
       650
       +
                required for this to be true).

     

       651
       651
       +
       

     

       652
       652
       +
             *  maySetSeen: "Boolean"

     

       653
       653
       +
       

     

       654
       654
       +
                The user may add or remove the "$seen" keyword to/from an

     

       655
       655
       +
                Email.  If an Email belongs to multiple Mailboxes, the user may

     

       656
       656
       +
                only modify "$seen" if they have this permission for *all* of

     

       657
       657
       +
                the Mailboxes.  Corresponds to IMAP ACL "s".

     

       658
       658
       +
       

     

       659
       659
       +
             *  maySetKeywords: "Boolean"

     

       660
       660
       +
       

     

       661
       661
       +
                The user may add or remove any keyword other than "$seen" to/

     

       662
       662
       +
                from an Email.  If an Email belongs to multiple Mailboxes, the

     

       663
       663
       +
                user may only modify keywords if they have this permission for

     

       664
       664
       +
                *all* of the Mailboxes.  Corresponds to IMAP ACL "w".

     

       665
       665
       +
       

     

       666
       666
       +
             *  mayCreateChild: "Boolean"

     

       667
       667
       +
       

     

       668
       668
       +
                The user may create a Mailbox with this Mailbox as its parent.

     

       669
       669
       +
                Corresponds to IMAP ACL "k".

     

       670
       670
       +
       

     

       671
       671
       +
       

     

       672
       672
       +
       

     

       673
       673
       +
       

     

       674
       674
       +
       Jenkins & Newman             Standards Track                   [Page 12]

     

       675
       675
       +
       

     

       676
       676
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       677
       677
       +
       

     

       678
       678
       +
       

     

       679
       679
       +
             *  mayRename: "Boolean"

     

       680
       680
       +
       

     

       681
       681
       +
                The user may rename the Mailbox or make it a child of another

     

       682
       682
       +
                Mailbox.  Corresponds to IMAP ACL "x" (although this covers

     

       683
       683
       +
                both rename and delete permissions).

     

       684
       684
       +
       

     

       685
       685
       +
             *  mayDelete: "Boolean"

     

       686
       686
       +
       

     

       687
       687
       +
                The user may delete the Mailbox itself.  Corresponds to IMAP

     

       688
       688
       +
                ACL "x" (although this covers both rename and delete

     

       689
       689
       +
                permissions).

     

       690
       690
       +
       

     

       691
       691
       +
             *  maySubmit: "Boolean"

     

       692
       692
       +
       

     

       693
       693
       +
                Messages may be submitted directly to this Mailbox.

     

       694
       694
       +
                Corresponds to IMAP ACL "p".

     

       695
       695
       +
       

     

       696
       696
       +
          o  isSubscribed: "Boolean"

     

       697
       697
       +
       

     

       698
       698
       +
             Has the user indicated they wish to see this Mailbox in their

     

       699
       699
       +
             client?  This SHOULD default to false for Mailboxes in shared

     

       700
       700
       +
             accounts the user has access to and true for any new Mailboxes

     

       701
       701
       +
             created by the user themself.  This MUST be stored separately per

     

       702
       702
       +
             user where multiple users have access to a shared Mailbox.

     

       703
       703
       +
       

     

       704
       704
       +
             A user may have permission to access a large number of shared

     

       705
       705
       +
             accounts, or a shared account with a very large set of Mailboxes,

     

       706
       706
       +
             but only be interested in the contents of a few of these.  Clients

     

       707
       707
       +
             may choose to only display Mailboxes where the "isSubscribed"

     

       708
       708
       +
             property is set to true, and offer a separate UI to allow the user

     

       709
       709
       +
             to see and subscribe/unsubscribe from the full set of Mailboxes.

     

       710
       710
       +
             However, clients MAY choose to ignore this property, either

     

       711
       711
       +
             entirely for ease of implementation or just for an account where

     

       712
       712
       +
             "isPersonal" is true (indicating it is the user's own rather than

     

       713
       713
       +
             a shared account).

     

       714
       714
       +
       

     

       715
       715
       +
             This property corresponds to IMAP [RFC3501] mailbox subscriptions.

     

       716
       716
       +
       

     

       717
       717
       +
          For IMAP compatibility, an Email in both the trash and another

     

       718
       718
       +
          Mailbox SHOULD be treated by the client as existing in both places

     

       719
       719
       +
          (i.e., when emptying the trash, the client should just remove it from

     

       720
       720
       +
          the trash Mailbox and leave it in the other Mailbox).

     

       721
       721
       +
       

     

       722
       722
       +
          The following JMAP methods are supported.

     

       723
       723
       +
       

     

       724
       724
       +
       

     

       725
       725
       +
       

     

       726
       726
       +
       

     

       727
       727
       +
       

     

       728
       728
       +
       

     

       729
       729
       +
       

     

       730
       730
       +
       Jenkins & Newman             Standards Track                   [Page 13]

     

       731
       731
       +
       

     

       732
       732
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       733
       733
       +
       

     

       734
       734
       +
       

     

       735
       735
       +
       2.1.  Mailbox/get

     

       736
       736
       +
       

     

       737
       737
       +
          This is a standard "/get" method as described in [RFC8620],

     

       738
       738
       +
          Section 5.1.  The "ids" argument may be "null" to fetch all at once.

     

       739
       739
       +
       

     

       740
       740
       +
       2.2.  Mailbox/changes

     

       741
       741
       +
       

     

       742
       742
       +
          This is a standard "/changes" method as described in [RFC8620],

     

       743
       743
       +
          Section 5.2 but with one extra argument to the response:

     

       744
       744
       +
       

     

       745
       745
       +
          o  updatedProperties: "String[]|null"

     

       746
       746
       +
       

     

       747
       747
       +
             If only the "totalEmails", "unreadEmails", "totalThreads", and/or

     

       748
       748
       +
             "unreadThreads" Mailbox properties have changed since the old

     

       749
       749
       +
             state, this will be the list of properties that may have changed.

     

       750
       750
       +
             If the server is unable to tell if only counts have changed, it

     

       751
       751
       +
             MUST just be null.

     

       752
       752
       +
       

     

       753
       753
       +
          Since counts frequently change but other properties are generally

     

       754
       754
       +
          only changed rarely, the server can help the client optimise data

     

       755
       755
       +
          transfer by keeping track of changes to Email/Thread counts separate

     

       756
       756
       +
          from other state changes.  The "updatedProperties" array may be used

     

       757
       757
       +
          directly via a back-reference in a subsequent "Mailbox/get" call in

     

       758
       758
       +
          the same request, so only these properties are returned if nothing

     

       759
       759
       +
          else has changed.

     

       760
       760
       +
       

     

       761
       761
       +
       2.3.  Mailbox/query

     

       762
       762
       +
       

     

       763
       763
       +
          This is a standard "/query" method as described in [RFC8620],

     

       764
       764
       +
          Section 5.5 but with the following additional request argument:

     

       765
       765
       +
       

     

       766
       766
       +
          o  sortAsTree: "Boolean" (default: false)

     

       767
       767
       +
       

     

       768
       768
       +
             If true, when sorting the query results and comparing Mailboxes A

     

       769
       769
       +
             and B:

     

       770
       770
       +
       

     

       771
       771
       +
             *  If A is an ancestor of B, it always comes first regardless of

     

       772
       772
       +
                the sort comparators.  Similarly, if A is descendant of B, then

     

       773
       773
       +
                B always comes first.

     

       774
       774
       +
       

     

       775
       775
       +
             *  Otherwise, if A and B do not share a "parentId", find the

     

       776
       776
       +
                nearest ancestors of each that do have the same "parentId" and

     

       777
       777
       +
                compare the sort properties on those Mailboxes instead.

     

       778
       778
       +
       

     

       779
       779
       +
             The result of this is that the Mailboxes are sorted as a tree

     

       780
       780
       +
             according to the parentId properties, with each set of children

     

       781
       781
       +
             with a common parent sorted according to the standard sort

     

       782
       782
       +
             comparators.

     

       783
       783
       +
       

     

       784
       784
       +
       

     

       785
       785
       +
       

     

       786
       786
       +
       Jenkins & Newman             Standards Track                   [Page 14]

     

       787
       787
       +
       

     

       788
       788
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       789
       789
       +
       

     

       790
       790
       +
       

     

       791
       791
       +
          o  filterAsTree: "Boolean" (default: false)

     

       792
       792
       +
       

     

       793
       793
       +
             If true, a Mailbox is only included in the query if all its

     

       794
       794
       +
             ancestors are also included in the query according to the filter.

     

       795
       795
       +
       

     

       796
       796
       +
          A *FilterCondition* object has the following properties, any of which

     

       797
       797
       +
          may be omitted:

     

       798
       798
       +
       

     

       799
       799
       +
          o  parentId: "Id|null"

     

       800
       800
       +
       

     

       801
       801
       +
             The Mailbox "parentId" property must match the given value

     

       802
       802
       +
             exactly.

     

       803
       803
       +
       

     

       804
       804
       +
          o  name: "String"

     

       805
       805
       +
       

     

       806
       806
       +
             The Mailbox "name" property contains the given string.

     

       807
       807
       +
       

     

       808
       808
       +
          o  role: "String|null"

     

       809
       809
       +
       

     

       810
       810
       +
             The Mailbox "role" property must match the given value exactly.

     

       811
       811
       +
       

     

       812
       812
       +
          o  hasAnyRole: "Boolean"

     

       813
       813
       +
       

     

       814
       814
       +
             If true, a Mailbox matches if it has any non-null value for its

     

       815
       815
       +
             "role" property.

     

       816
       816
       +
       

     

       817
       817
       +
          o  isSubscribed: "Boolean"

     

       818
       818
       +
       

     

       819
       819
       +
             The "isSubscribed" property of the Mailbox must be identical to

     

       820
       820
       +
             the value given to match the condition.

     

       821
       821
       +
       

     

       822
       822
       +
          A Mailbox object matches the FilterCondition if and only if all of

     

       823
       823
       +
          the given conditions match.  If zero properties are specified, it is

     

       824
       824
       +
          automatically true for all objects.

     

       825
       825
       +
       

     

       826
       826
       +
          The following Mailbox properties MUST be supported for sorting:

     

       827
       827
       +
       

     

       828
       828
       +
          o  "sortOrder"

     

       829
       829
       +
       

     

       830
       830
       +
          o  "name"

     

       831
       831
       +
       

     

       832
       832
       +
       2.4.  Mailbox/queryChanges

     

       833
       833
       +
       

     

       834
       834
       +
          This is a standard "/queryChanges" method as described in [RFC8620],

     

       835
       835
       +
          Section 5.6.

     

       836
       836
       +
       

     

       837
       837
       +
       

     

       838
       838
       +
       

     

       839
       839
       +
       

     

       840
       840
       +
       

     

       841
       841
       +
       

     

       842
       842
       +
       Jenkins & Newman             Standards Track                   [Page 15]

     

       843
       843
       +
       

     

       844
       844
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       845
       845
       +
       

     

       846
       846
       +
       

     

       847
       847
       +
       2.5.  Mailbox/set

     

       848
       848
       +
       

     

       849
       849
       +
          This is a standard "/set" method as described in [RFC8620],

     

       850
       850
       +
          Section 5.3 but with the following additional request argument:

     

       851
       851
       +
       

     

       852
       852
       +
          o  onDestroyRemoveEmails: "Boolean" (default: false)

     

       853
       853
       +
       

     

       854
       854
       +
             If false, any attempt to destroy a Mailbox that still has Emails

     

       855
       855
       +
             in it will be rejected with a "mailboxHasEmail" SetError.  If

     

       856
       856
       +
             true, any Emails that were in the Mailbox will be removed from it,

     

       857
       857
       +
             and if in no other Mailboxes, they will be destroyed when the

     

       858
       858
       +
             Mailbox is destroyed.

     

       859
       859
       +
       

     

       860
       860
       +
          The following extra SetError types are defined:

     

       861
       861
       +
       

     

       862
       862
       +
          For "destroy":

     

       863
       863
       +
       

     

       864
       864
       +
          o  "mailboxHasChild": The Mailbox still has at least one child

     

       865
       865
       +
             Mailbox.  The client MUST remove these before it can delete the

     

       866
       866
       +
             parent Mailbox.

     

       867
       867
       +
       

     

       868
       868
       +
          o  "mailboxHasEmail": The Mailbox has at least one Email assigned to

     

       869
       869
       +
             it, and the "onDestroyRemoveEmails" argument was false.

     

       870
       870
       +
       

     

       871
       871
       +
       

     

       872
       872
       +
       

     

       873
       873
       +
       

     

       874
       874
       +
       

     

       875
       875
       +
       

     

       876
       876
       +
       

     

       877
       877
       +
       

     

       878
       878
       +
       

     

       879
       879
       +
       

     

       880
       880
       +
       

     

       881
       881
       +
       

     

       882
       882
       +
       

     

       883
       883
       +
       

     

       884
       884
       +
       

     

       885
       885
       +
       

     

       886
       886
       +
       

     

       887
       887
       +
       

     

       888
       888
       +
       

     

       889
       889
       +
       

     

       890
       890
       +
       

     

       891
       891
       +
       

     

       892
       892
       +
       

     

       893
       893
       +
       

     

       894
       894
       +
       

     

       895
       895
       +
       

     

       896
       896
       +
       

     

       897
       897
       +
       

     

       898
       898
       +
       Jenkins & Newman             Standards Track                   [Page 16]

     

       899
       899
       +
       

     

       900
       900
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       901
       901
       +
       

     

       902
       902
       +
       

     

       903
       903
       +
       2.6.  Example

     

       904
       904
       +
       

     

       905
       905
       +
          Fetching all Mailboxes in an account:

     

       906
       906
       +
       

     

       907
       907
       +
                               [[ "Mailbox/get", {

     

       908
       908
       +
                                 "accountId": "u33084183",

     

       909
       909
       +
                                 "ids": null

     

       910
       910
       +
                               }, "0" ]]

     

       911
       911
       +
       

     

       912
       912
       +
          And the response:

     

       913
       913
       +
       

     

       914
       914
       +
                             [[ "Mailbox/get", {

     

       915
       915
       +
                               "accountId": "u33084183",

     

       916
       916
       +
                               "state": "78540",

     

       917
       917
       +
                               "list": [{

     

       918
       918
       +
                                 "id": "MB23cfa8094c0f41e6",

     

       919
       919
       +
                                 "name": "Inbox",

     

       920
       920
       +
                                 "parentId": null,

     

       921
       921
       +
                                 "role": "inbox",

     

       922
       922
       +
                                 "sortOrder": 10,

     

       923
       923
       +
                                 "totalEmails": 16307,

     

       924
       924
       +
                                 "unreadEmails": 13905,

     

       925
       925
       +
                                 "totalThreads": 5833,

     

       926
       926
       +
                                 "unreadThreads": 5128,

     

       927
       927
       +
                                 "myRights": {

     

       928
       928
       +
                                   "mayAddItems": true,

     

       929
       929
       +
                                   "mayRename": false,

     

       930
       930
       +
                                   "maySubmit": true,

     

       931
       931
       +
                                   "mayDelete": false,

     

       932
       932
       +
                                   "maySetKeywords": true,

     

       933
       933
       +
                                   "mayRemoveItems": true,

     

       934
       934
       +
                                   "mayCreateChild": true,

     

       935
       935
       +
                                   "maySetSeen": true,

     

       936
       936
       +
                                   "mayReadItems": true

     

       937
       937
       +
                                 },

     

       938
       938
       +
                                 "isSubscribed": true

     

       939
       939
       +
                               }, {

     

       940
       940
       +
                                 "id": "MB674cc24095db49ce",

     

       941
       941
       +
                                 "name": "Important mail",

     

       942
       942
       +
                                 ...

     

       943
       943
       +
                               }, ... ],

     

       944
       944
       +
                               "notFound": []

     

       945
       945
       +
                             }, "0" ]]

     

       946
       946
       +
       

     

       947
       947
       +
       

     

       948
       948
       +
       

     

       949
       949
       +
       

     

       950
       950
       +
       

     

       951
       951
       +
       

     

       952
       952
       +
       

     

       953
       953
       +
       

     

       954
       954
       +
       Jenkins & Newman             Standards Track                   [Page 17]

     

       955
       955
       +
       

     

       956
       956
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       957
       957
       +
       

     

       958
       958
       +
       

     

       959
       959
       +
          Now suppose an Email is marked read, and we get a push update that

     

       960
       960
       +
          the Mailbox state has changed.  You might fetch the updates like

     

       961
       961
       +
          this:

     

       962
       962
       +
       

     

       963
       963
       +
                            [[ "Mailbox/changes", {

     

       964
       964
       +
                              "accountId": "u33084183",

     

       965
       965
       +
                              "sinceState": "78540"

     

       966
       966
       +
                            }, "0" ],

     

       967
       967
       +
                            [ "Mailbox/get", {

     

       968
       968
       +
                              "accountId": "u33084183",

     

       969
       969
       +
                              "#ids": {

     

       970
       970
       +
                                "resultOf": "0",

     

       971
       971
       +
                                "name": "Mailbox/changes",

     

       972
       972
       +
                                "path": "/created"

     

       973
       973
       +
                              }

     

       974
       974
       +
                            }, "1" ],

     

       975
       975
       +
                            [ "Mailbox/get", {

     

       976
       976
       +
                              "accountId": "u33084183",

     

       977
       977
       +
                              "#ids": {

     

       978
       978
       +
                                "resultOf": "0",

     

       979
       979
       +
                                "name": "Mailbox/changes",

     

       980
       980
       +
                                "path": "/updated"

     

       981
       981
       +
                              },

     

       982
       982
       +
                              "#properties": {

     

       983
       983
       +
                                "resultOf": "0",

     

       984
       984
       +
                                "name": "Mailbox/changes",

     

       985
       985
       +
                                "path": "/updatedProperties"

     

       986
       986
       +
                              }

     

       987
       987
       +
                            }, "2" ]]

     

       988
       988
       +
       

     

       989
       989
       +
       

     

       990
       990
       +
       

     

       991
       991
       +
       

     

       992
       992
       +
       

     

       993
       993
       +
       

     

       994
       994
       +
       

     

       995
       995
       +
       

     

       996
       996
       +
       

     

       997
       997
       +
       

     

       998
       998
       +
       

     

       999
       999
       +
       

     

       1000
       1000
       +
       

     

       1001
       1001
       +
       

     

       1002
       1002
       +
       

     

       1003
       1003
       +
       

     

       1004
       1004
       +
       

     

       1005
       1005
       +
       

     

       1006
       1006
       +
       

     

       1007
       1007
       +
       

     

       1008
       1008
       +
       

     

       1009
       1009
       +
       

     

       1010
       1010
       +
       Jenkins & Newman             Standards Track                   [Page 18]

     

       1011
       1011
       +
       

     

       1012
       1012
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1013
       1013
       +
       

     

       1014
       1014
       +
       

     

       1015
       1015
       +
          This fetches the list of ids for created/updated/destroyed Mailboxes,

     

       1016
       1016
       +
          then using back-references, it fetches the data for just the created/

     

       1017
       1017
       +
          updated Mailboxes in the same request.  The response may look

     

       1018
       1018
       +
          something like this:

     

       1019
       1019
       +
       

     

       1020
       1020
       +
                          [[ "Mailbox/changes", {

     

       1021
       1021
       +
                            "accountId": "u33084183",

     

       1022
       1022
       +
                            "oldState": "78541",

     

       1023
       1023
       +
                            "newState": "78542",

     

       1024
       1024
       +
                            "hasMoreChanges": false,

     

       1025
       1025
       +
                            "updatedProperties": [

     

       1026
       1026
       +
                              "totalEmails", "unreadEmails",

     

       1027
       1027
       +
                              "totalThreads", "unreadThreads"

     

       1028
       1028
       +
                            ],

     

       1029
       1029
       +
                            "created": [],

     

       1030
       1030
       +
                            "updated": ["MB23cfa8094c0f41e6"],

     

       1031
       1031
       +
                            "destroyed": []

     

       1032
       1032
       +
                          }, "0" ],

     

       1033
       1033
       +
                          [ "Mailbox/get", {

     

       1034
       1034
       +
                            "accountId": "u33084183",

     

       1035
       1035
       +
                            "state": "78542",

     

       1036
       1036
       +
                            "list": [],

     

       1037
       1037
       +
                            "notFound": []

     

       1038
       1038
       +
                          }, "1" ],

     

       1039
       1039
       +
                          [ "Mailbox/get", {

     

       1040
       1040
       +
                            "accountId": "u33084183",

     

       1041
       1041
       +
                            "state": "78542",

     

       1042
       1042
       +
                            "list": [{

     

       1043
       1043
       +
                              "id": "MB23cfa8094c0f41e6",

     

       1044
       1044
       +
                              "totalEmails": 16307,

     

       1045
       1045
       +
                              "unreadEmails": 13903,

     

       1046
       1046
       +
                              "totalThreads": 5833,

     

       1047
       1047
       +
                              "unreadThreads": 5127

     

       1048
       1048
       +
                            }],

     

       1049
       1049
       +
                            "notFound": []

     

       1050
       1050
       +
                          }, "2" ]]

     

       1051
       1051
       +
       

     

       1052
       1052
       +
       

     

       1053
       1053
       +
       

     

       1054
       1054
       +
       

     

       1055
       1055
       +
       

     

       1056
       1056
       +
       

     

       1057
       1057
       +
       

     

       1058
       1058
       +
       

     

       1059
       1059
       +
       

     

       1060
       1060
       +
       

     

       1061
       1061
       +
       

     

       1062
       1062
       +
       

     

       1063
       1063
       +
       

     

       1064
       1064
       +
       

     

       1065
       1065
       +
       

     

       1066
       1066
       +
       Jenkins & Newman             Standards Track                   [Page 19]

     

       1067
       1067
       +
       

     

       1068
       1068
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1069
       1069
       +
       

     

       1070
       1070
       +
       

     

       1071
       1071
       +
          Here's an example where we try to rename one Mailbox and destroy

     

       1072
       1072
       +
          another:

     

       1073
       1073
       +
       

     

       1074
       1074
       +
                          [[ "Mailbox/set", {

     

       1075
       1075
       +
                            "accountId": "u33084183",

     

       1076
       1076
       +
                            "ifInState": "78542",

     

       1077
       1077
       +
                            "update": {

     

       1078
       1078
       +
                              "MB674cc24095db49ce": {

     

       1079
       1079
       +
                                "name": "Maybe important mail"

     

       1080
       1080
       +
                              }

     

       1081
       1081
       +
                            },

     

       1082
       1082
       +
                            "destroy": [ "MB23cfa8094c0f41e6" ]

     

       1083
       1083
       +
                          }, "0" ]]

     

       1084
       1084
       +
       

     

       1085
       1085
       +
          Suppose the rename succeeds, but we don't have permission to destroy

     

       1086
       1086
       +
          the Mailbox we tried to destroy; we might get back:

     

       1087
       1087
       +
       

     

       1088
       1088
       +
                            [[ "Mailbox/set", {

     

       1089
       1089
       +
                              "accountId": "u33084183",

     

       1090
       1090
       +
                              "oldState": "78542",

     

       1091
       1091
       +
                              "newState": "78549",

     

       1092
       1092
       +
                              "updated": {

     

       1093
       1093
       +
                                  "MB674cc24095db49ce": null

     

       1094
       1094
       +
                              },

     

       1095
       1095
       +
                              "notDestroyed": {

     

       1096
       1096
       +
                                "MB23cfa8094c0f41e6": {

     

       1097
       1097
       +
                                  "type": "forbidden"

     

       1098
       1098
       +
                                }

     

       1099
       1099
       +
                              }

     

       1100
       1100
       +
                            }, "0" ]]

     

       1101
       1101
       +
       

     

       1102
       1102
       +
       3.  Threads

     

       1103
       1103
       +
       

     

       1104
       1104
       +
          Replies are grouped together with the original message to form a

     

       1105
       1105
       +
          Thread.  In JMAP, a Thread is simply a flat list of Emails, ordered

     

       1106
       1106
       +
          by date.  Every Email MUST belong to a Thread, even if it is the only

     

       1107
       1107
       +
          Email in the Thread.

     

       1108
       1108
       +
       

     

       1109
       1109
       +
          The exact algorithm for determining whether two Emails belong to the

     

       1110
       1110
       +
          same Thread is not mandated in this spec to allow for compatibility

     

       1111
       1111
       +
          with different existing systems.  For new implementations, it is

     

       1112
       1112
       +
          suggested that two messages belong in the same Thread if both of the

     

       1113
       1113
       +
          following conditions apply:

     

       1114
       1114
       +
       

     

       1115
       1115
       +
          1.  An identical message id [RFC5322] appears in both messages in any

     

       1116
       1116
       +
              of the Message-Id, In-Reply-To, and References header fields.

     

       1117
       1117
       +
       

     

       1118
       1118
       +
       

     

       1119
       1119
       +
       

     

       1120
       1120
       +
       

     

       1121
       1121
       +
       

     

       1122
       1122
       +
       Jenkins & Newman             Standards Track                   [Page 20]

     

       1123
       1123
       +
       

     

       1124
       1124
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1125
       1125
       +
       

     

       1126
       1126
       +
       

     

       1127
       1127
       +
          2.  After stripping automatically added prefixes such as "Fwd:",

     

       1128
       1128
       +
              "Re:", "[List-Tag]", etc., and ignoring white space, the subjects

     

       1129
       1129
       +
              are the same.  This avoids the situation where a person replies

     

       1130
       1130
       +
              to an old message as a convenient way of finding the right

     

       1131
       1131
       +
              recipient to send to but changes the subject and starts a new

     

       1132
       1132
       +
              conversation.

     

       1133
       1133
       +
       

     

       1134
       1134
       +
          If messages are delivered out of order for some reason, a user may

     

       1135
       1135
       +
          have two Emails in the same Thread but without headers that associate

     

       1136
       1136
       +
          them with each other.  The arrival of a third Email may provide the

     

       1137
       1137
       +
          missing references to join them all together into a single Thread.

     

       1138
       1138
       +
          Since the "threadId" of an Email is immutable, if the server wishes

     

       1139
       1139
       +
          to merge the Threads, it MUST handle this by deleting and reinserting

     

       1140
       1140
       +
          (with a new Email id) the Emails that change "threadId".

     

       1141
       1141
       +
       

     

       1142
       1142
       +
          A *Thread* object has the following properties:

     

       1143
       1143
       +
       

     

       1144
       1144
       +
          o  id: "Id" (immutable; server-set)

     

       1145
       1145
       +
       

     

       1146
       1146
       +
       

     

       1147
       1147
       +
             The id of the Thread.

     

       1148
       1148
       +
       

     

       1149
       1149
       +
          o  emailIds: "Id[]" (server-set)

     

       1150
       1150
       +
       

     

       1151
       1151
       +
             The ids of the Emails in the Thread, sorted by the "receivedAt"

     

       1152
       1152
       +
             date of the Email, oldest first.  If two Emails have an identical

     

       1153
       1153
       +
             date, the sort is server dependent but MUST be stable (sorting by

     

       1154
       1154
       +
             id is recommended).

     

       1155
       1155
       +
       

     

       1156
       1156
       +
          The following JMAP methods are supported.

     

       1157
       1157
       +
       

     

       1158
       1158
       +
       

     

       1159
       1159
       +
       

     

       1160
       1160
       +
       

     

       1161
       1161
       +
       

     

       1162
       1162
       +
       

     

       1163
       1163
       +
       

     

       1164
       1164
       +
       

     

       1165
       1165
       +
       

     

       1166
       1166
       +
       

     

       1167
       1167
       +
       

     

       1168
       1168
       +
       

     

       1169
       1169
       +
       

     

       1170
       1170
       +
       

     

       1171
       1171
       +
       

     

       1172
       1172
       +
       

     

       1173
       1173
       +
       

     

       1174
       1174
       +
       

     

       1175
       1175
       +
       

     

       1176
       1176
       +
       

     

       1177
       1177
       +
       

     

       1178
       1178
       +
       Jenkins & Newman             Standards Track                   [Page 21]

     

       1179
       1179
       +
       

     

       1180
       1180
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1181
       1181
       +
       

     

       1182
       1182
       +
       

     

       1183
       1183
       +
       3.1.  Thread/get

     

       1184
       1184
       +
       

     

       1185
       1185
       +
          This is a standard "/get" method as described in [RFC8620],

     

       1186
       1186
       +
          Section 5.1.

     

       1187
       1187
       +
       

     

       1188
       1188
       +
       3.1.1.  Example

     

       1189
       1189
       +
       

     

       1190
       1190
       +
          Request:

     

       1191
       1191
       +
       

     

       1192
       1192
       +
                              [[ "Thread/get", {

     

       1193
       1193
       +
                                "accountId": "acme",

     

       1194
       1194
       +
                                "ids": ["f123u4", "f41u44"]

     

       1195
       1195
       +
                              }, "#1" ]]

     

       1196
       1196
       +
       

     

       1197
       1197
       +
          with response:

     

       1198
       1198
       +
       

     

       1199
       1199
       +
                        [[ "Thread/get", {

     

       1200
       1200
       +
                          "accountId": "acme",

     

       1201
       1201
       +
                          "state": "f6a7e214",

     

       1202
       1202
       +
                          "list": [

     

       1203
       1203
       +
                            {

     

       1204
       1204
       +
                              "id": "f123u4",

     

       1205
       1205
       +
                              "emailIds": [ "eaa623", "f782cbb"]

     

       1206
       1206
       +
                            },

     

       1207
       1207
       +
                            {

     

       1208
       1208
       +
                              "id": "f41u44",

     

       1209
       1209
       +
                              "emailIds": [ "82cf7bb" ]

     

       1210
       1210
       +
                            }

     

       1211
       1211
       +
                          ],

     

       1212
       1212
       +
                          "notFound": []

     

       1213
       1213
       +
                        }, "#1" ]]

     

       1214
       1214
       +
       

     

       1215
       1215
       +
       3.2.  Thread/changes

     

       1216
       1216
       +
       

     

       1217
       1217
       +
          This is a standard "/changes" method as described in [RFC8620],

     

       1218
       1218
       +
          Section 5.2.

     

       1219
       1219
       +
       

     

       1220
       1220
       +
       4.  Emails

     

       1221
       1221
       +
       

     

       1222
       1222
       +
          An *Email* object is a representation of a message [RFC5322], which

     

       1223
       1223
       +
          allows clients to avoid the complexities of MIME parsing, transfer

     

       1224
       1224
       +
          encoding, and character encoding.

     

       1225
       1225
       +
       

     

       1226
       1226
       +
       

     

       1227
       1227
       +
       

     

       1228
       1228
       +
       

     

       1229
       1229
       +
       

     

       1230
       1230
       +
       

     

       1231
       1231
       +
       

     

       1232
       1232
       +
       

     

       1233
       1233
       +
       

     

       1234
       1234
       +
       Jenkins & Newman             Standards Track                   [Page 22]

     

       1235
       1235
       +
       

     

       1236
       1236
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1237
       1237
       +
       

     

       1238
       1238
       +
       

     

       1239
       1239
       +
       4.1.  Properties of the Email Object

     

       1240
       1240
       +
       

     

       1241
       1241
       +
          Broadly, a message consists of two parts: a list of header fields and

     

       1242
       1242
       +
          then a body.  The Email data type provides a way to access the full

     

       1243
       1243
       +
          structure or to use simplified properties and avoid some complexity

     

       1244
       1244
       +
          if this is sufficient for the client application.

     

       1245
       1245
       +
       

     

       1246
       1246
       +
          While raw headers can be fetched and set, the vast majority of

     

       1247
       1247
       +
          clients should use an appropriate parsed form for each of the header

     

       1248
       1248
       +
          fields it wants to process, as this allows it to avoid the

     

       1249
       1249
       +
          complexities of various encodings that are required in a valid

     

       1250
       1250
       +
          message per RFC 5322.

     

       1251
       1251
       +
       

     

       1252
       1252
       +
          The body of a message is normally a MIME-encoded set of documents in

     

       1253
       1253
       +
          a tree structure.  This may be arbitrarily nested, but the majority

     

       1254
       1254
       +
          of email clients present a flat model of a message body (normally

     

       1255
       1255
       +
          plaintext or HTML) with a set of attachments.  Flattening the MIME

     

       1256
       1256
       +
          structure to form this model can be difficult and causes

     

       1257
       1257
       +
          inconsistency between clients.  Therefore, in addition to the

     

       1258
       1258
       +
          "bodyStructure" property, which gives the full tree, the Email object

     

       1259
       1259
       +
          contains 3 alternate properties with flat lists of body parts:

     

       1260
       1260
       +
       

     

       1261
       1261
       +
          o  "textBody"/"htmlBody": These provide a list of parts that should

     

       1262
       1262
       +
             be rendered sequentially as the "body" of the message.  This is a

     

       1263
       1263
       +
             list rather than a single part as messages may have headers and/or

     

       1264
       1264
       +
             footers appended/prepended as separate parts when they are

     

       1265
       1265
       +
             transmitted, and some clients send text and images intended to be

     

       1266
       1266
       +
             displayed inline in the body (or even videos and sound clips) as

     

       1267
       1267
       +
             multiple parts rather than a single HTML part with referenced

     

       1268
       1268
       +
             images.

     

       1269
       1269
       +
       

     

       1270
       1270
       +
             Because MIME allows for multiple representations of the same data

     

       1271
       1271
       +
             (using "multipart/alternative"), there is a "textBody" property

     

       1272
       1272
       +
             (which prefers a plaintext representation) and an "htmlBody"

     

       1273
       1273
       +
             property (which prefers an HTML representation) to accommodate the

     

       1274
       1274
       +
             two most common client requirements.  The same part may appear in

     

       1275
       1275
       +
             both lists where there is no alternative between the two.

     

       1276
       1276
       +
       

     

       1277
       1277
       +
          o  "attachments": This provides a list of parts that should be

     

       1278
       1278
       +
             presented as "attachments" to the message.  Some images may be

     

       1279
       1279
       +
             solely there for embedding within an HTML body part; clients may

     

       1280
       1280
       +
             wish to not present these as attachments in the user interface if

     

       1281
       1281
       +
             they are displaying the HTML with the embedded images directly.

     

       1282
       1282
       +
             Some parts may also be in htmlBody/textBody; again, clients may

     

       1283
       1283
       +
             wish to not present these as attachments in the user interface if

     

       1284
       1284
       +
             rendered as part of the body.

     

       1285
       1285
       +
       

     

       1286
       1286
       +
       

     

       1287
       1287
       +
       

     

       1288
       1288
       +
       

     

       1289
       1289
       +
       

     

       1290
       1290
       +
       Jenkins & Newman             Standards Track                   [Page 23]

     

       1291
       1291
       +
       

     

       1292
       1292
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1293
       1293
       +
       

     

       1294
       1294
       +
       

     

       1295
       1295
       +
          The "bodyValues" property allows for clients to fetch the value of

     

       1296
       1296
       +
          text parts directly without having to do a second request for the

     

       1297
       1297
       +
          blob and to have the server handle decoding the charset into unicode.

     

       1298
       1298
       +
          This data is in a separate property rather than on the EmailBodyPart

     

       1299
       1299
       +
          object to avoid duplication of large amounts of data, as the same

     

       1300
       1300
       +
          part may be included twice if the client fetches more than one of

     

       1301
       1301
       +
          bodyStructure, textBody, and htmlBody.

     

       1302
       1302
       +
       

     

       1303
       1303
       +
          In the following subsections, the common notational convention for

     

       1304
       1304
       +
          wildcards has been adopted for content types, so "foo/*" means any

     

       1305
       1305
       +
          content type that starts with "foo/".

     

       1306
       1306
       +
       

     

       1307
       1307
       +
          Due to the number of properties involved, the set of Email properties

     

       1308
       1308
       +
          is specified over the following four subsections.  This is purely for

     

       1309
       1309
       +
          readability; all properties are top-level peers.

     

       1310
       1310
       +
       

     

       1311
       1311
       +
       4.1.1.  Metadata

     

       1312
       1312
       +
       

     

       1313
       1313
       +
          These properties represent metadata about the message in the mail

     

       1314
       1314
       +
          store and are not derived from parsing the message itself.

     

       1315
       1315
       +
       

     

       1316
       1316
       +
          o  id: "Id" (immutable; server-set)

     

       1317
       1317
       +
       

     

       1318
       1318
       +
             The id of the Email object.  Note that this is the JMAP object id,

     

       1319
       1319
       +
             NOT the Message-ID header field value of the message [RFC5322].

     

       1320
       1320
       +
       

     

       1321
       1321
       +
          o  blobId: "Id" (immutable; server-set)

     

       1322
       1322
       +
       

     

       1323
       1323
       +
             The id representing the raw octets of the message [RFC5322] for

     

       1324
       1324
       +
             this Email.  This may be used to download the raw original message

     

       1325
       1325
       +
             or to attach it directly to another Email, etc.

     

       1326
       1326
       +
       

     

       1327
       1327
       +
          o  threadId: "Id" (immutable; server-set)

     

       1328
       1328
       +
       

     

       1329
       1329
       +
             The id of the Thread to which this Email belongs.

     

       1330
       1330
       +
       

     

       1331
       1331
       +
          o  mailboxIds: "Id[Boolean]"

     

       1332
       1332
       +
       

     

       1333
       1333
       +
             The set of Mailbox ids this Email belongs to.  An Email in the

     

       1334
       1334
       +
             mail store MUST belong to one or more Mailboxes at all times

     

       1335
       1335
       +
             (until it is destroyed).  The set is represented as an object,

     

       1336
       1336
       +
             with each key being a Mailbox id.  The value for each key in the

     

       1337
       1337
       +
             object MUST be true.

     

       1338
       1338
       +
       

     

       1339
       1339
       +
       

     

       1340
       1340
       +
       

     

       1341
       1341
       +
       

     

       1342
       1342
       +
       

     

       1343
       1343
       +
       

     

       1344
       1344
       +
       

     

       1345
       1345
       +
       

     

       1346
       1346
       +
       Jenkins & Newman             Standards Track                   [Page 24]

     

       1347
       1347
       +
       

     

       1348
       1348
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1349
       1349
       +
       

     

       1350
       1350
       +
       

     

       1351
       1351
       +
          o  keywords: "String[Boolean]" (default: {})

     

       1352
       1352
       +
       

     

       1353
       1353
       +
             A set of keywords that apply to the Email.  The set is represented

     

       1354
       1354
       +
             as an object, with the keys being the keywords.  The value for

     

       1355
       1355
       +
             each key in the object MUST be true.

     

       1356
       1356
       +
       

     

       1357
       1357
       +
             Keywords are shared with IMAP.  The six system keywords from IMAP

     

       1358
       1358
       +
             get special treatment.  The following four keywords have their

     

       1359
       1359
       +
             first character changed from "\" in IMAP to "$" in JMAP and have

     

       1360
       1360
       +
             particular semantic meaning:

     

       1361
       1361
       +
       

     

       1362
       1362
       +
             *  "$draft": The Email is a draft the user is composing.

     

       1363
       1363
       +
       

     

       1364
       1364
       +
             *  "$seen": The Email has been read.

     

       1365
       1365
       +
       

     

       1366
       1366
       +
             *  "$flagged": The Email has been flagged for urgent/special

     

       1367
       1367
       +
                attention.

     

       1368
       1368
       +
       

     

       1369
       1369
       +
             *  "$answered": The Email has been replied to.

     

       1370
       1370
       +
       

     

       1371
       1371
       +
             The IMAP "\Recent" keyword is not exposed via JMAP.  The IMAP

     

       1372
       1372
       +
             "\Deleted" keyword is also not present: IMAP uses a delete+expunge

     

       1373
       1373
       +
             model, which JMAP does not.  Any message with the "\Deleted"

     

       1374
       1374
       +
             keyword MUST NOT be visible via JMAP (and so are not counted in

     

       1375
       1375
       +
             the "totalEmails", "unreadEmails", "totalThreads", and

     

       1376
       1376
       +
             "unreadThreads" Mailbox properties).

     

       1377
       1377
       +
       

     

       1378
       1378
       +
             Users may add arbitrary keywords to an Email.  For compatibility

     

       1379
       1379
       +
             with IMAP, a keyword is a case-insensitive string of 1-255

     

       1380
       1380
       +
             characters in the ASCII subset %x21-%x7e (excludes control chars

     

       1381
       1381
       +
             and space), and it MUST NOT include any of these characters:

     

       1382
       1382
       +
       

     

       1383
       1383
       +
                                     ( ) { ] % * " \

     

       1384
       1384
       +
       

     

       1385
       1385
       +
             Because JSON is case sensitive, servers MUST return keywords in

     

       1386
       1386
       +
             lowercase.

     

       1387
       1387
       +
       

     

       1388
       1388
       +
             The IANA "IMAP and JMAP Keywords" registry at

     

       1389
       1389
       +
             <https://www.iana.org/assignments/imap-jmap-keywords/> as

     

       1390
       1390
       +
             established in [RFC5788] assigns semantic meaning to some other

     

       1391
       1391
       +
             keywords in common use.  New keywords may be established here in

     

       1392
       1392
       +
             the future.  In particular, note:

     

       1393
       1393
       +
       

     

       1394
       1394
       +
             *  "$forwarded": The Email has been forwarded.

     

       1395
       1395
       +
       

     

       1396
       1396
       +
             *  "$phishing": The Email is highly likely to be phishing.

     

       1397
       1397
       +
                Clients SHOULD warn users to take care when viewing this Email

     

       1398
       1398
       +
                and disable links and attachments.

     

       1399
       1399
       +
       

     

       1400
       1400
       +
       

     

       1401
       1401
       +
       

     

       1402
       1402
       +
       Jenkins & Newman             Standards Track                   [Page 25]

     

       1403
       1403
       +
       

     

       1404
       1404
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1405
       1405
       +
       

     

       1406
       1406
       +
       

     

       1407
       1407
       +
             *  "$junk": The Email is definitely spam.  Clients SHOULD set this

     

       1408
       1408
       +
                flag when users report spam to help train automated spam-

     

       1409
       1409
       +
                detection systems.

     

       1410
       1410
       +
       

     

       1411
       1411
       +
             *  "$notjunk": The Email is definitely not spam.  Clients SHOULD

     

       1412
       1412
       +
                set this flag when users indicate an Email is legitimate, to

     

       1413
       1413
       +
                help train automated spam-detection systems.

     

       1414
       1414
       +
       

     

       1415
       1415
       +
          o  size: "UnsignedInt" (immutable; server-set)

     

       1416
       1416
       +
       

     

       1417
       1417
       +
             The size, in octets, of the raw data for the message [RFC5322] (as

     

       1418
       1418
       +
             referenced by the "blobId", i.e., the number of octets in the file

     

       1419
       1419
       +
             the user would download).

     

       1420
       1420
       +
       

     

       1421
       1421
       +
          o  receivedAt: "UTCDate" (immutable; default: time of creation on

     

       1422
       1422
       +
             server)

     

       1423
       1423
       +
       

     

       1424
       1424
       +
             The date the Email was received by the message store.  This is the

     

       1425
       1425
       +
             "internal date" in IMAP [RFC3501].

     

       1426
       1426
       +
       

     

       1427
       1427
       +
       4.1.2.  Header Fields Parsed Forms

     

       1428
       1428
       +
       

     

       1429
       1429
       +
          Header field properties are derived from the message header fields

     

       1430
       1430
       +
          [RFC5322] [RFC6532].  All header fields may be fetched in a raw form.

     

       1431
       1431
       +
          Some header fields may also be fetched in a parsed form.  The

     

       1432
       1432
       +
          structured form that may be fetched depends on the header.  The forms

     

       1433
       1433
       +
          are defined in the subsections that follow.

     

       1434
       1434
       +
       

     

       1435
       1435
       +
       4.1.2.1.  Raw

     

       1436
       1436
       +
       

     

       1437
       1437
       +
          Type: "String"

     

       1438
       1438
       +
       

     

       1439
       1439
       +
          The raw octets of the header field value from the first octet

     

       1440
       1440
       +
          following the header field name terminating colon, up to but

     

       1441
       1441
       +
          excluding the header field terminating CRLF.  Any standards-compliant

     

       1442
       1442
       +
          message MUST be either ASCII (RFC 5322) or UTF-8 (RFC 6532); however,

     

       1443
       1443
       +
          other encodings exist in the wild.  A server SHOULD replace any octet

     

       1444
       1444
       +
          or octet run with the high bit set that violates UTF-8 syntax with

     

       1445
       1445
       +
          the unicode replacement character (U+FFFD).  Any NUL octet MUST be

     

       1446
       1446
       +
          dropped.

     

       1447
       1447
       +
       

     

       1448
       1448
       +
          This form will typically have a leading space, as most generated

     

       1449
       1449
       +
          messages insert a space after the colon that terminates the header

     

       1450
       1450
       +
          field name.

     

       1451
       1451
       +
       

     

       1452
       1452
       +
       

     

       1453
       1453
       +
       

     

       1454
       1454
       +
       

     

       1455
       1455
       +
       

     

       1456
       1456
       +
       

     

       1457
       1457
       +
       

     

       1458
       1458
       +
       Jenkins & Newman             Standards Track                   [Page 26]

     

       1459
       1459
       +
       

     

       1460
       1460
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1461
       1461
       +
       

     

       1462
       1462
       +
       

     

       1463
       1463
       +
       4.1.2.2.  Text

     

       1464
       1464
       +
       

     

       1465
       1465
       +
          Type: "String"

     

       1466
       1466
       +
       

     

       1467
       1467
       +
          The header field value with:

     

       1468
       1468
       +
       

     

       1469
       1469
       +
          1.  White space unfolded (as defined in [RFC5322], Section 2.2.3).

     

       1470
       1470
       +
       

     

       1471
       1471
       +
          2.  The terminating CRLF at the end of the value removed.

     

       1472
       1472
       +
       

     

       1473
       1473
       +
          3.  Any SP characters at the beginning of the value removed.

     

       1474
       1474
       +
       

     

       1475
       1475
       +
          4.  Any syntactically correct encoded sections [RFC2047] with a known

     

       1476
       1476
       +
              character set decoded.  Any NUL octets or control characters

     

       1477
       1477
       +
              encoded per [RFC2047] are dropped from the decoded value.  Any

     

       1478
       1478
       +
              text that looks like syntax per [RFC2047] but violates placement

     

       1479
       1479
       +
              or white space rules per [RFC2047] MUST NOT be decoded.

     

       1480
       1480
       +
       

     

       1481
       1481
       +
          5.  The resulting unicode converted to Normalization Form C (NFC)

     

       1482
       1482
       +
              form.

     

       1483
       1483
       +
       

     

       1484
       1484
       +
          If any decodings fail, the parser SHOULD insert a unicode replacement

     

       1485
       1485
       +
          character (U+FFFD) and attempt to continue as much as possible.

     

       1486
       1486
       +
       

     

       1487
       1487
       +
          To prevent obviously nonsense behaviour, which can lead to

     

       1488
       1488
       +
          interoperability issues, this form may only be fetched or set for the

     

       1489
       1489
       +
          following header fields:

     

       1490
       1490
       +
       

     

       1491
       1491
       +
          o  Subject

     

       1492
       1492
       +
       

     

       1493
       1493
       +
          o  Comments

     

       1494
       1494
       +
       

     

       1495
       1495
       +
          o  Keywords

     

       1496
       1496
       +
       

     

       1497
       1497
       +
          o  List-Id

     

       1498
       1498
       +
       

     

       1499
       1499
       +
          o  Any header field not defined in [RFC5322] or [RFC2369]

     

       1500
       1500
       +
       

     

       1501
       1501
       +
       4.1.2.3.  Addresses

     

       1502
       1502
       +
       

     

       1503
       1503
       +
          Type: "EmailAddress[]"

     

       1504
       1504
       +
       

     

       1505
       1505
       +
          The header field is parsed as an "address-list" value, as specified

     

       1506
       1506
       +
          in [RFC5322], Section 3.4, into the "EmailAddress[]" type.  There is

     

       1507
       1507
       +
          an EmailAddress item for each "mailbox" parsed from the "address-

     

       1508
       1508
       +
          list".  Group and comment information is discarded.

     

       1509
       1509
       +
       

     

       1510
       1510
       +
       

     

       1511
       1511
       +
       

     

       1512
       1512
       +
       

     

       1513
       1513
       +
       

     

       1514
       1514
       +
       Jenkins & Newman             Standards Track                   [Page 27]

     

       1515
       1515
       +
       

     

       1516
       1516
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1517
       1517
       +
       

     

       1518
       1518
       +
       

     

       1519
       1519
       +
          An *EmailAddress* object has the following properties:

     

       1520
       1520
       +
       

     

       1521
       1521
       +
          o  name: "String|null"

     

       1522
       1522
       +
       

     

       1523
       1523
       +
             The "display-name" of the "mailbox" [RFC5322].  If this is a

     

       1524
       1524
       +
             "quoted-string":

     

       1525
       1525
       +
       

     

       1526
       1526
       +
             1.  The surrounding DQUOTE characters are removed.

     

       1527
       1527
       +
       

     

       1528
       1528
       +
             2.  Any "quoted-pair" is decoded.

     

       1529
       1529
       +
       

     

       1530
       1530
       +
             3.  White space is unfolded, and then any leading and trailing

     

       1531
       1531
       +
                 white space is removed.

     

       1532
       1532
       +
       

     

       1533
       1533
       +
             If there is no "display-name" but there is a "comment" immediately

     

       1534
       1534
       +
             following the "addr-spec", the value of this SHOULD be used

     

       1535
       1535
       +
             instead.  Otherwise, this property is null.

     

       1536
       1536
       +
       

     

       1537
       1537
       +
          o  email: "String"

     

       1538
       1538
       +
       

     

       1539
       1539
       +
             The "addr-spec" of the "mailbox" [RFC5322].

     

       1540
       1540
       +
       

     

       1541
       1541
       +
          Any syntactically correct encoded sections [RFC2047] with a known

     

       1542
       1542
       +
          encoding MUST be decoded, following the same rules as for the Text

     

       1543
       1543
       +
          form (see Section 4.1.2.2).

     

       1544
       1544
       +
       

     

       1545
       1545
       +
          Parsing SHOULD be best effort in the face of invalid structure to

     

       1546
       1546
       +
          accommodate invalid messages and semi-complete drafts.  EmailAddress

     

       1547
       1547
       +
          objects MAY have an "email" property that does not conform to the

     

       1548
       1548
       +
          "addr-spec" form (for example, may not contain an @ symbol).

     

       1549
       1549
       +
       

     

       1550
       1550
       +
          For example, the following "address-list" string:

     

       1551
       1551
       +
       

     

       1552
       1552
       +
                     "  James Smythe" <james@example.com>, Friends:

     

       1553
       1553
       +
                       jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?=

     

       1554
       1554
       +
                       <john@example.com>;

     

       1555
       1555
       +
       

     

       1556
       1556
       +
          would be parsed as:

     

       1557
       1557
       +
       

     

       1558
       1558
       +
               [

     

       1559
       1559
       +
                 { "name": "James Smythe", "email": "james@example.com" },

     

       1560
       1560
       +
                 { "name": null, "email": "jane@example.com" },

     

       1561
       1561
       +
                 { "name": "John Smith", "email": "john@example.com" }

     

       1562
       1562
       +
               ]

     

       1563
       1563
       +
       

     

       1564
       1564
       +
       

     

       1565
       1565
       +
       

     

       1566
       1566
       +
       

     

       1567
       1567
       +
       

     

       1568
       1568
       +
       

     

       1569
       1569
       +
       

     

       1570
       1570
       +
       Jenkins & Newman             Standards Track                   [Page 28]

     

       1571
       1571
       +
       

     

       1572
       1572
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1573
       1573
       +
       

     

       1574
       1574
       +
       

     

       1575
       1575
       +
          To prevent obviously nonsense behaviour, which can lead to

     

       1576
       1576
       +
          interoperability issues, this form may only be fetched or set for the

     

       1577
       1577
       +
          following header fields:

     

       1578
       1578
       +
       

     

       1579
       1579
       +
          o  From

     

       1580
       1580
       +
       

     

       1581
       1581
       +
          o  Sender

     

       1582
       1582
       +
       

     

       1583
       1583
       +
          o  Reply-To

     

       1584
       1584
       +
       

     

       1585
       1585
       +
          o  To

     

       1586
       1586
       +
       

     

       1587
       1587
       +
          o  Cc

     

       1588
       1588
       +
       

     

       1589
       1589
       +
          o  Bcc

     

       1590
       1590
       +
       

     

       1591
       1591
       +
          o  Resent-From

     

       1592
       1592
       +
       

     

       1593
       1593
       +
          o  Resent-Sender

     

       1594
       1594
       +
       

     

       1595
       1595
       +
          o  Resent-Reply-To

     

       1596
       1596
       +
       

     

       1597
       1597
       +
          o  Resent-To

     

       1598
       1598
       +
       

     

       1599
       1599
       +
          o  Resent-Cc

     

       1600
       1600
       +
       

     

       1601
       1601
       +
          o  Resent-Bcc

     

       1602
       1602
       +
       

     

       1603
       1603
       +
          o  Any header field not defined in [RFC5322] or [RFC2369]

     

       1604
       1604
       +
       

     

       1605
       1605
       +
       4.1.2.4.  GroupedAddresses

     

       1606
       1606
       +
       

     

       1607
       1607
       +
          Type: "EmailAddressGroup[]"

     

       1608
       1608
       +
       

     

       1609
       1609
       +
          This is similar to the Addresses form but preserves group

     

       1610
       1610
       +
          information.  The header field is parsed as an "address-list" value,

     

       1611
       1611
       +
          as specified in [RFC5322], Section 3.4, into the "GroupedAddresses[]"

     

       1612
       1612
       +
          type.  Consecutive "mailbox" values that are not part of a group are

     

       1613
       1613
       +
          still collected under an EmailAddressGroup object to provide a

     

       1614
       1614
       +
          uniform type.

     

       1615
       1615
       +
       

     

       1616
       1616
       +
       

     

       1617
       1617
       +
       

     

       1618
       1618
       +
       

     

       1619
       1619
       +
       

     

       1620
       1620
       +
       

     

       1621
       1621
       +
       

     

       1622
       1622
       +
       

     

       1623
       1623
       +
       

     

       1624
       1624
       +
       

     

       1625
       1625
       +
       

     

       1626
       1626
       +
       Jenkins & Newman             Standards Track                   [Page 29]

     

       1627
       1627
       +
       

     

       1628
       1628
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1629
       1629
       +
       

     

       1630
       1630
       +
       

     

       1631
       1631
       +
          An *EmailAddressGroup* object has the following properties:

     

       1632
       1632
       +
       

     

       1633
       1633
       +
          o  name: "String|null"

     

       1634
       1634
       +
       

     

       1635
       1635
       +
             The "display-name" of the "group" [RFC5322], or null if the

     

       1636
       1636
       +
             addresses are not part of a group.  If this is a "quoted-string",

     

       1637
       1637
       +
             it is processed the same as the "name" in the EmailAddress type.

     

       1638
       1638
       +
       

     

       1639
       1639
       +
          o  addresses: "EmailAddress[]"

     

       1640
       1640
       +
       

     

       1641
       1641
       +
             The "mailbox" values that belong to this group, represented as

     

       1642
       1642
       +
             EmailAddress objects.

     

       1643
       1643
       +
       

     

       1644
       1644
       +
          Any syntactically correct encoded sections [RFC2047] with a known

     

       1645
       1645
       +
          encoding MUST be decoded, following the same rules as for the Text

     

       1646
       1646
       +
          form (see Section 4.1.2.2).

     

       1647
       1647
       +
       

     

       1648
       1648
       +
          Parsing SHOULD be best effort in the face of invalid structure to

     

       1649
       1649
       +
          accommodate invalid messages and semi-complete drafts.

     

       1650
       1650
       +
       

     

       1651
       1651
       +
          For example, the following "address-list" string:

     

       1652
       1652
       +
       

     

       1653
       1653
       +
                     "  James Smythe" <james@example.com>, Friends:

     

       1654
       1654
       +
                       jane@example.com, =?UTF-8?Q?John_Sm=C3=AEth?=

     

       1655
       1655
       +
                       <john@example.com>;

     

       1656
       1656
       +
       

     

       1657
       1657
       +
          would be parsed as:

     

       1658
       1658
       +
       

     

       1659
       1659
       +
              [

     

       1660
       1660
       +
                { "name": null, "addresses": [

     

       1661
       1661
       +
                  { "name": "James Smythe", "email": "james@example.com" }

     

       1662
       1662
       +
                ]},

     

       1663
       1663
       +
                { "name": "Friends", "addresses": [

     

       1664
       1664
       +
                  { "name": null, "email": "jane@example.com" },

     

       1665
       1665
       +
                  { "name": "John Smith", "email": "john@example.com" }

     

       1666
       1666
       +
                ]}

     

       1667
       1667
       +
              ]

     

       1668
       1668
       +
       

     

       1669
       1669
       +
          To prevent obviously nonsense behaviour, which can lead to

     

       1670
       1670
       +
          interoperability issues, this form may only be fetched or set for the

     

       1671
       1671
       +
          same header fields as the Addresses form (see Section 4.1.2.3).

     

       1672
       1672
       +
       

     

       1673
       1673
       +
       

     

       1674
       1674
       +
       

     

       1675
       1675
       +
       

     

       1676
       1676
       +
       

     

       1677
       1677
       +
       

     

       1678
       1678
       +
       

     

       1679
       1679
       +
       

     

       1680
       1680
       +
       

     

       1681
       1681
       +
       

     

       1682
       1682
       +
       Jenkins & Newman             Standards Track                   [Page 30]

     

       1683
       1683
       +
       

     

       1684
       1684
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1685
       1685
       +
       

     

       1686
       1686
       +
       

     

       1687
       1687
       +
       4.1.2.5.  MessageIds

     

       1688
       1688
       +
       

     

       1689
       1689
       +
          Type: "String[]|null"

     

       1690
       1690
       +
       

     

       1691
       1691
       +
          The header field is parsed as a list of "msg-id" values, as specified

     

       1692
       1692
       +
          in [RFC5322], Section 3.6.4, into the "String[]" type.  Comments and/

     

       1693
       1693
       +
          or folding white space (CFWS) and surrounding angle brackets ("<>")

     

       1694
       1694
       +
          are removed.  If parsing fails, the value is null.

     

       1695
       1695
       +
       

     

       1696
       1696
       +
          To prevent obviously nonsense behaviour, which can lead to

     

       1697
       1697
       +
          interoperability issues, this form may only be fetched or set for the

     

       1698
       1698
       +
          following header fields:

     

       1699
       1699
       +
       

     

       1700
       1700
       +
          o  Message-ID

     

       1701
       1701
       +
       

     

       1702
       1702
       +
          o  In-Reply-To

     

       1703
       1703
       +
       

     

       1704
       1704
       +
          o  References

     

       1705
       1705
       +
       

     

       1706
       1706
       +
          o  Resent-Message-ID

     

       1707
       1707
       +
       

     

       1708
       1708
       +
          o  Any header field not defined in [RFC5322] or [RFC2369]

     

       1709
       1709
       +
       

     

       1710
       1710
       +
       4.1.2.6.  Date

     

       1711
       1711
       +
       

     

       1712
       1712
       +
          Type: "Date|null"

     

       1713
       1713
       +
       

     

       1714
       1714
       +
          The header field is parsed as a "date-time" value, as specified in

     

       1715
       1715
       +
          [RFC5322], Section 3.3, into the "Date" type.  If parsing fails, the

     

       1716
       1716
       +
          value is null.

     

       1717
       1717
       +
       

     

       1718
       1718
       +
          To prevent obviously nonsense behaviour, which can lead to

     

       1719
       1719
       +
          interoperability issues, this form may only be fetched or set for the

     

       1720
       1720
       +
          following header fields:

     

       1721
       1721
       +
       

     

       1722
       1722
       +
          o  Date

     

       1723
       1723
       +
       

     

       1724
       1724
       +
          o  Resent-Date

     

       1725
       1725
       +
       

     

       1726
       1726
       +
          o  Any header field not defined in [RFC5322] or [RFC2369]

     

       1727
       1727
       +
       

     

       1728
       1728
       +
       

     

       1729
       1729
       +
       

     

       1730
       1730
       +
       

     

       1731
       1731
       +
       

     

       1732
       1732
       +
       

     

       1733
       1733
       +
       

     

       1734
       1734
       +
       

     

       1735
       1735
       +
       

     

       1736
       1736
       +
       

     

       1737
       1737
       +
       

     

       1738
       1738
       +
       Jenkins & Newman             Standards Track                   [Page 31]

     

       1739
       1739
       +
       

     

       1740
       1740
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1741
       1741
       +
       

     

       1742
       1742
       +
       

     

       1743
       1743
       +
       4.1.2.7.  URLs

     

       1744
       1744
       +
       

     

       1745
       1745
       +
          Type: "String[]|null"

     

       1746
       1746
       +
       

     

       1747
       1747
       +
          The header field is parsed as a list of URLs, as described in

     

       1748
       1748
       +
          [RFC2369], into the "String[]" type.  Values do not include the

     

       1749
       1749
       +
          surrounding angle brackets or any comments in the header field with

     

       1750
       1750
       +
          the URLs.  If parsing fails, the value is null.

     

       1751
       1751
       +
       

     

       1752
       1752
       +
          To prevent obviously nonsense behaviour, which can lead to

     

       1753
       1753
       +
          interoperability issues, this form may only be fetched or set for the

     

       1754
       1754
       +
          following header fields:

     

       1755
       1755
       +
       

     

       1756
       1756
       +
          o  List-Help

     

       1757
       1757
       +
       

     

       1758
       1758
       +
          o  List-Unsubscribe

     

       1759
       1759
       +
       

     

       1760
       1760
       +
          o  List-Subscribe

     

       1761
       1761
       +
       

     

       1762
       1762
       +
          o  List-Post

     

       1763
       1763
       +
       

     

       1764
       1764
       +
          o  List-Owner

     

       1765
       1765
       +
       

     

       1766
       1766
       +
          o  List-Archive

     

       1767
       1767
       +
       

     

       1768
       1768
       +
          o  Any header field not defined in [RFC5322] or [RFC2369]

     

       1769
       1769
       +
       

     

       1770
       1770
       +
       4.1.3.  Header Fields Properties

     

       1771
       1771
       +
       

     

       1772
       1772
       +
          The following low-level Email property is specified for complete

     

       1773
       1773
       +
          access to the header data of the message:

     

       1774
       1774
       +
       

     

       1775
       1775
       +
          o  headers: "EmailHeader[]" (immutable)

     

       1776
       1776
       +
       

     

       1777
       1777
       +
             This is a list of all header fields [RFC5322], in the same order

     

       1778
       1778
       +
             they appear in the message.  An *EmailHeader* object has the

     

       1779
       1779
       +
             following properties:

     

       1780
       1780
       +
       

     

       1781
       1781
       +
             *  name: "String"

     

       1782
       1782
       +
       

     

       1783
       1783
       +
                The header "field name" as defined in [RFC5322], with the same

     

       1784
       1784
       +
                capitalization that it has in the message.

     

       1785
       1785
       +
       

     

       1786
       1786
       +
             *  value: "String"

     

       1787
       1787
       +
       

     

       1788
       1788
       +
                The header "field value" as defined in [RFC5322], in Raw form.

     

       1789
       1789
       +
       

     

       1790
       1790
       +
       

     

       1791
       1791
       +
       

     

       1792
       1792
       +
       

     

       1793
       1793
       +
       

     

       1794
       1794
       +
       Jenkins & Newman             Standards Track                   [Page 32]

     

       1795
       1795
       +
       

     

       1796
       1796
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1797
       1797
       +
       

     

       1798
       1798
       +
       

     

       1799
       1799
       +
          In addition, the client may request/send properties representing

     

       1800
       1800
       +
          individual header fields of the form:

     

       1801
       1801
       +
       

     

       1802
       1802
       +
                               header:{header-field-name}

     

       1803
       1803
       +
       

     

       1804
       1804
       +
          Where "{header-field-name}" means any series of one or more printable

     

       1805
       1805
       +
          ASCII characters (i.e., characters that have values between 33 and

     

       1806
       1806
       +
          126, inclusive), except for colon (:).  The property may also have

     

       1807
       1807
       +
          the following suffixes:

     

       1808
       1808
       +
       

     

       1809
       1809
       +
          o  :as{header-form}

     

       1810
       1810
       +
       

     

       1811
       1811
       +
             This means the value is in a parsed form, where "{header-form}" is

     

       1812
       1812
       +
             one of the parsed-form names specified above.  If not given, the

     

       1813
       1813
       +
             value is in Raw form.

     

       1814
       1814
       +
       

     

       1815
       1815
       +
          o  :all

     

       1816
       1816
       +
       

     

       1817
       1817
       +
             This means the value is an array, with the items corresponding to

     

       1818
       1818
       +
             each instance of the header field, in the order they appear in the

     

       1819
       1819
       +
             message.  If this suffix is not used, the result is the value of

     

       1820
       1820
       +
             the *last* instance of the header field (i.e., identical to the

     

       1821
       1821
       +
             last item in the array if :all is used), or null if none.

     

       1822
       1822
       +
       

     

       1823
       1823
       +
          If both suffixes are used, they MUST be specified in the order above.

     

       1824
       1824
       +
          Header field names are matched case insensitively.  The value is

     

       1825
       1825
       +
          typed according to the requested form or to an array of that type if

     

       1826
       1826
       +
          :all is used.  If no header fields exist in the message with the

     

       1827
       1827
       +
          requested name, the value is null if fetching a single instance or an

     

       1828
       1828
       +
          empty array if requesting :all.

     

       1829
       1829
       +
       

     

       1830
       1830
       +
          As a simple example, if the client requests a property called

     

       1831
       1831
       +
          "header:subject", this means find the *last* header field in the

     

       1832
       1832
       +
          message named "subject" (matched case insensitively) and return the

     

       1833
       1833
       +
          value in Raw form, or null if no header field of this name is found.

     

       1834
       1834
       +
       

     

       1835
       1835
       +
          For a more complex example, consider the client requesting a property

     

       1836
       1836
       +
          called "header:Resent-To:asAddresses:all".  This means:

     

       1837
       1837
       +
       

     

       1838
       1838
       +
          1.  Find *all* header fields named Resent-To (matched case

     

       1839
       1839
       +
              insensitively).

     

       1840
       1840
       +
       

     

       1841
       1841
       +
          2.  For each instance, parse the header field value in the Addresses

     

       1842
       1842
       +
              form.

     

       1843
       1843
       +
       

     

       1844
       1844
       +
          3.  The result is of type "EmailAddress[][]" -- each item in the

     

       1845
       1845
       +
              array corresponds to the parsed value (which is itself an array)

     

       1846
       1846
       +
              of the Resent-To header field instance.

     

       1847
       1847
       +
       

     

       1848
       1848
       +
       

     

       1849
       1849
       +
       

     

       1850
       1850
       +
       Jenkins & Newman             Standards Track                   [Page 33]

     

       1851
       1851
       +
       

     

       1852
       1852
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1853
       1853
       +
       

     

       1854
       1854
       +
       

     

       1855
       1855
       +
          The following convenience properties are also specified for the Email

     

       1856
       1856
       +
          object:

     

       1857
       1857
       +
       

     

       1858
       1858
       +
          o  messageId: "String[]|null" (immutable)

     

       1859
       1859
       +
       

     

       1860
       1860
       +
             The value is identical to the value of "header:Message-

     

       1861
       1861
       +
             ID:asMessageIds".  For messages conforming to RFC 5322, this will

     

       1862
       1862
       +
             be an array with a single entry.

     

       1863
       1863
       +
       

     

       1864
       1864
       +
          o  inReplyTo: "String[]|null" (immutable)

     

       1865
       1865
       +
       

     

       1866
       1866
       +
             The value is identical to the value of "header:In-Reply-

     

       1867
       1867
       +
             To:asMessageIds".

     

       1868
       1868
       +
       

     

       1869
       1869
       +
          o  references: "String[]|null" (immutable)

     

       1870
       1870
       +
       

     

       1871
       1871
       +
             The value is identical to the value of

     

       1872
       1872
       +
             "header:References:asMessageIds".

     

       1873
       1873
       +
       

     

       1874
       1874
       +
          o  sender: "EmailAddress[]|null" (immutable)

     

       1875
       1875
       +
       

     

       1876
       1876
       +
             The value is identical to the value of

     

       1877
       1877
       +
             "header:Sender:asAddresses".

     

       1878
       1878
       +
       

     

       1879
       1879
       +
          o  from: "EmailAddress[]|null" (immutable)

     

       1880
       1880
       +
       

     

       1881
       1881
       +
             The value is identical to the value of "header:From:asAddresses".

     

       1882
       1882
       +
       

     

       1883
       1883
       +
          o  to: "EmailAddress[]|null" (immutable)

     

       1884
       1884
       +
       

     

       1885
       1885
       +
             The value is identical to the value of "header:To:asAddresses".

     

       1886
       1886
       +
       

     

       1887
       1887
       +
          o  cc: "EmailAddress[]|null" (immutable)

     

       1888
       1888
       +
       

     

       1889
       1889
       +
             The value is identical to the value of "header:Cc:asAddresses".

     

       1890
       1890
       +
       

     

       1891
       1891
       +
          o  bcc: "EmailAddress[]|null" (immutable)

     

       1892
       1892
       +
       

     

       1893
       1893
       +
             The value is identical to the value of "header:Bcc:asAddresses".

     

       1894
       1894
       +
       

     

       1895
       1895
       +
          o  replyTo: "EmailAddress[]|null" (immutable)

     

       1896
       1896
       +
       

     

       1897
       1897
       +
             The value is identical to the value of "header:Reply-

     

       1898
       1898
       +
             To:asAddresses".

     

       1899
       1899
       +
       

     

       1900
       1900
       +
          o  subject: "String|null" (immutable)

     

       1901
       1901
       +
       

     

       1902
       1902
       +
             The value is identical to the value of "header:Subject:asText".

     

       1903
       1903
       +
       

     

       1904
       1904
       +
       

     

       1905
       1905
       +
       

     

       1906
       1906
       +
       Jenkins & Newman             Standards Track                   [Page 34]

     

       1907
       1907
       +
       

     

       1908
       1908
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1909
       1909
       +
       

     

       1910
       1910
       +
       

     

       1911
       1911
       +
          o  sentAt: "Date|null" (immutable; default on creation: current

     

       1912
       1912
       +
             server time)

     

       1913
       1913
       +
       

     

       1914
       1914
       +
             The value is identical to the value of "header:Date:asDate".

     

       1915
       1915
       +
       

     

       1916
       1916
       +
       4.1.4.  Body Parts

     

       1917
       1917
       +
       

     

       1918
       1918
       +
          These properties are derived from the message body [RFC5322] and its

     

       1919
       1919
       +
          MIME entities [RFC2045].

     

       1920
       1920
       +
       

     

       1921
       1921
       +
          An *EmailBodyPart* object has the following properties:

     

       1922
       1922
       +
       

     

       1923
       1923
       +
          o  partId: "String|null"

     

       1924
       1924
       +
       

     

       1925
       1925
       +
             Identifies this part uniquely within the Email.  This is scoped to

     

       1926
       1926
       +
             the "emailId" and has no meaning outside of the JMAP Email object

     

       1927
       1927
       +
             representation.  This is null if, and only if, the part is of type

     

       1928
       1928
       +
             "multipart/*".

     

       1929
       1929
       +
       

     

       1930
       1930
       +
          o  blobId: "Id|null"

     

       1931
       1931
       +
       

     

       1932
       1932
       +
             The id representing the raw octets of the contents of the part,

     

       1933
       1933
       +
             after decoding any known Content-Transfer-Encoding (as defined in

     

       1934
       1934
       +
             [RFC2045]), or null if, and only if, the part is of type

     

       1935
       1935
       +
             "multipart/*".  Note that two parts may be transfer-encoded

     

       1936
       1936
       +
             differently but have the same blob id if their decoded octets are

     

       1937
       1937
       +
             identical and the server is using a secure hash of the data for

     

       1938
       1938
       +
             the blob id.  If the transfer encoding is unknown, it is treated

     

       1939
       1939
       +
             as though it had no transfer encoding.

     

       1940
       1940
       +
       

     

       1941
       1941
       +
          o  size: "UnsignedInt"

     

       1942
       1942
       +
       

     

       1943
       1943
       +
             The size, in octets, of the raw data after content transfer

     

       1944
       1944
       +
             decoding (as referenced by the "blobId", i.e., the number of

     

       1945
       1945
       +
             octets in the file the user would download).

     

       1946
       1946
       +
       

     

       1947
       1947
       +
          o  headers: "EmailHeader[]"

     

       1948
       1948
       +
       

     

       1949
       1949
       +
             This is a list of all header fields in the part, in the order they

     

       1950
       1950
       +
             appear in the message.  The values are in Raw form.

     

       1951
       1951
       +
       

     

       1952
       1952
       +
          o  name: "String|null"

     

       1953
       1953
       +
       

     

       1954
       1954
       +
             This is the decoded "filename" parameter of the Content-

     

       1955
       1955
       +
             Disposition header field per [RFC2231], or (for compatibility with

     

       1956
       1956
       +
             existing systems) if not present, then it's the decoded "name"

     

       1957
       1957
       +
             parameter of the Content-Type header field per [RFC2047].

     

       1958
       1958
       +
       

     

       1959
       1959
       +
       

     

       1960
       1960
       +
       

     

       1961
       1961
       +
       

     

       1962
       1962
       +
       Jenkins & Newman             Standards Track                   [Page 35]

     

       1963
       1963
       +
       

     

       1964
       1964
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       1965
       1965
       +
       

     

       1966
       1966
       +
       

     

       1967
       1967
       +
          o  type: "String"

     

       1968
       1968
       +
       

     

       1969
       1969
       +
             The value of the Content-Type header field of the part, if

     

       1970
       1970
       +
             present; otherwise, the implicit type as per the MIME standard

     

       1971
       1971
       +
             ("text/plain" or "message/rfc822" if inside a "multipart/digest").

     

       1972
       1972
       +
             CFWS is removed and any parameters are stripped.

     

       1973
       1973
       +
       

     

       1974
       1974
       +
          o  charset: "String|null"

     

       1975
       1975
       +
       

     

       1976
       1976
       +
             The value of the charset parameter of the Content-Type header

     

       1977
       1977
       +
             field, if present, or null if the header field is present but not

     

       1978
       1978
       +
             of type "text/*".  If there is no Content-Type header field, or it

     

       1979
       1979
       +
             exists and is of type "text/*" but has no charset parameter, this

     

       1980
       1980
       +
             is the implicit charset as per the MIME standard: "us-ascii".

     

       1981
       1981
       +
       

     

       1982
       1982
       +
          o  disposition: "String|null"

     

       1983
       1983
       +
       

     

       1984
       1984
       +
             The value of the Content-Disposition header field of the part, if

     

       1985
       1985
       +
             present; otherwise, it's null.  CFWS is removed and any parameters

     

       1986
       1986
       +
             are stripped.

     

       1987
       1987
       +
       

     

       1988
       1988
       +
          o  cid: "String|null"

     

       1989
       1989
       +
       

     

       1990
       1990
       +
             The value of the Content-Id header field of the part, if present;

     

       1991
       1991
       +
             otherwise, it's null.  CFWS and surrounding angle brackets ("<>")

     

       1992
       1992
       +
             are removed.  This may be used to reference the content from

     

       1993
       1993
       +
             within a "text/html" body part [HTML] using the "cid:" protocol,

     

       1994
       1994
       +
             as defined in [RFC2392].

     

       1995
       1995
       +
       

     

       1996
       1996
       +
          o  language: "String[]|null"

     

       1997
       1997
       +
       

     

       1998
       1998
       +
             The list of language tags, as defined in [RFC3282], in the

     

       1999
       1999
       +
             Content-Language header field of the part, if present.

     

       2000
       2000
       +
       

     

       2001
       2001
       +
          o  location: "String|null"

     

       2002
       2002
       +
       

     

       2003
       2003
       +
             The URI, as defined in [RFC2557], in the Content-Location header

     

       2004
       2004
       +
             field of the part, if present.

     

       2005
       2005
       +
       

     

       2006
       2006
       +
          o  subParts: "EmailBodyPart[]|null"

     

       2007
       2007
       +
       

     

       2008
       2008
       +
             If the type is "multipart/*", this contains the body parts of each

     

       2009
       2009
       +
             child.

     

       2010
       2010
       +
       

     

       2011
       2011
       +
          In addition, the client may request/send EmailBodyPart properties

     

       2012
       2012
       +
          representing individual header fields, following the same syntax and

     

       2013
       2013
       +
          semantics as for the Email object, e.g., "header:Content-Type".

     

       2014
       2014
       +
       

     

       2015
       2015
       +
       

     

       2016
       2016
       +
       

     

       2017
       2017
       +
       

     

       2018
       2018
       +
       Jenkins & Newman             Standards Track                   [Page 36]

     

       2019
       2019
       +
       

     

       2020
       2020
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2021
       2021
       +
       

     

       2022
       2022
       +
       

     

       2023
       2023
       +
          The following Email properties are specified for access to the body

     

       2024
       2024
       +
          data of the message:

     

       2025
       2025
       +
       

     

       2026
       2026
       +
          o  bodyStructure: "EmailBodyPart" (immutable)

     

       2027
       2027
       +
       

     

       2028
       2028
       +
             This is the full MIME structure of the message body, without

     

       2029
       2029
       +
             recursing into "message/rfc822" or "message/global" parts.  Note

     

       2030
       2030
       +
             that EmailBodyParts may have subParts if they are of type

     

       2031
       2031
       +
             "multipart/*".

     

       2032
       2032
       +
       

     

       2033
       2033
       +
          o  bodyValues: "String[EmailBodyValue]" (immutable)

     

       2034
       2034
       +
       

     

       2035
       2035
       +
             This is a map of "partId" to an EmailBodyValue object for none,

     

       2036
       2036
       +
             some, or all "text/*" parts.  Which parts are included and whether

     

       2037
       2037
       +
             the value is truncated is determined by various arguments to

     

       2038
       2038
       +
             "Email/get" and "Email/parse".  An *EmailBodyValue* object has the

     

       2039
       2039
       +
             following properties:

     

       2040
       2040
       +
       

     

       2041
       2041
       +
             *  value: "String"

     

       2042
       2042
       +
       

     

       2043
       2043
       +
                The value of the body part after decoding Content-Transfer-

     

       2044
       2044
       +
                Encoding and the Content-Type charset, if both known to the

     

       2045
       2045
       +
                server, and with any CRLF replaced with a single LF.  The

     

       2046
       2046
       +
                server MAY use heuristics to determine the charset to use for

     

       2047
       2047
       +
                decoding if the charset is unknown, no charset is given, or it

     

       2048
       2048
       +
                believes the charset given is incorrect.  Decoding is best

     

       2049
       2049
       +
                effort; the server SHOULD insert the unicode replacement

     

       2050
       2050
       +
                character (U+FFFD) and continue when a malformed section is

     

       2051
       2051
       +
                encountered.

     

       2052
       2052
       +
       

     

       2053
       2053
       +
                Note that due to the charset decoding and line ending

     

       2054
       2054
       +
                normalisation, the length of this string will probably not be

     

       2055
       2055
       +
                exactly the same as the "size" property on the corresponding

     

       2056
       2056
       +
                EmailBodyPart.

     

       2057
       2057
       +
       

     

       2058
       2058
       +
             *  isEncodingProblem: "Boolean" (default: false)

     

       2059
       2059
       +
       

     

       2060
       2060
       +
                This is true if malformed sections were found while decoding

     

       2061
       2061
       +
                the charset, the charset was unknown, or the content-transfer-

     

       2062
       2062
       +
                encoding was unknown.

     

       2063
       2063
       +
       

     

       2064
       2064
       +
             *  isTruncated: "Boolean" (default: false)

     

       2065
       2065
       +
       

     

       2066
       2066
       +
                This is true if the "value" has been truncated.

     

       2067
       2067
       +
       

     

       2068
       2068
       +
             See the Security Considerations section for issues related to

     

       2069
       2069
       +
             truncation and heuristic determination of the content-type and

     

       2070
       2070
       +
             charset.

     

       2071
       2071
       +
       

     

       2072
       2072
       +
       

     

       2073
       2073
       +
       

     

       2074
       2074
       +
       Jenkins & Newman             Standards Track                   [Page 37]

     

       2075
       2075
       +
       

     

       2076
       2076
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2077
       2077
       +
       

     

       2078
       2078
       +
       

     

       2079
       2079
       +
          o  textBody: "EmailBodyPart[]" (immutable)

     

       2080
       2080
       +
       

     

       2081
       2081
       +
             A list of "text/plain", "text/html", "image/*", "audio/*", and/or

     

       2082
       2082
       +
             "video/*" parts to display (sequentially) as the message body,

     

       2083
       2083
       +
             with a preference for "text/plain" when alternative versions are

     

       2084
       2084
       +
             available.

     

       2085
       2085
       +
       

     

       2086
       2086
       +
          o  htmlBody: "EmailBodyPart[]" (immutable)

     

       2087
       2087
       +
       

     

       2088
       2088
       +
             A list of "text/plain", "text/html", "image/*", "audio/*", and/or

     

       2089
       2089
       +
             "video/*" parts to display (sequentially) as the message body,

     

       2090
       2090
       +
             with a preference for "text/html" when alternative versions are

     

       2091
       2091
       +
             available.

     

       2092
       2092
       +
       

     

       2093
       2093
       +
          o  attachments: "EmailBodyPart[]" (immutable)

     

       2094
       2094
       +
       

     

       2095
       2095
       +
             A list, traversing depth-first, of all parts in "bodyStructure"

     

       2096
       2096
       +
             that satisfy either of the following conditions:

     

       2097
       2097
       +
       

     

       2098
       2098
       +
             *  not of type "multipart/*" and not included in "textBody" or

     

       2099
       2099
       +
                "htmlBody"

     

       2100
       2100
       +
       

     

       2101
       2101
       +
             *  of type "image/*", "audio/*", or "video/*" and not in both

     

       2102
       2102
       +
                "textBody" and "htmlBody"

     

       2103
       2103
       +
       

     

       2104
       2104
       +
             None of these parts include subParts, including "message/*" types.

     

       2105
       2105
       +
             Attached messages may be fetched using the "Email/parse" method

     

       2106
       2106
       +
             and the "blobId".

     

       2107
       2107
       +
       

     

       2108
       2108
       +
             Note that a "text/html" body part [HTML] may reference image parts

     

       2109
       2109
       +
             in attachments by using "cid:" links to reference the Content-Id,

     

       2110
       2110
       +
             as defined in [RFC2392], or by referencing the Content-Location.

     

       2111
       2111
       +
       

     

       2112
       2112
       +
          o  hasAttachment: "Boolean" (immutable; server-set)

     

       2113
       2113
       +
       

     

       2114
       2114
       +
             This is true if there are one or more parts in the message that a

     

       2115
       2115
       +
             client UI should offer as downloadable.  A server SHOULD set

     

       2116
       2116
       +
             hasAttachment to true if the "attachments" list contains at least

     

       2117
       2117
       +
             one item that does not have "Content-Disposition: inline".  The

     

       2118
       2118
       +
             server MAY ignore parts in this list that are processed

     

       2119
       2119
       +
             automatically in some way or are referenced as embedded images in

     

       2120
       2120
       +
             one of the "text/html" parts of the message.

     

       2121
       2121
       +
       

     

       2122
       2122
       +
             The server MAY set hasAttachment based on implementation-defined

     

       2123
       2123
       +
             or site-configurable heuristics.

     

       2124
       2124
       +
       

     

       2125
       2125
       +
       

     

       2126
       2126
       +
       

     

       2127
       2127
       +
       

     

       2128
       2128
       +
       

     

       2129
       2129
       +
       

     

       2130
       2130
       +
       Jenkins & Newman             Standards Track                   [Page 38]

     

       2131
       2131
       +
       

     

       2132
       2132
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2133
       2133
       +
       

     

       2134
       2134
       +
       

     

       2135
       2135
       +
          o  preview: "String" (immutable; server-set)

     

       2136
       2136
       +
       

     

       2137
       2137
       +
             A plaintext fragment of the message body.  This is intended to be

     

       2138
       2138
       +
             shown as a preview line when listing messages in the mail store

     

       2139
       2139
       +
             and may be truncated when shown.  The server may choose which part

     

       2140
       2140
       +
             of the message to include in the preview; skipping quoted sections

     

       2141
       2141
       +
             and salutations and collapsing white space can result in a more

     

       2142
       2142
       +
             useful preview.

     

       2143
       2143
       +
       

     

       2144
       2144
       +
             This MUST NOT be more than 256 characters in length.

     

       2145
       2145
       +
       

     

       2146
       2146
       +
             As this is derived from the message content by the server, and the

     

       2147
       2147
       +
             algorithm for doing so could change over time, fetching this for

     

       2148
       2148
       +
             an Email a second time MAY return a different result.  However,

     

       2149
       2149
       +
             the previous value is not considered incorrect, and the change

     

       2150
       2150
       +
             SHOULD NOT cause the Email object to be considered as changed by

     

       2151
       2151
       +
             the server.

     

       2152
       2152
       +
       

     

       2153
       2153
       +
          The exact algorithm for decomposing bodyStructure into textBody,

     

       2154
       2154
       +
          htmlBody, and attachments part lists is not mandated, as this is a

     

       2155
       2155
       +
          quality-of-service implementation issue and likely to require

     

       2156
       2156
       +
          workarounds for malformed content discovered over time.  However, the

     

       2157
       2157
       +
          following algorithm (expressed here in JavaScript) is suggested as a

     

       2158
       2158
       +
          starting point, based on real-world experience:

     

       2159
       2159
       +
       

     

       2160
       2160
       +
         function isInlineMediaType ( type ) {

     

       2161
       2161
       +
           return type.startsWith( 'image/' ) ||

     

       2162
       2162
       +
                  type.startsWith( 'audio/' ) ||

     

       2163
       2163
       +
                  type.startsWith( 'video/' );

     

       2164
       2164
       +
         }

     

       2165
       2165
       +
       

     

       2166
       2166
       +
         function parseStructure ( parts, multipartType, inAlternative,

     

       2167
       2167
       +
                 htmlBody, textBody, attachments ) {

     

       2168
       2168
       +
       

     

       2169
       2169
       +
             // For multipartType == alternative

     

       2170
       2170
       +
             let textLength = textBody ? textBody.length : -1;

     

       2171
       2171
       +
             let htmlLength = htmlBody ? htmlBody.length : -1;

     

       2172
       2172
       +
       

     

       2173
       2173
       +
             for ( let i = 0; i < parts.length; i += 1 ) {

     

       2174
       2174
       +
                 let part = parts[i];

     

       2175
       2175
       +
                 let isMultipart = part.type.startsWith( 'multipart/' );

     

       2176
       2176
       +
                 // Is this a body part rather than an attachment

     

       2177
       2177
       +
                 let isInline = part.disposition != "attachment" &&

     

       2178
       2178
       +
                     // Must be one of the allowed body types

     

       2179
       2179
       +
                     ( part.type == "text/plain" ||

     

       2180
       2180
       +
                       part.type == "text/html" ||

     

       2181
       2181
       +
                       isInlineMediaType( part.type ) ) &&

     

       2182
       2182
       +
       

     

       2183
       2183
       +
       

     

       2184
       2184
       +
       

     

       2185
       2185
       +
       

     

       2186
       2186
       +
       Jenkins & Newman             Standards Track                   [Page 39]

     

       2187
       2187
       +
       

     

       2188
       2188
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2189
       2189
       +
       

     

       2190
       2190
       +
       

     

       2191
       2191
       +
                     // If multipart/related, only the first part can be inline

     

       2192
       2192
       +
                     // If a text part with a filename, and not the first item

     

       2193
       2193
       +
                     // in the multipart, assume it is an attachment

     

       2194
       2194
       +
                     ( i === 0 ||

     

       2195
       2195
       +
                       ( multipartType != "related" &&

     

       2196
       2196
       +
                         ( isInlineMediaType( part.type ) || !part.name ) ) );

     

       2197
       2197
       +
       

     

       2198
       2198
       +
                 if ( isMultipart ) {

     

       2199
       2199
       +
                     let subMultiType = part.type.split( '/' )[1];

     

       2200
       2200
       +
                     parseStructure( part.subParts, subMultiType,

     

       2201
       2201
       +
                         inAlternative || ( subMultiType == 'alternative' ),

     

       2202
       2202
       +
                         htmlBody, textBody, attachments );

     

       2203
       2203
       +
                 } else if ( isInline ) {

     

       2204
       2204
       +
                     if ( multipartType == 'alternative' ) {

     

       2205
       2205
       +
                         switch ( part.type ) {

     

       2206
       2206
       +
                         case 'text/plain':

     

       2207
       2207
       +
                             textBody.push( part );

     

       2208
       2208
       +
                             break;

     

       2209
       2209
       +
                         case 'text/html':

     

       2210
       2210
       +
                             htmlBody.push( part );

     

       2211
       2211
       +
                             break;

     

       2212
       2212
       +
                         default:

     

       2213
       2213
       +
                             attachments.push( part );

     

       2214
       2214
       +
                             break;

     

       2215
       2215
       +
                         }

     

       2216
       2216
       +
                         continue;

     

       2217
       2217
       +
                     } else if ( inAlternative ) {

     

       2218
       2218
       +
                         if ( part.type == 'text/plain' ) {

     

       2219
       2219
       +
                             htmlBody = null;

     

       2220
       2220
       +
                         }

     

       2221
       2221
       +
                         if ( part.type == 'text/html' ) {

     

       2222
       2222
       +
                             textBody = null;

     

       2223
       2223
       +
                         }

     

       2224
       2224
       +
                     }

     

       2225
       2225
       +
                     if ( textBody ) {

     

       2226
       2226
       +
                         textBody.push( part );

     

       2227
       2227
       +
                     }

     

       2228
       2228
       +
                     if ( htmlBody ) {

     

       2229
       2229
       +
                         htmlBody.push( part );

     

       2230
       2230
       +
                     }

     

       2231
       2231
       +
                     if ( ( !textBody || !htmlBody ) &&

     

       2232
       2232
       +
                             isInlineMediaType( part.type ) ) {

     

       2233
       2233
       +
                         attachments.push( part );

     

       2234
       2234
       +
                     }

     

       2235
       2235
       +
                 } else {

     

       2236
       2236
       +
                     attachments.push( part );

     

       2237
       2237
       +
                 }

     

       2238
       2238
       +
             }

     

       2239
       2239
       +
       

     

       2240
       2240
       +
       

     

       2241
       2241
       +
       

     

       2242
       2242
       +
       Jenkins & Newman             Standards Track                   [Page 40]

     

       2243
       2243
       +
       

     

       2244
       2244
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2245
       2245
       +
       

     

       2246
       2246
       +
       

     

       2247
       2247
       +
             if ( multipartType == 'alternative' && textBody && htmlBody ) {

     

       2248
       2248
       +
                 // Found HTML part only

     

       2249
       2249
       +
                 if ( textLength == textBody.length &&

     

       2250
       2250
       +
                         htmlLength != htmlBody.length ) {

     

       2251
       2251
       +
                     for ( let i = htmlLength; i < htmlBody.length; i += 1 ) {

     

       2252
       2252
       +
                         textBody.push( htmlBody[i] );

     

       2253
       2253
       +
                     }

     

       2254
       2254
       +
                 }

     

       2255
       2255
       +
                 // Found plaintext part only

     

       2256
       2256
       +
                 if ( htmlLength == htmlBody.length &&

     

       2257
       2257
       +
                         textLength != textBody.length ) {

     

       2258
       2258
       +
                     for ( let i = textLength; i < textBody.length; i += 1 ) {

     

       2259
       2259
       +
                         htmlBody.push( textBody[i] );

     

       2260
       2260
       +
                     }

     

       2261
       2261
       +
                 }

     

       2262
       2262
       +
             }

     

       2263
       2263
       +
         }

     

       2264
       2264
       +
       

     

       2265
       2265
       +
         // Usage:

     

       2266
       2266
       +
         let htmlBody = [];

     

       2267
       2267
       +
         let textBody = [];

     

       2268
       2268
       +
         let attachments = [];

     

       2269
       2269
       +
       

     

       2270
       2270
       +
         parseStructure( [ bodyStructure ], 'mixed', false,

     

       2271
       2271
       +
             htmlBody, textBody, attachments );

     

       2272
       2272
       +
       

     

       2273
       2273
       +
          For instance, consider a message with both text and HTML versions

     

       2274
       2274
       +
          that has gone through a list software manager that attaches a header

     

       2275
       2275
       +
          and footer.  It might have a MIME structure something like:

     

       2276
       2276
       +
       

     

       2277
       2277
       +
                   multipart/mixed

     

       2278
       2278
       +
                     text/plain, content-disposition=inline - A

     

       2279
       2279
       +
                     multipart/mixed

     

       2280
       2280
       +
                       multipart/alternative

     

       2281
       2281
       +
                         multipart/mixed

     

       2282
       2282
       +
                           text/plain, content-disposition=inline - B

     

       2283
       2283
       +
                           image/jpeg, content-disposition=inline - C

     

       2284
       2284
       +
                           text/plain, content-disposition=inline - D

     

       2285
       2285
       +
                         multipart/related

     

       2286
       2286
       +
                           text/html - E

     

       2287
       2287
       +
                           image/jpeg - F

     

       2288
       2288
       +
                       image/jpeg, content-disposition=attachment - G

     

       2289
       2289
       +
                       application/x-excel - H

     

       2290
       2290
       +
                       message/rfc822 - J

     

       2291
       2291
       +
                     text/plain, content-disposition=inline - K

     

       2292
       2292
       +
       

     

       2293
       2293
       +
       

     

       2294
       2294
       +
       

     

       2295
       2295
       +
       

     

       2296
       2296
       +
       

     

       2297
       2297
       +
       

     

       2298
       2298
       +
       Jenkins & Newman             Standards Track                   [Page 41]

     

       2299
       2299
       +
       

     

       2300
       2300
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2301
       2301
       +
       

     

       2302
       2302
       +
       

     

       2303
       2303
       +
          In this case, the above algorithm would decompose this to:

     

       2304
       2304
       +
       

     

       2305
       2305
       +
                            textBody => [ A, B, C, D, K ]

     

       2306
       2306
       +
                            htmlBody => [ A, E, K ]

     

       2307
       2307
       +
                            attachments => [ C, F, G, H, J ]

     

       2308
       2308
       +
       

     

       2309
       2309
       +
       4.2.  Email/get

     

       2310
       2310
       +
       

     

       2311
       2311
       +
          This is a standard "/get" method as described in [RFC8620],

     

       2312
       2312
       +
          Section 5.1 with the following additional request arguments:

     

       2313
       2313
       +
       

     

       2314
       2314
       +
          o  bodyProperties: "String[]"

     

       2315
       2315
       +
       

     

       2316
       2316
       +
             A list of properties to fetch for each EmailBodyPart returned.  If

     

       2317
       2317
       +
             omitted, this defaults to:

     

       2318
       2318
       +
       

     

       2319
       2319
       +
                [ "partId", "blobId", "size", "name", "type", "charset",

     

       2320
       2320
       +
                  "disposition", "cid", "language", "location" ]

     

       2321
       2321
       +
       

     

       2322
       2322
       +
          o  fetchTextBodyValues: "Boolean" (default: false)

     

       2323
       2323
       +
       

     

       2324
       2324
       +
             If true, the "bodyValues" property includes any "text/*" part in

     

       2325
       2325
       +
             the "textBody" property.

     

       2326
       2326
       +
       

     

       2327
       2327
       +
          o  fetchHTMLBodyValues: "Boolean" (default: false)

     

       2328
       2328
       +
       

     

       2329
       2329
       +
             If true, the "bodyValues" property includes any "text/*" part in

     

       2330
       2330
       +
             the "htmlBody" property.

     

       2331
       2331
       +
       

     

       2332
       2332
       +
          o  fetchAllBodyValues: "Boolean" (default: false)

     

       2333
       2333
       +
       

     

       2334
       2334
       +
             If true, the "bodyValues" property includes any "text/*" part in

     

       2335
       2335
       +
             the "bodyStructure" property.

     

       2336
       2336
       +
       

     

       2337
       2337
       +
          o  maxBodyValueBytes: "UnsignedInt" (default: 0)

     

       2338
       2338
       +
       

     

       2339
       2339
       +
             If greater than zero, the "value" property of any EmailBodyValue

     

       2340
       2340
       +
             object returned in "bodyValues" MUST be truncated if necessary so

     

       2341
       2341
       +
             it does not exceed this number of octets in size.  If 0 (the

     

       2342
       2342
       +
             default), no truncation occurs.

     

       2343
       2343
       +
       

     

       2344
       2344
       +
             The server MUST ensure the truncation results in valid UTF-8 and

     

       2345
       2345
       +
             does not occur mid-codepoint.  If the part is of type "text/html",

     

       2346
       2346
       +
             the server SHOULD NOT truncate inside an HTML tag, e.g., in the

     

       2347
       2347
       +
             middle of "<a href="https://example.com">".  There is no

     

       2348
       2348
       +
             requirement for the truncated form to be a balanced tree or valid

     

       2349
       2349
       +
             HTML (indeed, the original source may well be neither of these

     

       2350
       2350
       +
             things).

     

       2351
       2351
       +
       

     

       2352
       2352
       +
       

     

       2353
       2353
       +
       

     

       2354
       2354
       +
       Jenkins & Newman             Standards Track                   [Page 42]

     

       2355
       2355
       +
       

     

       2356
       2356
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2357
       2357
       +
       

     

       2358
       2358
       +
       

     

       2359
       2359
       +
          If the standard "properties" argument is omitted or null, the

     

       2360
       2360
       +
          following default MUST be used instead of "all" properties:

     

       2361
       2361
       +
       

     

       2362
       2362
       +
        [ "id", "blobId", "threadId", "mailboxIds", "keywords", "size",

     

       2363
       2363
       +
        "receivedAt", "messageId", "inReplyTo", "references", "sender", "from",

     

       2364
       2364
       +
        "to", "cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment",

     

       2365
       2365
       +
        "preview", "bodyValues", "textBody", "htmlBody", "attachments" ]

     

       2366
       2366
       +
       

     

       2367
       2367
       +
          The following properties are expected to be fast to fetch in a

     

       2368
       2368
       +
          quality implementation:

     

       2369
       2369
       +
       

     

       2370
       2370
       +
          o  id

     

       2371
       2371
       +
       

     

       2372
       2372
       +
          o  blobId

     

       2373
       2373
       +
       

     

       2374
       2374
       +
          o  threadId

     

       2375
       2375
       +
       

     

       2376
       2376
       +
          o  mailboxIds

     

       2377
       2377
       +
       

     

       2378
       2378
       +
          o  keywords

     

       2379
       2379
       +
       

     

       2380
       2380
       +
          o  size

     

       2381
       2381
       +
       

     

       2382
       2382
       +
          o  receivedAt

     

       2383
       2383
       +
       

     

       2384
       2384
       +
          o  messageId

     

       2385
       2385
       +
       

     

       2386
       2386
       +
          o  inReplyTo

     

       2387
       2387
       +
       

     

       2388
       2388
       +
          o  sender

     

       2389
       2389
       +
       

     

       2390
       2390
       +
          o  from

     

       2391
       2391
       +
       

     

       2392
       2392
       +
          o  to

     

       2393
       2393
       +
       

     

       2394
       2394
       +
          o  cc

     

       2395
       2395
       +
       

     

       2396
       2396
       +
          o  bcc

     

       2397
       2397
       +
       

     

       2398
       2398
       +
          o  replyTo

     

       2399
       2399
       +
       

     

       2400
       2400
       +
          o  subject

     

       2401
       2401
       +
       

     

       2402
       2402
       +
          o  sentAt

     

       2403
       2403
       +
       

     

       2404
       2404
       +
          o  hasAttachment

     

       2405
       2405
       +
       

     

       2406
       2406
       +
          o  preview

     

       2407
       2407
       +
       

     

       2408
       2408
       +
       

     

       2409
       2409
       +
       

     

       2410
       2410
       +
       Jenkins & Newman             Standards Track                   [Page 43]

     

       2411
       2411
       +
       

     

       2412
       2412
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2413
       2413
       +
       

     

       2414
       2414
       +
       

     

       2415
       2415
       +
          Clients SHOULD take care when fetching any other properties, as there

     

       2416
       2416
       +
          may be significantly longer latency in fetching and returning the

     

       2417
       2417
       +
          data.

     

       2418
       2418
       +
       

     

       2419
       2419
       +
          As specified above, parsed forms of headers may only be used on

     

       2420
       2420
       +
          appropriate header fields.  Attempting to fetch a form that is

     

       2421
       2421
       +
          forbidden (e.g., "header:From:asDate") MUST result in the method call

     

       2422
       2422
       +
          being rejected with an "invalidArguments" error.

     

       2423
       2423
       +
       

     

       2424
       2424
       +
          Where a specific header field is requested as a property, the

     

       2425
       2425
       +
          capitalization of the property name in the response MUST be identical

     

       2426
       2426
       +
          to that used in the request.

     

       2427
       2427
       +
       

     

       2428
       2428
       +
       4.2.1.  Example

     

       2429
       2429
       +
       

     

       2430
       2430
       +
          Request:

     

       2431
       2431
       +
       

     

       2432
       2432
       +
             [[ "Email/get", {

     

       2433
       2433
       +
               "ids": [ "f123u456", "f123u457" ],

     

       2434
       2434
       +
               "properties": [ "threadId", "mailboxIds", "from", "subject",

     

       2435
       2435
       +
                 "receivedAt", "header:List-POST:asURLs",

     

       2436
       2436
       +
                 "htmlBody", "bodyValues" ],

     

       2437
       2437
       +
               "bodyProperties": [ "partId", "blobId", "size", "type" ],

     

       2438
       2438
       +
               "fetchHTMLBodyValues": true,

     

       2439
       2439
       +
               "maxBodyValueBytes": 256

     

       2440
       2440
       +
             }, "#1" ]]

     

       2441
       2441
       +
       

     

       2442
       2442
       +
          and response:

     

       2443
       2443
       +
       

     

       2444
       2444
       +
          [[ "Email/get", {

     

       2445
       2445
       +
            "accountId": "abc",

     

       2446
       2446
       +
            "state": "41234123231",

     

       2447
       2447
       +
            "list": [

     

       2448
       2448
       +
              {

     

       2449
       2449
       +
                "id": "f123u457",

     

       2450
       2450
       +
                "threadId": "ef1314a",

     

       2451
       2451
       +
                "mailboxIds": { "f123": true },

     

       2452
       2452
       +
                "from": [{ "name": "Joe Bloggs", "email": "joe@example.com" }],

     

       2453
       2453
       +
                "subject": "Dinner on Thursday?",

     

       2454
       2454
       +
                "receivedAt": "2013-10-13T14:12:00Z",

     

       2455
       2455
       +
                "header:List-POST:asURLs": [

     

       2456
       2456
       +
                  "mailto:partytime@lists.example.com"

     

       2457
       2457
       +
                ],

     

       2458
       2458
       +
                "htmlBody": [{

     

       2459
       2459
       +
                  "partId": "1",

     

       2460
       2460
       +
                  "blobId": "B841623871",

     

       2461
       2461
       +
                  "size": 283331,

     

       2462
       2462
       +
                  "type": "text/html"

     

       2463
       2463
       +
       

     

       2464
       2464
       +
       

     

       2465
       2465
       +
       

     

       2466
       2466
       +
       Jenkins & Newman             Standards Track                   [Page 44]

     

       2467
       2467
       +
       

     

       2468
       2468
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2469
       2469
       +
       

     

       2470
       2470
       +
       

     

       2471
       2471
       +
                }, {

     

       2472
       2472
       +
                  "partId": "2",

     

       2473
       2473
       +
                  "blobId": "B319437193",

     

       2474
       2474
       +
                  "size": 10343,

     

       2475
       2475
       +
                  "type": "text/plain"

     

       2476
       2476
       +
                }],

     

       2477
       2477
       +
                "bodyValues": {

     

       2478
       2478
       +
                  "1": {

     

       2479
       2479
       +
                    "isEncodingProblem": false,

     

       2480
       2480
       +
                    "isTruncated": true,

     

       2481
       2481
       +
                    "value": "<html><body><p>Hello ..."

     

       2482
       2482
       +
                  },

     

       2483
       2483
       +
                  "2": {

     

       2484
       2484
       +
                    "isEncodingProblem": false,

     

       2485
       2485
       +
                    "isTruncated": false,

     

       2486
       2486
       +
                    "value": "-- Sent by your friendly mailing list ..."

     

       2487
       2487
       +
                  }

     

       2488
       2488
       +
                }

     

       2489
       2489
       +
              }

     

       2490
       2490
       +
            ],

     

       2491
       2491
       +
            "notFound": [ "f123u456" ]

     

       2492
       2492
       +
          }, "#1" ]]

     

       2493
       2493
       +
       

     

       2494
       2494
       +
       4.3.  Email/changes

     

       2495
       2495
       +
       

     

       2496
       2496
       +
          This is a standard "/changes" method as described in [RFC8620],

     

       2497
       2497
       +
          Section 5.2.  If generating intermediate states for a large set of

     

       2498
       2498
       +
          changes, it is recommended that newer changes be returned first, as

     

       2499
       2499
       +
          these are generally of more interest to users.

     

       2500
       2500
       +
       

     

       2501
       2501
       +
       4.4.  Email/query

     

       2502
       2502
       +
       

     

       2503
       2503
       +
          This is a standard "/query" method as described in [RFC8620],

     

       2504
       2504
       +
          Section 5.5 but with the following additional request arguments:

     

       2505
       2505
       +
       

     

       2506
       2506
       +
          o  collapseThreads: "Boolean" (default: false)

     

       2507
       2507
       +
       

     

       2508
       2508
       +
             If true, Emails in the same Thread as a previous Email in the list

     

       2509
       2509
       +
             (given the filter and sort order) will be removed from the list.

     

       2510
       2510
       +
             This means only one Email at most will be included in the list for

     

       2511
       2511
       +
             any given Thread.

     

       2512
       2512
       +
       

     

       2513
       2513
       +
          In quality implementations, the query "total" property is expected to

     

       2514
       2514
       +
          be fast to calculate when the filter consists solely of a single

     

       2515
       2515
       +
          "inMailbox" property, as it is the same as the totalEmails or

     

       2516
       2516
       +
          totalThreads properties (depending on whether collapseThreads is

     

       2517
       2517
       +
          true) of the associated Mailbox object.

     

       2518
       2518
       +
       

     

       2519
       2519
       +
       

     

       2520
       2520
       +
       

     

       2521
       2521
       +
       

     

       2522
       2522
       +
       Jenkins & Newman             Standards Track                   [Page 45]

     

       2523
       2523
       +
       

     

       2524
       2524
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2525
       2525
       +
       

     

       2526
       2526
       +
       

     

       2527
       2527
       +
       4.4.1.  Filtering

     

       2528
       2528
       +
       

     

       2529
       2529
       +
          A *FilterCondition* object has the following properties, any of which

     

       2530
       2530
       +
          may be omitted:

     

       2531
       2531
       +
       

     

       2532
       2532
       +
          o  inMailbox: "Id"

     

       2533
       2533
       +
       

     

       2534
       2534
       +
             A Mailbox id.  An Email must be in this Mailbox to match the

     

       2535
       2535
       +
             condition.

     

       2536
       2536
       +
       

     

       2537
       2537
       +
          o  inMailboxOtherThan: "Id[]"

     

       2538
       2538
       +
       

     

       2539
       2539
       +
             A list of Mailbox ids.  An Email must be in at least one Mailbox

     

       2540
       2540
       +
             not in this list to match the condition.  This is to allow

     

       2541
       2541
       +
             messages solely in trash/spam to be easily excluded from a search.

     

       2542
       2542
       +
       

     

       2543
       2543
       +
          o  before: "UTCDate"

     

       2544
       2544
       +
       

     

       2545
       2545
       +
             The "receivedAt" date-time of the Email must be before this date-

     

       2546
       2546
       +
             time to match the condition.

     

       2547
       2547
       +
       

     

       2548
       2548
       +
          o  after: "UTCDate"

     

       2549
       2549
       +
       

     

       2550
       2550
       +
             The "receivedAt" date-time of the Email must be the same or after

     

       2551
       2551
       +
             this date-time to match the condition.

     

       2552
       2552
       +
       

     

       2553
       2553
       +
          o  minSize: "UnsignedInt"

     

       2554
       2554
       +
       

     

       2555
       2555
       +
             The "size" property of the Email must be equal to or greater than

     

       2556
       2556
       +
             this number to match the condition.

     

       2557
       2557
       +
       

     

       2558
       2558
       +
          o  maxSize: "UnsignedInt"

     

       2559
       2559
       +
       

     

       2560
       2560
       +
             The "size" property of the Email must be less than this number to

     

       2561
       2561
       +
             match the condition.

     

       2562
       2562
       +
       

     

       2563
       2563
       +
          o  allInThreadHaveKeyword: "String"

     

       2564
       2564
       +
       

     

       2565
       2565
       +
             All Emails (including this one) in the same Thread as this Email

     

       2566
       2566
       +
             must have the given keyword to match the condition.

     

       2567
       2567
       +
       

     

       2568
       2568
       +
          o  someInThreadHaveKeyword: "String"

     

       2569
       2569
       +
       

     

       2570
       2570
       +
             At least one Email (possibly this one) in the same Thread as this

     

       2571
       2571
       +
             Email must have the given keyword to match the condition.

     

       2572
       2572
       +
       

     

       2573
       2573
       +
       

     

       2574
       2574
       +
       

     

       2575
       2575
       +
       

     

       2576
       2576
       +
       

     

       2577
       2577
       +
       

     

       2578
       2578
       +
       Jenkins & Newman             Standards Track                   [Page 46]

     

       2579
       2579
       +
       

     

       2580
       2580
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2581
       2581
       +
       

     

       2582
       2582
       +
       

     

       2583
       2583
       +
          o  noneInThreadHaveKeyword: "String"

     

       2584
       2584
       +
       

     

       2585
       2585
       +
             All Emails (including this one) in the same Thread as this Email

     

       2586
       2586
       +
             must *not* have the given keyword to match the condition.

     

       2587
       2587
       +
       

     

       2588
       2588
       +
          o  hasKeyword: "String"

     

       2589
       2589
       +
       

     

       2590
       2590
       +
             This Email must have the given keyword to match the condition.

     

       2591
       2591
       +
       

     

       2592
       2592
       +
          o  notKeyword: "String"

     

       2593
       2593
       +
       

     

       2594
       2594
       +
             This Email must not have the given keyword to match the condition.

     

       2595
       2595
       +
       

     

       2596
       2596
       +
          o  hasAttachment: "Boolean"

     

       2597
       2597
       +
       

     

       2598
       2598
       +
             The "hasAttachment" property of the Email must be identical to the

     

       2599
       2599
       +
             value given to match the condition.

     

       2600
       2600
       +
       

     

       2601
       2601
       +
          o  text: "String"

     

       2602
       2602
       +
       

     

       2603
       2603
       +
             Looks for the text in Emails.  The server MUST look up text in the

     

       2604
       2604
       +
             From, To, Cc, Bcc, and Subject header fields of the message and

     

       2605
       2605
       +
             SHOULD look inside any "text/*" or other body parts that may be

     

       2606
       2606
       +
             converted to text by the server.  The server MAY extend the search

     

       2607
       2607
       +
             to any additional textual property.

     

       2608
       2608
       +
       

     

       2609
       2609
       +
          o  from: "String"

     

       2610
       2610
       +
       

     

       2611
       2611
       +
             Looks for the text in the From header field of the message.

     

       2612
       2612
       +
       

     

       2613
       2613
       +
          o  to: "String"

     

       2614
       2614
       +
       

     

       2615
       2615
       +
             Looks for the text in the To header field of the message.

     

       2616
       2616
       +
       

     

       2617
       2617
       +
          o  cc: "String"

     

       2618
       2618
       +
       

     

       2619
       2619
       +
             Looks for the text in the Cc header field of the message.

     

       2620
       2620
       +
       

     

       2621
       2621
       +
          o  bcc: "String"

     

       2622
       2622
       +
       

     

       2623
       2623
       +
             Looks for the text in the Bcc header field of the message.

     

       2624
       2624
       +
       

     

       2625
       2625
       +
          o  subject: "String"

     

       2626
       2626
       +
       

     

       2627
       2627
       +
             Looks for the text in the Subject header field of the message.

     

       2628
       2628
       +
       

     

       2629
       2629
       +
       

     

       2630
       2630
       +
       

     

       2631
       2631
       +
       

     

       2632
       2632
       +
       

     

       2633
       2633
       +
       

     

       2634
       2634
       +
       Jenkins & Newman             Standards Track                   [Page 47]

     

       2635
       2635
       +
       

     

       2636
       2636
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2637
       2637
       +
       

     

       2638
       2638
       +
       

     

       2639
       2639
       +
          o  body: "String"

     

       2640
       2640
       +
       

     

       2641
       2641
       +
             Looks for the text in one of the body parts of the message.  The

     

       2642
       2642
       +
             server MAY exclude MIME body parts with content media types other

     

       2643
       2643
       +
             than "text/*" and "message/*" from consideration in search

     

       2644
       2644
       +
             matching.  Care should be taken to match based on the text content

     

       2645
       2645
       +
             actually presented to an end user by viewers for that media type

     

       2646
       2646
       +
             or otherwise identified as appropriate for search indexing.

     

       2647
       2647
       +
             Matching document metadata uninteresting to an end user (e.g.,

     

       2648
       2648
       +
             markup tag and attribute names) is undesirable.

     

       2649
       2649
       +
       

     

       2650
       2650
       +
          o  header: "String[]"

     

       2651
       2651
       +
       

     

       2652
       2652
       +
             The array MUST contain either one or two elements.  The first

     

       2653
       2653
       +
             element is the name of the header field to match against.  The

     

       2654
       2654
       +
             second (optional) element is the text to look for in the header

     

       2655
       2655
       +
             field value.  If not supplied, the message matches simply if it

     

       2656
       2656
       +
             has a header field of the given name.

     

       2657
       2657
       +
       

     

       2658
       2658
       +
          If zero properties are specified on the FilterCondition, the

     

       2659
       2659
       +
          condition MUST always evaluate to true.  If multiple properties are

     

       2660
       2660
       +
          specified, ALL must apply for the condition to be true (it is

     

       2661
       2661
       +
          equivalent to splitting the object into one-property conditions and

     

       2662
       2662
       +
          making them all the child of an AND filter operator).

     

       2663
       2663
       +
       

     

       2664
       2664
       +
          The exact semantics for matching "String" fields is *deliberately not

     

       2665
       2665
       +
          defined* to allow for flexibility in indexing implementation, subject

     

       2666
       2666
       +
          to the following:

     

       2667
       2667
       +
       

     

       2668
       2668
       +
          o  Any syntactically correct encoded sections [RFC2047] of header

     

       2669
       2669
       +
             fields with a known encoding SHOULD be decoded before attempting

     

       2670
       2670
       +
             to match text.

     

       2671
       2671
       +
       

     

       2672
       2672
       +
          o  When searching inside a "text/html" body part, any text considered

     

       2673
       2673
       +
             markup rather than content SHOULD be ignored, including HTML tags

     

       2674
       2674
       +
             and most attributes, anything inside the "<head>" tag, Cascading

     

       2675
       2675
       +
             Style Sheets (CSS), and JavaScript.  Attribute content intended

     

       2676
       2676
       +
             for presentation to the user such as "alt" and "title" SHOULD be

     

       2677
       2677
       +
             considered in the search.

     

       2678
       2678
       +
       

     

       2679
       2679
       +
          o  Text SHOULD be matched in a case-insensitive manner.

     

       2680
       2680
       +
       

     

       2681
       2681
       +
          o  Text contained in either (but matched) single (') or double (")

     

       2682
       2682
       +
             quotes SHOULD be treated as a *phrase search*; that is, a match is

     

       2683
       2683
       +
             required for that exact word or sequence of words, excluding the

     

       2684
       2684
       +
             surrounding quotation marks.

     

       2685
       2685
       +
       

     

       2686
       2686
       +
       

     

       2687
       2687
       +
       

     

       2688
       2688
       +
       

     

       2689
       2689
       +
       

     

       2690
       2690
       +
       Jenkins & Newman             Standards Track                   [Page 48]

     

       2691
       2691
       +
       

     

       2692
       2692
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2693
       2693
       +
       

     

       2694
       2694
       +
       

     

       2695
       2695
       +
             Within a phrase, to match one of the following characters you MUST

     

       2696
       2696
       +
             escape it by prefixing it with a backslash (\):

     

       2697
       2697
       +
       

     

       2698
       2698
       +
                                           ' " \

     

       2699
       2699
       +
       

     

       2700
       2700
       +
          o  Outside of a phrase, white space SHOULD be treated as dividing

     

       2701
       2701
       +
             separate tokens that may be searched for separately but MUST all

     

       2702
       2702
       +
             be present for the Email to match the filter.

     

       2703
       2703
       +
       

     

       2704
       2704
       +
          o  Tokens (not part of a phrase) MAY be matched on a whole-word basis

     

       2705
       2705
       +
             using stemming (for example, a text search for "bus" would match

     

       2706
       2706
       +
             "buses" but not "business").

     

       2707
       2707
       +
       

     

       2708
       2708
       +
       4.4.2.  Sorting

     

       2709
       2709
       +
       

     

       2710
       2710
       +
          The following value for the "property" field on the Comparator object

     

       2711
       2711
       +
          MUST be supported for sorting:

     

       2712
       2712
       +
       

     

       2713
       2713
       +
          o  "receivedAt" - The "receivedAt" date as returned in the Email

     

       2714
       2714
       +
             object.

     

       2715
       2715
       +
       

     

       2716
       2716
       +
          The following values for the "property" field on the Comparator

     

       2717
       2717
       +
          object SHOULD be supported for sorting.  When specifying a

     

       2718
       2718
       +
          "hasKeyword", "allInThreadHaveKeyword", or "someInThreadHaveKeyword"

     

       2719
       2719
       +
          sort, the Comparator object MUST also have a "keyword" property.

     

       2720
       2720
       +
       

     

       2721
       2721
       +
          o  "size" - The "size" as returned in the Email object.

     

       2722
       2722
       +
       

     

       2723
       2723
       +
          o  "from" - This is taken to be either the "name" property or if

     

       2724
       2724
       +
             null/empty, the "email" property of the *first* EmailAddress

     

       2725
       2725
       +
             object in the Email's "from" property.  If still none, consider

     

       2726
       2726
       +
             the value to be the empty string.

     

       2727
       2727
       +
       

     

       2728
       2728
       +
          o  "to" - This is taken to be either the "name" property or if null/

     

       2729
       2729
       +
             empty, the "email" property of the *first* EmailAddress object in

     

       2730
       2730
       +
             the Email's "to" property.  If still none, consider the value to

     

       2731
       2731
       +
             be the empty string.

     

       2732
       2732
       +
       

     

       2733
       2733
       +
          o  "subject" - This is taken to be the base subject of the message,

     

       2734
       2734
       +
             as defined in Section 2.1 of [RFC5256].

     

       2735
       2735
       +
       

     

       2736
       2736
       +
          o  "sentAt" - The "sentAt" property on the Email object.

     

       2737
       2737
       +
       

     

       2738
       2738
       +
          o  "hasKeyword" - This value MUST be considered true if the Email has

     

       2739
       2739
       +
             the keyword given as an additional "keyword" property on the

     

       2740
       2740
       +
             Comparator object, or false otherwise.

     

       2741
       2741
       +
       

     

       2742
       2742
       +
       

     

       2743
       2743
       +
       

     

       2744
       2744
       +
       

     

       2745
       2745
       +
       

     

       2746
       2746
       +
       Jenkins & Newman             Standards Track                   [Page 49]

     

       2747
       2747
       +
       

     

       2748
       2748
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2749
       2749
       +
       

     

       2750
       2750
       +
       

     

       2751
       2751
       +
          o  "allInThreadHaveKeyword" - This value MUST be considered true for

     

       2752
       2752
       +
             the Email if *all* of the Emails in the same Thread have the

     

       2753
       2753
       +
             keyword given as an additional "keyword" property on the

     

       2754
       2754
       +
             Comparator object.

     

       2755
       2755
       +
       

     

       2756
       2756
       +
          o  "someInThreadHaveKeyword" - This value MUST be considered true for

     

       2757
       2757
       +
             the Email if *any* of the Emails in the same Thread have the

     

       2758
       2758
       +
             keyword given as an additional "keyword" property on the

     

       2759
       2759
       +
             Comparator object.

     

       2760
       2760
       +
       

     

       2761
       2761
       +
          The server MAY support sorting based on other properties as well.  A

     

       2762
       2762
       +
          client can discover which properties are supported by inspecting the

     

       2763
       2763
       +
          account's "capabilities" object (see Section 1.3).

     

       2764
       2764
       +
       

     

       2765
       2765
       +
          Example sort:

     

       2766
       2766
       +
       

     

       2767
       2767
       +
                        [{

     

       2768
       2768
       +
                          "property": "someInThreadHaveKeyword",

     

       2769
       2769
       +
                          "keyword": "$flagged",

     

       2770
       2770
       +
                          "isAscending": false

     

       2771
       2771
       +
                        }, {

     

       2772
       2772
       +
                          "property": "subject",

     

       2773
       2773
       +
                          "collation": "i;ascii-casemap"

     

       2774
       2774
       +
                        }, {

     

       2775
       2775
       +
                          "property": "receivedAt",

     

       2776
       2776
       +
                          "isAscending": false

     

       2777
       2777
       +
                        }]

     

       2778
       2778
       +
       

     

       2779
       2779
       +
          This would sort Emails in flagged Threads first (the Thread is

     

       2780
       2780
       +
          considered flagged if any Email within it is flagged), in subject

     

       2781
       2781
       +
          order second, and then from newest first for messages with the same

     

       2782
       2782
       +
          subject.  If two Emails have identical values for all three

     

       2783
       2783
       +
          properties, then the order is server dependent but must be stable.

     

       2784
       2784
       +
       

     

       2785
       2785
       +
       4.4.3.  Thread Collapsing

     

       2786
       2786
       +
       

     

       2787
       2787
       +
          When "collapseThreads" is true, then after filtering and sorting the

     

       2788
       2788
       +
          Email list, the list is further winnowed by removing any Emails for a

     

       2789
       2789
       +
          Thread id that has already been seen (when passing through the list

     

       2790
       2790
       +
          sequentially).  A Thread will therefore only appear *once* in the

     

       2791
       2791
       +
          result, at the position of the first Email in the list that belongs

     

       2792
       2792
       +
          to the Thread (given the current sort/filter).

     

       2793
       2793
       +
       

     

       2794
       2794
       +
       

     

       2795
       2795
       +
       

     

       2796
       2796
       +
       

     

       2797
       2797
       +
       

     

       2798
       2798
       +
       

     

       2799
       2799
       +
       

     

       2800
       2800
       +
       

     

       2801
       2801
       +
       

     

       2802
       2802
       +
       Jenkins & Newman             Standards Track                   [Page 50]

     

       2803
       2803
       +
       

     

       2804
       2804
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2805
       2805
       +
       

     

       2806
       2806
       +
       

     

       2807
       2807
       +
       4.5.  Email/queryChanges

     

       2808
       2808
       +
       

     

       2809
       2809
       +
          This is a standard "/queryChanges" method as described in [RFC8620],

     

       2810
       2810
       +
          Section 5.6 with the following additional request argument:

     

       2811
       2811
       +
       

     

       2812
       2812
       +
          o  collapseThreads: "Boolean" (default: false)

     

       2813
       2813
       +
       

     

       2814
       2814
       +
             The "collapseThreads" argument that was used with "Email/query".

     

       2815
       2815
       +
       

     

       2816
       2816
       +
       4.6.  Email/set

     

       2817
       2817
       +
       

     

       2818
       2818
       +
          This is a standard "/set" method as described in [RFC8620],

     

       2819
       2819
       +
          Section 5.3.  The "Email/set" method encompasses:

     

       2820
       2820
       +
       

     

       2821
       2821
       +
          o  Creating a draft

     

       2822
       2822
       +
       

     

       2823
       2823
       +
          o  Changing the keywords of an Email (e.g., unread/flagged status)

     

       2824
       2824
       +
       

     

       2825
       2825
       +
          o  Adding/removing an Email to/from Mailboxes (moving a message)

     

       2826
       2826
       +
       

     

       2827
       2827
       +
          o  Deleting Emails

     

       2828
       2828
       +
       

     

       2829
       2829
       +
          The format of the "keywords"/"mailboxIds" properties means that when

     

       2830
       2830
       +
          updating an Email, you can either replace the entire set of keywords/

     

       2831
       2831
       +
          Mailboxes (by setting the full value of the property) or add/remove

     

       2832
       2832
       +
          individual ones using the JMAP patch syntax (see [RFC8620],

     

       2833
       2833
       +
          Section 5.3 for the specification and Section 5.7 for an example).

     

       2834
       2834
       +
       

     

       2835
       2835
       +
          Due to the format of the Email object, when creating an Email, there

     

       2836
       2836
       +
          are a number of ways to specify the same information.  To ensure that

     

       2837
       2837
       +
          the message [RFC5322] to create is unambiguous, the following

     

       2838
       2838
       +
          constraints apply to Email objects submitted for creation:

     

       2839
       2839
       +
       

     

       2840
       2840
       +
          o  The "headers" property MUST NOT be given on either the top-level

     

       2841
       2841
       +
             Email or an EmailBodyPart -- the client must set each header field

     

       2842
       2842
       +
             as an individual property.

     

       2843
       2843
       +
       

     

       2844
       2844
       +
          o  There MUST NOT be two properties that represent the same header

     

       2845
       2845
       +
             field (e.g., "header:from" and "from") within the Email or

     

       2846
       2846
       +
             particular EmailBodyPart.

     

       2847
       2847
       +
       

     

       2848
       2848
       +
          o  Header fields MUST NOT be specified in parsed forms that are

     

       2849
       2849
       +
             forbidden for that particular field.

     

       2850
       2850
       +
       

     

       2851
       2851
       +
          o  Header fields beginning with "Content-" MUST NOT be specified on

     

       2852
       2852
       +
             the Email object, only on EmailBodyPart objects.

     

       2853
       2853
       +
       

     

       2854
       2854
       +
       

     

       2855
       2855
       +
       

     

       2856
       2856
       +
       

     

       2857
       2857
       +
       

     

       2858
       2858
       +
       Jenkins & Newman             Standards Track                   [Page 51]

     

       2859
       2859
       +
       

     

       2860
       2860
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2861
       2861
       +
       

     

       2862
       2862
       +
       

     

       2863
       2863
       +
          o  If a "bodyStructure" property is given, there MUST NOT be

     

       2864
       2864
       +
             "textBody", "htmlBody", or "attachments" properties.

     

       2865
       2865
       +
       

     

       2866
       2866
       +
          o  If given, the "bodyStructure" EmailBodyPart MUST NOT contain a

     

       2867
       2867
       +
             property representing a header field that is already defined on

     

       2868
       2868
       +
             the top-level Email object.

     

       2869
       2869
       +
       

     

       2870
       2870
       +
          o  If given, textBody MUST contain exactly one body part and it MUST

     

       2871
       2871
       +
             be of type "text/plain".

     

       2872
       2872
       +
       

     

       2873
       2873
       +
          o  If given, htmlBody MUST contain exactly one body part and it MUST

     

       2874
       2874
       +
             be of type "text/html".

     

       2875
       2875
       +
       

     

       2876
       2876
       +
          o  Within an EmailBodyPart:

     

       2877
       2877
       +
       

     

       2878
       2878
       +
             *  The client may specify a partId OR a blobId, but not both.  If

     

       2879
       2879
       +
                a partId is given, this partId MUST be present in the

     

       2880
       2880
       +
                "bodyValues" property.

     

       2881
       2881
       +
       

     

       2882
       2882
       +
             *  The "charset" property MUST be omitted if a partId is given

     

       2883
       2883
       +
                (the part's content is included in bodyValues, and the server

     

       2884
       2884
       +
                may choose any appropriate encoding).

     

       2885
       2885
       +
       

     

       2886
       2886
       +
             *  The "size" property MUST be omitted if a partId is given.  If a

     

       2887
       2887
       +
                blobId is given, it may be included but is ignored by the

     

       2888
       2888
       +
                server (the size is actually calculated from the blob content

     

       2889
       2889
       +
                itself).

     

       2890
       2890
       +
       

     

       2891
       2891
       +
             *  A Content-Transfer-Encoding header field MUST NOT be given.

     

       2892
       2892
       +
       

     

       2893
       2893
       +
          o  Within an EmailBodyValue object, isEncodingProblem and isTruncated

     

       2894
       2894
       +
             MUST be either false or omitted.

     

       2895
       2895
       +
       

     

       2896
       2896
       +
          Creation attempts that violate any of this SHOULD be rejected with an

     

       2897
       2897
       +
          "invalidProperties" error; however, a server MAY choose to modify the

     

       2898
       2898
       +
          Email (e.g., choose between conflicting headers, use a different

     

       2899
       2899
       +
          content-encoding, etc.) to comply with its requirements instead.

     

       2900
       2900
       +
       

     

       2901
       2901
       +
          The server MAY also choose to set additional headers.  If not

     

       2902
       2902
       +
          included, the server MUST generate and set a Message-ID header field

     

       2903
       2903
       +
          in conformance with [RFC5322], Section 3.6.4 and a Date header field

     

       2904
       2904
       +
          in conformance with Section 3.6.1.

     

       2905
       2905
       +
       

     

       2906
       2906
       +
          The final message generated may be invalid per RFC 5322.  For

     

       2907
       2907
       +
          example, if it is a half-finished draft, the To header field may have

     

       2908
       2908
       +
          a value that does not conform to the required syntax for this header.

     

       2909
       2909
       +
          The message will be checked for strict conformance when submitted for

     

       2910
       2910
       +
          sending (see the EmailSubmission object description).

     

       2911
       2911
       +
       

     

       2912
       2912
       +
       

     

       2913
       2913
       +
       

     

       2914
       2914
       +
       Jenkins & Newman             Standards Track                   [Page 52]

     

       2915
       2915
       +
       

     

       2916
       2916
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2917
       2917
       +
       

     

       2918
       2918
       +
       

     

       2919
       2919
       +
          Destroying an Email removes it from all Mailboxes to which it

     

       2920
       2920
       +
          belonged.  To just delete an Email to trash, simply change the

     

       2921
       2921
       +
          "mailboxIds" property, so it is now in the Mailbox with a "role"

     

       2922
       2922
       +
          property equal to "trash", and remove all other Mailbox ids.

     

       2923
       2923
       +
       

     

       2924
       2924
       +
          When emptying the trash, clients SHOULD NOT destroy Emails that are

     

       2925
       2925
       +
          also in a Mailbox other than trash.  For those Emails, they SHOULD

     

       2926
       2926
       +
          just remove the trash Mailbox from the Email.

     

       2927
       2927
       +
       

     

       2928
       2928
       +
          For successfully created Email objects, the "created" response

     

       2929
       2929
       +
          contains the "id", "blobId", "threadId", and "size" properties of the

     

       2930
       2930
       +
          object.

     

       2931
       2931
       +
       

     

       2932
       2932
       +
          The following extra SetError types are defined:

     

       2933
       2933
       +
       

     

       2934
       2934
       +
          For "create":

     

       2935
       2935
       +
       

     

       2936
       2936
       +
          o  "blobNotFound": At least one blob id given for an EmailBodyPart

     

       2937
       2937
       +
             doesn't exist.  An extra "notFound" property of type "Id[]" MUST

     

       2938
       2938
       +
             be included in the SetError object containing every "blobId"

     

       2939
       2939
       +
             referenced by an EmailBodyPart that could not be found on the

     

       2940
       2940
       +
             server.

     

       2941
       2941
       +
       

     

       2942
       2942
       +
          For "create" and "update":

     

       2943
       2943
       +
       

     

       2944
       2944
       +
          o  "tooManyKeywords": The change to the Email's keywords would exceed

     

       2945
       2945
       +
             a server-defined maximum.

     

       2946
       2946
       +
       

     

       2947
       2947
       +
          o  "tooManyMailboxes": The change to the set of Mailboxes that this

     

       2948
       2948
       +
             Email is in would exceed a server-defined maximum.

     

       2949
       2949
       +
       

     

       2950
       2950
       +
       4.7.  Email/copy

     

       2951
       2951
       +
       

     

       2952
       2952
       +
          This is a standard "/copy" method as described in [RFC8620],

     

       2953
       2953
       +
          Section 5.4, except only the "mailboxIds", "keywords", and

     

       2954
       2954
       +
          "receivedAt" properties may be set during the copy.  This method

     

       2955
       2955
       +
          cannot modify the message represented by the Email.

     

       2956
       2956
       +
       

     

       2957
       2957
       +
          The server MAY forbid two Email objects with identical message

     

       2958
       2958
       +
          content [RFC5322], or even just with the same Message-ID [RFC5322],

     

       2959
       2959
       +
          to coexist within an account; if the target account already has the

     

       2960
       2960
       +
          Email, the copy will be rejected with a standard "alreadyExists"

     

       2961
       2961
       +
          error.

     

       2962
       2962
       +
       

     

       2963
       2963
       +
          For successfully copied Email objects, the "created" response

     

       2964
       2964
       +
          contains the "id", "blobId", "threadId", and "size" properties of the

     

       2965
       2965
       +
          new object.

     

       2966
       2966
       +
       

     

       2967
       2967
       +
       

     

       2968
       2968
       +
       

     

       2969
       2969
       +
       

     

       2970
       2970
       +
       Jenkins & Newman             Standards Track                   [Page 53]

     

       2971
       2971
       +
       

     

       2972
       2972
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       2973
       2973
       +
       

     

       2974
       2974
       +
       

     

       2975
       2975
       +
       4.8.  Email/import

     

       2976
       2976
       +
       

     

       2977
       2977
       +
          The "Email/import" method adds messages [RFC5322] to the set of

     

       2978
       2978
       +
          Emails in an account.  The server MUST support messages with Email

     

       2979
       2979
       +
          Address Internationalization (EAI) headers [RFC6532].  The messages

     

       2980
       2980
       +
          must first be uploaded as blobs using the standard upload mechanism.

     

       2981
       2981
       +
          The method takes the following arguments:

     

       2982
       2982
       +
       

     

       2983
       2983
       +
          o  accountId: "Id"

     

       2984
       2984
       +
       

     

       2985
       2985
       +
             The id of the account to use.

     

       2986
       2986
       +
       

     

       2987
       2987
       +
          o  ifInState: "String|null"

     

       2988
       2988
       +
       

     

       2989
       2989
       +
             This is a state string as returned by the "Email/get" method.  If

     

       2990
       2990
       +
             supplied, the string must match the current state of the account

     

       2991
       2991
       +
             referenced by the accountId; otherwise, the method will be aborted

     

       2992
       2992
       +
             and a "stateMismatch" error returned.  If null, any changes will

     

       2993
       2993
       +
             be applied to the current state.

     

       2994
       2994
       +
       

     

       2995
       2995
       +
          o  emails: "Id[EmailImport]"

     

       2996
       2996
       +
       

     

       2997
       2997
       +
             A map of creation id (client specified) to EmailImport objects.

     

       2998
       2998
       +
       

     

       2999
       2999
       +
          An *EmailImport* object has the following properties:

     

       3000
       3000
       +
       

     

       3001
       3001
       +
          o  blobId: "Id"

     

       3002
       3002
       +
       

     

       3003
       3003
       +
             The id of the blob containing the raw message [RFC5322].

     

       3004
       3004
       +
       

     

       3005
       3005
       +
          o  mailboxIds: "Id[Boolean]"

     

       3006
       3006
       +
       

     

       3007
       3007
       +
             The ids of the Mailboxes to assign this Email to.  At least one

     

       3008
       3008
       +
             Mailbox MUST be given.

     

       3009
       3009
       +
       

     

       3010
       3010
       +
          o  keywords: "String[Boolean]" (default: {})

     

       3011
       3011
       +
       

     

       3012
       3012
       +
             The keywords to apply to the Email.

     

       3013
       3013
       +
       

     

       3014
       3014
       +
          o  receivedAt: "UTCDate" (default: time of most recent Received

     

       3015
       3015
       +
             header, or time of import on server if none)

     

       3016
       3016
       +
       

     

       3017
       3017
       +
             The "receivedAt" date to set on the Email.

     

       3018
       3018
       +
       

     

       3019
       3019
       +
          Each Email to import is considered an atomic unit that may succeed or

     

       3020
       3020
       +
          fail individually.  Importing successfully creates a new Email object

     

       3021
       3021
       +
          from the data referenced by the blobId and applies the given

     

       3022
       3022
       +
          Mailboxes, keywords, and receivedAt date.

     

       3023
       3023
       +
       

     

       3024
       3024
       +
       

     

       3025
       3025
       +
       

     

       3026
       3026
       +
       Jenkins & Newman             Standards Track                   [Page 54]

     

       3027
       3027
       +
       

     

       3028
       3028
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3029
       3029
       +
       

     

       3030
       3030
       +
       

     

       3031
       3031
       +
          The server MAY forbid two Email objects with the same exact content

     

       3032
       3032
       +
          [RFC5322], or even just with the same Message-ID [RFC5322], to

     

       3033
       3033
       +
          coexist within an account.  In this case, it MUST reject attempts to

     

       3034
       3034
       +
          import an Email considered to be a duplicate with an "alreadyExists"

     

       3035
       3035
       +
          SetError.  An "existingId" property of type "Id" MUST be included on

     

       3036
       3036
       +
          the SetError object with the id of the existing Email.  If duplicates

     

       3037
       3037
       +
          are allowed, the newly created Email object MUST have a separate id

     

       3038
       3038
       +
          and independent mutable properties to the existing object.

     

       3039
       3039
       +
       

     

       3040
       3040
       +
          If the "blobId", "mailboxIds", or "keywords" properties are invalid

     

       3041
       3041
       +
          (e.g., missing, wrong type, id not found), the server MUST reject the

     

       3042
       3042
       +
          import with an "invalidProperties" SetError.

     

       3043
       3043
       +
       

     

       3044
       3044
       +
          If the Email cannot be imported because it would take the account

     

       3045
       3045
       +
          over quota, the import should be rejected with an "overQuota"

     

       3046
       3046
       +
          SetError.

     

       3047
       3047
       +
       

     

       3048
       3048
       +
          If the blob referenced is not a valid message [RFC5322], the server

     

       3049
       3049
       +
          MAY modify the message to fix errors (such as removing NUL octets or

     

       3050
       3050
       +
          fixing invalid headers).  If it does this, the "blobId" on the

     

       3051
       3051
       +
          response MUST represent the new representation and therefore be

     

       3052
       3052
       +
          different to the "blobId" on the EmailImport object.  Alternatively,

     

       3053
       3053
       +
          the server MAY reject the import with an "invalidEmail" SetError.

     

       3054
       3054
       +
       

     

       3055
       3055
       +
          The response has the following arguments:

     

       3056
       3056
       +
       

     

       3057
       3057
       +
          o  accountId: "Id"

     

       3058
       3058
       +
       

     

       3059
       3059
       +
             The id of the account used for this call.

     

       3060
       3060
       +
       

     

       3061
       3061
       +
          o  oldState: "String|null"

     

       3062
       3062
       +
       

     

       3063
       3063
       +
             The state string that would have been returned by "Email/get" on

     

       3064
       3064
       +
             this account before making the requested changes, or null if the

     

       3065
       3065
       +
             server doesn't know what the previous state string was.

     

       3066
       3066
       +
       

     

       3067
       3067
       +
          o  newState: "String"

     

       3068
       3068
       +
       

     

       3069
       3069
       +
             The state string that will now be returned by "Email/get" on this

     

       3070
       3070
       +
             account.

     

       3071
       3071
       +
       

     

       3072
       3072
       +
          o  created: "Id[Email]|null"

     

       3073
       3073
       +
       

     

       3074
       3074
       +
             A map of the creation id to an object containing the "id",

     

       3075
       3075
       +
             "blobId", "threadId", and "size" properties for each successfully

     

       3076
       3076
       +
             imported Email, or null if none.

     

       3077
       3077
       +
       

     

       3078
       3078
       +
       

     

       3079
       3079
       +
       

     

       3080
       3080
       +
       

     

       3081
       3081
       +
       

     

       3082
       3082
       +
       Jenkins & Newman             Standards Track                   [Page 55]

     

       3083
       3083
       +
       

     

       3084
       3084
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3085
       3085
       +
       

     

       3086
       3086
       +
       

     

       3087
       3087
       +
          o  notCreated: "Id[SetError]|null"

     

       3088
       3088
       +
       

     

       3089
       3089
       +
             A map of the creation id to a SetError object for each Email that

     

       3090
       3090
       +
             failed to be created, or null if all successful.  The possible

     

       3091
       3091
       +
             errors are defined above.

     

       3092
       3092
       +
       

     

       3093
       3093
       +
          The following additional errors may be returned instead of the

     

       3094
       3094
       +
          "Email/import" response:

     

       3095
       3095
       +
       

     

       3096
       3096
       +
          "stateMismatch": An "ifInState" argument was supplied, and it does

     

       3097
       3097
       +
          not match the current state.

     

       3098
       3098
       +
       

     

       3099
       3099
       +
       4.9.  Email/parse

     

       3100
       3100
       +
       

     

       3101
       3101
       +
          This method allows you to parse blobs as messages [RFC5322] to get

     

       3102
       3102
       +
          Email objects.  The server MUST support messages with EAI headers

     

       3103
       3103
       +
          [RFC6532].  This can be used to parse and display attached messages

     

       3104
       3104
       +
          without having to import them as top-level Email objects in the mail

     

       3105
       3105
       +
          store in their own right.

     

       3106
       3106
       +
       

     

       3107
       3107
       +
          The following metadata properties on the Email objects will be null

     

       3108
       3108
       +
          if requested:

     

       3109
       3109
       +
       

     

       3110
       3110
       +
          o  id

     

       3111
       3111
       +
       

     

       3112
       3112
       +
          o  mailboxIds

     

       3113
       3113
       +
       

     

       3114
       3114
       +
          o  keywords

     

       3115
       3115
       +
       

     

       3116
       3116
       +
          o  receivedAt

     

       3117
       3117
       +
       

     

       3118
       3118
       +
          The "threadId" property of the Email MAY be present if the server can

     

       3119
       3119
       +
          calculate which Thread the Email would be assigned to were it to be

     

       3120
       3120
       +
          imported.  Otherwise, this too is null if fetched.

     

       3121
       3121
       +
       

     

       3122
       3122
       +
          The "Email/parse" method takes the following arguments:

     

       3123
       3123
       +
       

     

       3124
       3124
       +
          o  accountId: "Id"

     

       3125
       3125
       +
       

     

       3126
       3126
       +
             The id of the account to use.

     

       3127
       3127
       +
       

     

       3128
       3128
       +
          o  blobIds: "Id[]"

     

       3129
       3129
       +
       

     

       3130
       3130
       +
             The ids of the blobs to parse.

     

       3131
       3131
       +
       

     

       3132
       3132
       +
       

     

       3133
       3133
       +
       

     

       3134
       3134
       +
       

     

       3135
       3135
       +
       

     

       3136
       3136
       +
       

     

       3137
       3137
       +
       

     

       3138
       3138
       +
       Jenkins & Newman             Standards Track                   [Page 56]

     

       3139
       3139
       +
       

     

       3140
       3140
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3141
       3141
       +
       

     

       3142
       3142
       +
       

     

       3143
       3143
       +
          o  properties: "String[]"

     

       3144
       3144
       +
       

     

       3145
       3145
       +
             If supplied, only the properties listed in the array are returned

     

       3146
       3146
       +
             for each Email object.  If omitted, defaults to:

     

       3147
       3147
       +
       

     

       3148
       3148
       +
             [ "messageId", "inReplyTo", "references", "sender", "from", "to",

     

       3149
       3149
       +
             "cc", "bcc", "replyTo", "subject", "sentAt", "hasAttachment",

     

       3150
       3150
       +
             "preview", "bodyValues", "textBody", "htmlBody", "attachments" ]

     

       3151
       3151
       +
       

     

       3152
       3152
       +
          o  bodyProperties: "String[]"

     

       3153
       3153
       +
       

     

       3154
       3154
       +
             A list of properties to fetch for each EmailBodyPart returned.  If

     

       3155
       3155
       +
             omitted, defaults to the same value as the "Email/get"

     

       3156
       3156
       +
             "bodyProperties" default argument.

     

       3157
       3157
       +
       

     

       3158
       3158
       +
          o  fetchTextBodyValues: "Boolean" (default: false)

     

       3159
       3159
       +
       

     

       3160
       3160
       +
             If true, the "bodyValues" property includes any "text/*" part in

     

       3161
       3161
       +
             the "textBody" property.

     

       3162
       3162
       +
       

     

       3163
       3163
       +
          o  fetchHTMLBodyValues: "Boolean" (default: false)

     

       3164
       3164
       +
       

     

       3165
       3165
       +
             If true, the "bodyValues" property includes any "text/*" part in

     

       3166
       3166
       +
             the "htmlBody" property.

     

       3167
       3167
       +
       

     

       3168
       3168
       +
          o  fetchAllBodyValues: "Boolean" (default: false)

     

       3169
       3169
       +
       

     

       3170
       3170
       +
             If true, the "bodyValues" property includes any "text/*" part in

     

       3171
       3171
       +
             the "bodyStructure" property.

     

       3172
       3172
       +
       

     

       3173
       3173
       +
          o  maxBodyValueBytes: "UnsignedInt" (default: 0)

     

       3174
       3174
       +
       

     

       3175
       3175
       +
             If greater than zero, the "value" property of any EmailBodyValue

     

       3176
       3176
       +
             object returned in "bodyValues" MUST be truncated if necessary so

     

       3177
       3177
       +
             it does not exceed this number of octets in size.  If 0 (the

     

       3178
       3178
       +
             default), no truncation occurs.

     

       3179
       3179
       +
       

     

       3180
       3180
       +
             The server MUST ensure the truncation results in valid UTF-8 and

     

       3181
       3181
       +
             does not occur mid-codepoint.  If the part is of type "text/html",

     

       3182
       3182
       +
             the server SHOULD NOT truncate inside an HTML tag, e.g., in the

     

       3183
       3183
       +
             middle of "<a href="https://example.com">".  There is no

     

       3184
       3184
       +
             requirement for the truncated form to be a balanced tree or valid

     

       3185
       3185
       +
             HTML (indeed, the original source may well be neither of these

     

       3186
       3186
       +
             things).

     

       3187
       3187
       +
       

     

       3188
       3188
       +
       

     

       3189
       3189
       +
       

     

       3190
       3190
       +
       

     

       3191
       3191
       +
       

     

       3192
       3192
       +
       

     

       3193
       3193
       +
       

     

       3194
       3194
       +
       Jenkins & Newman             Standards Track                   [Page 57]

     

       3195
       3195
       +
       

     

       3196
       3196
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3197
       3197
       +
       

     

       3198
       3198
       +
       

     

       3199
       3199
       +
          The response has the following arguments:

     

       3200
       3200
       +
       

     

       3201
       3201
       +
          o  accountId: "Id"

     

       3202
       3202
       +
       

     

       3203
       3203
       +
             The id of the account used for the call.

     

       3204
       3204
       +
       

     

       3205
       3205
       +
          o  parsed: "Id[Email]|null"

     

       3206
       3206
       +
       

     

       3207
       3207
       +
             A map of blob id to parsed Email representation for each

     

       3208
       3208
       +
             successfully parsed blob, or null if none.

     

       3209
       3209
       +
       

     

       3210
       3210
       +
          o  notParsable: "Id[]|null"

     

       3211
       3211
       +
       

     

       3212
       3212
       +
             A list of ids given that corresponded to blobs that could not be

     

       3213
       3213
       +
             parsed as Emails, or null if none.

     

       3214
       3214
       +
       

     

       3215
       3215
       +
          o  notFound: "Id[]|null"

     

       3216
       3216
       +
       

     

       3217
       3217
       +
             A list of blob ids given that could not be found, or null if none.

     

       3218
       3218
       +
       

     

       3219
       3219
       +
          As specified above, parsed forms of headers may only be used on

     

       3220
       3220
       +
          appropriate header fields.  Attempting to fetch a form that is

     

       3221
       3221
       +
          forbidden (e.g., "header:From:asDate") MUST result in the method call

     

       3222
       3222
       +
          being rejected with an "invalidArguments" error.

     

       3223
       3223
       +
       

     

       3224
       3224
       +
          Where a specific header field is requested as a property, the

     

       3225
       3225
       +
          capitalization of the property name in the response MUST be identical

     

       3226
       3226
       +
          to that used in the request.

     

       3227
       3227
       +
       

     

       3228
       3228
       +
       4.10.  Examples

     

       3229
       3229
       +
       

     

       3230
       3230
       +
          A client logs in for the first time.  It first fetches the set of

     

       3231
       3231
       +
          Mailboxes.  Now it will display the inbox to the user, which we will

     

       3232
       3232
       +
          presume has Mailbox id "fb666a55".  The inbox may be (very!) large,

     

       3233
       3233
       +
          but the user's screen is only so big, so the client can just load the

     

       3234
       3234
       +
          Threads it needs to fill the screen and then load in more only when

     

       3235
       3235
       +
          the user scrolls.  The client sends this request:

     

       3236
       3236
       +
       

     

       3237
       3237
       +
                             [[ "Email/query",{

     

       3238
       3238
       +
                               "accountId": "ue150411c",

     

       3239
       3239
       +
                               "filter": {

     

       3240
       3240
       +
                                 "inMailbox": "fb666a55"

     

       3241
       3241
       +
                               },

     

       3242
       3242
       +
                               "sort": [{

     

       3243
       3243
       +
                                 "isAscending": false,

     

       3244
       3244
       +
                                 "property": "receivedAt"

     

       3245
       3245
       +
                               }],

     

       3246
       3246
       +
                               "collapseThreads": true,

     

       3247
       3247
       +
       

     

       3248
       3248
       +
       

     

       3249
       3249
       +
       

     

       3250
       3250
       +
       Jenkins & Newman             Standards Track                   [Page 58]

     

       3251
       3251
       +
       

     

       3252
       3252
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3253
       3253
       +
       

     

       3254
       3254
       +
       

     

       3255
       3255
       +
                               "position": 0,

     

       3256
       3256
       +
                               "limit": 30,

     

       3257
       3257
       +
                               "calculateTotal": true

     

       3258
       3258
       +
                             }, "0" ],

     

       3259
       3259
       +
                             [ "Email/get", {

     

       3260
       3260
       +
                               "accountId": "ue150411c",

     

       3261
       3261
       +
                               "#ids": {

     

       3262
       3262
       +
                                 "resultOf": "0",

     

       3263
       3263
       +
                                 "name": "Email/query",

     

       3264
       3264
       +
                                 "path": "/ids"

     

       3265
       3265
       +
                               },

     

       3266
       3266
       +
                               "properties": [

     

       3267
       3267
       +
                                 "threadId"

     

       3268
       3268
       +
                               ]

     

       3269
       3269
       +
                             }, "1" ],

     

       3270
       3270
       +
                             [ "Thread/get", {

     

       3271
       3271
       +
                               "accountId": "ue150411c",

     

       3272
       3272
       +
                               "#ids": {

     

       3273
       3273
       +
                                 "resultOf": "1",

     

       3274
       3274
       +
                                 "name": "Email/get",

     

       3275
       3275
       +
                                 "path": "/list/*/threadId"

     

       3276
       3276
       +
                               }

     

       3277
       3277
       +
                             }, "2" ],

     

       3278
       3278
       +
                             [ "Email/get", {

     

       3279
       3279
       +
                               "accountId": "ue150411c",

     

       3280
       3280
       +
                               "#ids": {

     

       3281
       3281
       +
                                 "resultOf": "2",

     

       3282
       3282
       +
                                 "name": "Thread/get",

     

       3283
       3283
       +
                                 "path": "/list/*/emailIds"

     

       3284
       3284
       +
                               },

     

       3285
       3285
       +
                               "properties": [

     

       3286
       3286
       +
                                 "threadId",

     

       3287
       3287
       +
                                 "mailboxIds",

     

       3288
       3288
       +
                                 "keywords",

     

       3289
       3289
       +
                                 "hasAttachment",

     

       3290
       3290
       +
                                 "from",

     

       3291
       3291
       +
                                 "subject",

     

       3292
       3292
       +
                                 "receivedAt",

     

       3293
       3293
       +
                                 "size",

     

       3294
       3294
       +
                                 "preview"

     

       3295
       3295
       +
                               ]

     

       3296
       3296
       +
                             }, "3" ]]

     

       3297
       3297
       +
       

     

       3298
       3298
       +
       

     

       3299
       3299
       +
       

     

       3300
       3300
       +
       

     

       3301
       3301
       +
       

     

       3302
       3302
       +
       

     

       3303
       3303
       +
       

     

       3304
       3304
       +
       

     

       3305
       3305
       +
       

     

       3306
       3306
       +
       Jenkins & Newman             Standards Track                   [Page 59]

     

       3307
       3307
       +
       

     

       3308
       3308
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3309
       3309
       +
       

     

       3310
       3310
       +
       

     

       3311
       3311
       +
          Let's break down the 4 method calls to see what they're doing:

     

       3312
       3312
       +
       

     

       3313
       3313
       +
          "0": This asks the server for the ids of the first 30 Email objects

     

       3314
       3314
       +
          in the inbox, sorted newest first, ignoring Emails from the same

     

       3315
       3315
       +
          Thread as a newer Email in the Mailbox (i.e., it is the first 30

     

       3316
       3316
       +
          unique Threads).

     

       3317
       3317
       +
       

     

       3318
       3318
       +
          "1": Now we use a back-reference to fetch the Thread ids for each of

     

       3319
       3319
       +
          these Email ids.

     

       3320
       3320
       +
       

     

       3321
       3321
       +
          "2": Another back-reference fetches the Thread object for each of

     

       3322
       3322
       +
          these Thread ids.

     

       3323
       3323
       +
       

     

       3324
       3324
       +
          "3": Finally, we fetch the information we need to display the Mailbox

     

       3325
       3325
       +
          listing (but no more!) for every Email in each of these 30 Threads.

     

       3326
       3326
       +
          The client may aggregate this data for display, for example, by

     

       3327
       3327
       +
          showing the Thread as "flagged" if any of the Emails in it has the

     

       3328
       3328
       +
          "$flagged" keyword.

     

       3329
       3329
       +
       

     

       3330
       3330
       +
          The response from the server may look something like this:

     

       3331
       3331
       +
       

     

       3332
       3332
       +
           [[ "Email/query", {

     

       3333
       3333
       +
             "accountId": "ue150411c",

     

       3334
       3334
       +
             "queryState": "09aa9a075588-780599:0",

     

       3335
       3335
       +
             "canCalculateChanges": true,

     

       3336
       3336
       +
             "position": 0,

     

       3337
       3337
       +
             "total": 115,

     

       3338
       3338
       +
             "ids": [ "Ma783e5cdf5f2deffbc97930a",

     

       3339
       3339
       +
               "M9bd17497e2a99cb345fc1d0a", ... ]

     

       3340
       3340
       +
           }, "0" ],

     

       3341
       3341
       +
           [ "Email/get", {

     

       3342
       3342
       +
             "accountId": "ue150411c",

     

       3343
       3343
       +
             "state": "780599",

     

       3344
       3344
       +
             "list": [{

     

       3345
       3345
       +
               "id": "Ma783e5cdf5f2deffbc97930a",

     

       3346
       3346
       +
               "threadId": "T36703c2cfe9bd5ed"

     

       3347
       3347
       +
             }, {

     

       3348
       3348
       +
               "id": "M9bd17497e2a99cb345fc1d0a",

     

       3349
       3349
       +
               "threadId": "T0a22ad76e9c097a1"

     

       3350
       3350
       +
             }, ... ],

     

       3351
       3351
       +
             "notFound": []

     

       3352
       3352
       +
           }, "1" ],

     

       3353
       3353
       +
           [ "Thread/get", {

     

       3354
       3354
       +
             "accountId": "ue150411c",

     

       3355
       3355
       +
             "state": "22a8728b",

     

       3356
       3356
       +
             "list": [{

     

       3357
       3357
       +
               "id": "T36703c2cfe9bd5ed",

     

       3358
       3358
       +
               "emailIds": [ "Ma783e5cdf5f2deffbc97930a" ]

     

       3359
       3359
       +
       

     

       3360
       3360
       +
       

     

       3361
       3361
       +
       

     

       3362
       3362
       +
       Jenkins & Newman             Standards Track                   [Page 60]

     

       3363
       3363
       +
       

     

       3364
       3364
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3365
       3365
       +
       

     

       3366
       3366
       +
       

     

       3367
       3367
       +
             }, {

     

       3368
       3368
       +
               "id": "T0a22ad76e9c097a1",

     

       3369
       3369
       +
               "emailIds": [ "M3b568670a63e5d100f518fa5",

     

       3370
       3370
       +
                 "M9bd17497e2a99cb345fc1d0a" ]

     

       3371
       3371
       +
             },  ... ],

     

       3372
       3372
       +
             "notFound": []

     

       3373
       3373
       +
           }, "2" ],

     

       3374
       3374
       +
           [ "Email/get", {

     

       3375
       3375
       +
             "accountId": "ue150411c",

     

       3376
       3376
       +
             "state": "780599",

     

       3377
       3377
       +
             "list": [{

     

       3378
       3378
       +
               "id": "Ma783e5cdf5f2deffbc97930a",

     

       3379
       3379
       +
               "threadId": "T36703c2cfe9bd5ed",

     

       3380
       3380
       +
               "mailboxIds": {

     

       3381
       3381
       +
                 "fb666a55": true

     

       3382
       3382
       +
               },

     

       3383
       3383
       +
               "keywords": {

     

       3384
       3384
       +
                 "$seen": true,

     

       3385
       3385
       +
                 "$flagged": true

     

       3386
       3386
       +
               },

     

       3387
       3387
       +
               "hasAttachment": true,

     

       3388
       3388
       +
               "from": [{

     

       3389
       3389
       +
                 "email": "jdoe@example.com",

     

       3390
       3390
       +
                 "name": "Jane Doe"

     

       3391
       3391
       +
               }],

     

       3392
       3392
       +
               "subject": "The Big Reveal",

     

       3393
       3393
       +
               "receivedAt": "2018-06-27T00:20:35Z",

     

       3394
       3394
       +
               "size": 175047,

     

       3395
       3395
       +
               "preview": "As you may be aware, we are required to prepare a

     

       3396
       3396
       +
                 presentation where we wow a panel of 5 random members of the

     

       3397
       3397
       +
                 public, on or before 30 June each year.  We have drafted..."

     

       3398
       3398
       +
             },

     

       3399
       3399
       +
             ...

     

       3400
       3400
       +
             ],

     

       3401
       3401
       +
             "notFound": []

     

       3402
       3402
       +
           }, "3" ]]

     

       3403
       3403
       +
       

     

       3404
       3404
       +
       

     

       3405
       3405
       +
       

     

       3406
       3406
       +
       

     

       3407
       3407
       +
       

     

       3408
       3408
       +
       

     

       3409
       3409
       +
       

     

       3410
       3410
       +
       

     

       3411
       3411
       +
       

     

       3412
       3412
       +
       

     

       3413
       3413
       +
       

     

       3414
       3414
       +
       

     

       3415
       3415
       +
       

     

       3416
       3416
       +
       

     

       3417
       3417
       +
       

     

       3418
       3418
       +
       Jenkins & Newman             Standards Track                   [Page 61]

     

       3419
       3419
       +
       

     

       3420
       3420
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3421
       3421
       +
       

     

       3422
       3422
       +
       

     

       3423
       3423
       +
          Now, on another device, the user marks the first Email as unread,

     

       3424
       3424
       +
          sending this API request:

     

       3425
       3425
       +
       

     

       3426
       3426
       +
                           [[ "Email/set", {

     

       3427
       3427
       +
                             "accountId": "ue150411c",

     

       3428
       3428
       +
                             "update": {

     

       3429
       3429
       +
                               "Ma783e5cdf5f2deffbc97930a": {

     

       3430
       3430
       +
                                 "keywords/$seen": null

     

       3431
       3431
       +
                               }

     

       3432
       3432
       +
                             }

     

       3433
       3433
       +
                           }, "0" ]]

     

       3434
       3434
       +
       

     

       3435
       3435
       +
          The server applies this and sends the success response:

     

       3436
       3436
       +
       

     

       3437
       3437
       +
                          [[ "Email/set", {

     

       3438
       3438
       +
                            "accountId": "ue150411c",

     

       3439
       3439
       +
                            "oldState": "780605",

     

       3440
       3440
       +
                            "newState": "780606",

     

       3441
       3441
       +
                            "updated": {

     

       3442
       3442
       +
                              "Ma783e5cdf5f2deffbc97930a": null

     

       3443
       3443
       +
                            },

     

       3444
       3444
       +
                            ...

     

       3445
       3445
       +
                          }, "0" ]]

     

       3446
       3446
       +
       

     

       3447
       3447
       +
          The user also deletes a few Emails, and then a new message arrives.

     

       3448
       3448
       +
       

     

       3449
       3449
       +
       

     

       3450
       3450
       +
       

     

       3451
       3451
       +
       

     

       3452
       3452
       +
       

     

       3453
       3453
       +
       

     

       3454
       3454
       +
       

     

       3455
       3455
       +
       

     

       3456
       3456
       +
       

     

       3457
       3457
       +
       

     

       3458
       3458
       +
       

     

       3459
       3459
       +
       

     

       3460
       3460
       +
       

     

       3461
       3461
       +
       

     

       3462
       3462
       +
       

     

       3463
       3463
       +
       

     

       3464
       3464
       +
       

     

       3465
       3465
       +
       

     

       3466
       3466
       +
       

     

       3467
       3467
       +
       

     

       3468
       3468
       +
       

     

       3469
       3469
       +
       

     

       3470
       3470
       +
       

     

       3471
       3471
       +
       

     

       3472
       3472
       +
       

     

       3473
       3473
       +
       

     

       3474
       3474
       +
       Jenkins & Newman             Standards Track                   [Page 62]

     

       3475
       3475
       +
       

     

       3476
       3476
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3477
       3477
       +
       

     

       3478
       3478
       +
       

     

       3479
       3479
       +
          Back on our original machine, we receive a push update that the state

     

       3480
       3480
       +
          string for Email is now "780800".  As this does not match the

     

       3481
       3481
       +
          client's current state, it issues a request for the changes:

     

       3482
       3482
       +
       

     

       3483
       3483
       +
                      [[ "Email/changes", {

     

       3484
       3484
       +
                        "accountId": "ue150411c",

     

       3485
       3485
       +
                        "sinceState": "780605",

     

       3486
       3486
       +
                        "maxChanges": 50

     

       3487
       3487
       +
                      }, "3" ],

     

       3488
       3488
       +
                      [ "Email/queryChanges", {

     

       3489
       3489
       +
                        "accountId": "ue150411c",

     

       3490
       3490
       +
                        "filter": {

     

       3491
       3491
       +
                          "inMailbox": "fb666a55"

     

       3492
       3492
       +
                        },

     

       3493
       3493
       +
                        "sort": [{

     

       3494
       3494
       +
                          "property": "receivedAt",

     

       3495
       3495
       +
                          "isAscending": false

     

       3496
       3496
       +
                        }],

     

       3497
       3497
       +
                        "collapseThreads": true,

     

       3498
       3498
       +
                        "sinceQueryState": "09aa9a075588-780599:0",

     

       3499
       3499
       +
                        "upToId": "Mc2781d5e856a908d8a35a564",

     

       3500
       3500
       +
                        "maxChanges": 25,

     

       3501
       3501
       +
                        "calculateTotal": true

     

       3502
       3502
       +
                      }, "11" ]]

     

       3503
       3503
       +
       

     

       3504
       3504
       +
          The response:

     

       3505
       3505
       +
       

     

       3506
       3506
       +
                   [[ "Email/changes", {

     

       3507
       3507
       +
                     "accountId": "ue150411c",

     

       3508
       3508
       +
                     "oldState": "780605",

     

       3509
       3509
       +
                     "newState": "780800",

     

       3510
       3510
       +
                     "hasMoreChanges": false,

     

       3511
       3511
       +
                     "created": [ "Me8de6c9f6de198239b982ea2" ],

     

       3512
       3512
       +
                     "updated": [ "Ma783e5cdf5f2deffbc97930a" ],

     

       3513
       3513
       +
                     "destroyed": [ "M9bd17497e2a99cb345fc1d0a", ... ]

     

       3514
       3514
       +
                   }, "3" ],

     

       3515
       3515
       +
                   [ "Email/queryChanges", {

     

       3516
       3516
       +
                     "accountId": "ue150411c",

     

       3517
       3517
       +
                     "oldQueryState": "09aa9a075588-780599:0",

     

       3518
       3518
       +
                     "newQueryState": "e35e9facf117-780615:0",

     

       3519
       3519
       +
                     "added": [{

     

       3520
       3520
       +
                       "id": "Me8de6c9f6de198239b982ea2",

     

       3521
       3521
       +
                       "index": 0

     

       3522
       3522
       +
                     }],

     

       3523
       3523
       +
                     "removed": [ "M9bd17497e2a99cb345fc1d0a" ],

     

       3524
       3524
       +
                     "total": 115

     

       3525
       3525
       +
                   }, "11" ]]

     

       3526
       3526
       +
       

     

       3527
       3527
       +
       

     

       3528
       3528
       +
       

     

       3529
       3529
       +
       

     

       3530
       3530
       +
       Jenkins & Newman             Standards Track                   [Page 63]

     

       3531
       3531
       +
       

     

       3532
       3532
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3533
       3533
       +
       

     

       3534
       3534
       +
       

     

       3535
       3535
       +
          The client can update its local cache of the query results by

     

       3536
       3536
       +
          removing "M9bd17497e2a99cb345fc1d0a" and then splicing in

     

       3537
       3537
       +
          "Me8de6c9f6de198239b982ea2" at position 0.  As it does not have the

     

       3538
       3538
       +
          data for this new Email, it will then fetch it (it also could have

     

       3539
       3539
       +
          done this in the same request using back-references).

     

       3540
       3540
       +
       

     

       3541
       3541
       +
          It knows something has changed about "Ma783e5cdf5f2deffbc97930a", so

     

       3542
       3542
       +
          it will refetch the Mailbox ids and keywords (the only mutable

     

       3543
       3543
       +
          properties) for this Email too.

     

       3544
       3544
       +
       

     

       3545
       3545
       +
          The user starts composing a new Email.  The email is plaintext and

     

       3546
       3546
       +
          the client knows the email in English so adds this metadata to the

     

       3547
       3547
       +
          body part.  The user saves a draft while the composition is still in

     

       3548
       3548
       +
          progress.  The client sends:

     

       3549
       3549
       +
       

     

       3550
       3550
       +
            [[ "Email/set", {

     

       3551
       3551
       +
              "accountId": "ue150411c",

     

       3552
       3552
       +
              "create": {

     

       3553
       3553
       +
                "k192": {

     

       3554
       3554
       +
                  "mailboxIds": {

     

       3555
       3555
       +
                    "2ea1ca41b38e": true

     

       3556
       3556
       +
                  },

     

       3557
       3557
       +
                  "keywords": {

     

       3558
       3558
       +
                    "$seen": true,

     

       3559
       3559
       +
                    "$draft": true

     

       3560
       3560
       +
                  },

     

       3561
       3561
       +
                  "from": [{

     

       3562
       3562
       +
                    "name": "Joe Bloggs",

     

       3563
       3563
       +
                    "email": "joe@example.com"

     

       3564
       3564
       +
                  }],

     

       3565
       3565
       +
                  "subject": "World domination",

     

       3566
       3566
       +
                  "receivedAt": "2018-07-10T01:03:11Z",

     

       3567
       3567
       +
                  "sentAt": "2018-07-10T11:03:11+10:00",

     

       3568
       3568
       +
                  "bodyStructure": {

     

       3569
       3569
       +
                    "type": "text/plain",

     

       3570
       3570
       +
                    "partId": "bd48",

     

       3571
       3571
       +
                    "header:Content-Language": "en"

     

       3572
       3572
       +
                  },

     

       3573
       3573
       +
                  "bodyValues": {

     

       3574
       3574
       +
                    "bd48": {

     

       3575
       3575
       +
                      "value": "I have the most brilliant plan.  Let me tell

     

       3576
       3576
       +
                        you all about it.  What we do is, we",

     

       3577
       3577
       +
                      "isTruncated": false

     

       3578
       3578
       +
                    }

     

       3579
       3579
       +
                  }

     

       3580
       3580
       +
                }

     

       3581
       3581
       +
              }

     

       3582
       3582
       +
            }, "0" ]]

     

       3583
       3583
       +
       

     

       3584
       3584
       +
       

     

       3585
       3585
       +
       

     

       3586
       3586
       +
       Jenkins & Newman             Standards Track                   [Page 64]

     

       3587
       3587
       +
       

     

       3588
       3588
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3589
       3589
       +
       

     

       3590
       3590
       +
       

     

       3591
       3591
       +
          The server creates the message and sends the success response:

     

       3592
       3592
       +
       

     

       3593
       3593
       +
              [[ "Email/set", {

     

       3594
       3594
       +
                "accountId": "ue150411c",

     

       3595
       3595
       +
                "oldState": "780823",

     

       3596
       3596
       +
                "newState": "780839",

     

       3597
       3597
       +
                "created": {

     

       3598
       3598
       +
                  "k192": {

     

       3599
       3599
       +
                    "id": "Mf40b5f831efa7233b9eb1c7f",

     

       3600
       3600
       +
                    "blobId": "Gf40b5f831efa7233b9eb1c7f8f97d84eeeee64f7",

     

       3601
       3601
       +
                    "threadId": "Td957e72e89f516dc",

     

       3602
       3602
       +
                    "size": 359

     

       3603
       3603
       +
                  }

     

       3604
       3604
       +
                },

     

       3605
       3605
       +
                ...

     

       3606
       3606
       +
              }, "0" ]]

     

       3607
       3607
       +
       

     

       3608
       3608
       +
          The message created on the server looks something like this:

     

       3609
       3609
       +
       

     

       3610
       3610
       +
        Message-Id: <bbce0ae9-58be-4b24-ac82-deb840d58016@sloti7d1t02>

     

       3611
       3611
       +
        User-Agent: Cyrus-JMAP/3.1.6-736-gdfb8e44

     

       3612
       3612
       +
        Mime-Version: 1.0

     

       3613
       3613
       +
        Date: Tue, 10 Jul 2018 11:03:11 +1000

     

       3614
       3614
       +
        From: "Joe Bloggs" <joe@example.com>

     

       3615
       3615
       +
        Subject: World domination

     

       3616
       3616
       +
        Content-Language: en

     

       3617
       3617
       +
        Content-Type: text/plain

     

       3618
       3618
       +
       

     

       3619
       3619
       +
        I have the most brilliant plan.  Let me tell you all about it.  What we

     

       3620
       3620
       +
        do is, we

     

       3621
       3621
       +
       

     

       3622
       3622
       +
          The user adds a recipient and converts the message to HTML so they

     

       3623
       3623
       +
          can add formatting, then saves an updated draft:

     

       3624
       3624
       +
       

     

       3625
       3625
       +
        [[ "Email/set", {

     

       3626
       3626
       +
          "accountId": "ue150411c",

     

       3627
       3627
       +
          "create": {

     

       3628
       3628
       +
            "k1546": {

     

       3629
       3629
       +
              "mailboxIds": {

     

       3630
       3630
       +
                "2ea1ca41b38e": true

     

       3631
       3631
       +
              },

     

       3632
       3632
       +
              "keywords": {

     

       3633
       3633
       +
                "$seen": true,

     

       3634
       3634
       +
                "$draft": true

     

       3635
       3635
       +
              },

     

       3636
       3636
       +
              "from": [{

     

       3637
       3637
       +
                "name": "Joe Bloggs",

     

       3638
       3638
       +
                "email": "joe@example.com"

     

       3639
       3639
       +
       

     

       3640
       3640
       +
       

     

       3641
       3641
       +
       

     

       3642
       3642
       +
       Jenkins & Newman             Standards Track                   [Page 65]

     

       3643
       3643
       +
       

     

       3644
       3644
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3645
       3645
       +
       

     

       3646
       3646
       +
       

     

       3647
       3647
       +
              }],

     

       3648
       3648
       +
              "to": [{

     

       3649
       3649
       +
                "name": "John",

     

       3650
       3650
       +
                "email": "john@example.com"

     

       3651
       3651
       +
              }],

     

       3652
       3652
       +
              "subject": "World domination",

     

       3653
       3653
       +
              "receivedAt": "2018-07-10T01:05:08Z",

     

       3654
       3654
       +
              "sentAt": "2018-07-10T11:05:08+10:00",

     

       3655
       3655
       +
              "bodyStructure": {

     

       3656
       3656
       +
                "type": "multipart/alternative",

     

       3657
       3657
       +
                "subParts": [{

     

       3658
       3658
       +
                  "partId": "a49d",

     

       3659
       3659
       +
                  "type": "text/html",

     

       3660
       3660
       +
                  "header:Content-Language": "en"

     

       3661
       3661
       +
                }, {

     

       3662
       3662
       +
                  "partId": "bd48",

     

       3663
       3663
       +
                  "type": "text/plain",

     

       3664
       3664
       +
                  "header:Content-Language": "en"

     

       3665
       3665
       +
                }]

     

       3666
       3666
       +
              },

     

       3667
       3667
       +
              "bodyValues": {

     

       3668
       3668
       +
                "bd48": {

     

       3669
       3669
       +
                  "value": "I have the most brilliant plan.  Let me tell

     

       3670
       3670
       +
                    you all about it.  What we do is, we",

     

       3671
       3671
       +
                  "isTruncated": false

     

       3672
       3672
       +
                },

     

       3673
       3673
       +
                "a49d": {

     

       3674
       3674
       +
                  "value": "<!DOCTYPE html><html><head><title></title>

     

       3675
       3675
       +
                    <style type=\"text/css\">div{font-size:16px}</style></head>

     

       3676
       3676
       +
                    <body><div>I have the most <b>brilliant</b> plan.  Let me

     

       3677
       3677
       +
                    tell you all about it.  What we do is, we</div></body>

     

       3678
       3678
       +
                    </html>",

     

       3679
       3679
       +
                  "isTruncated": false

     

       3680
       3680
       +
                }

     

       3681
       3681
       +
              }

     

       3682
       3682
       +
            }

     

       3683
       3683
       +
          },

     

       3684
       3684
       +
          "destroy": [ "Mf40b5f831efa7233b9eb1c7f" ]

     

       3685
       3685
       +
        }, "0" ]]

     

       3686
       3686
       +
       

     

       3687
       3687
       +
       

     

       3688
       3688
       +
       

     

       3689
       3689
       +
       

     

       3690
       3690
       +
       

     

       3691
       3691
       +
       

     

       3692
       3692
       +
       

     

       3693
       3693
       +
       

     

       3694
       3694
       +
       

     

       3695
       3695
       +
       

     

       3696
       3696
       +
       

     

       3697
       3697
       +
       

     

       3698
       3698
       +
       Jenkins & Newman             Standards Track                   [Page 66]

     

       3699
       3699
       +
       

     

       3700
       3700
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3701
       3701
       +
       

     

       3702
       3702
       +
       

     

       3703
       3703
       +
          The server creates the new draft, deletes the old one, and sends the

     

       3704
       3704
       +
          success response:

     

       3705
       3705
       +
       

     

       3706
       3706
       +
              [[ "Email/set", {

     

       3707
       3707
       +
                "accountId": "ue150411c",

     

       3708
       3708
       +
                "oldState": "780839",

     

       3709
       3709
       +
                "newState": "780842",

     

       3710
       3710
       +
                "created": {

     

       3711
       3711
       +
                  "k1546": {

     

       3712
       3712
       +
                    "id": "Md45b47b4877521042cec0938",

     

       3713
       3713
       +
                    "blobId": "Ge8de6c9f6de198239b982ea214e0f3a704e4af74",

     

       3714
       3714
       +
                    "threadId": "Td957e72e89f516dc",

     

       3715
       3715
       +
                    "size": 11721

     

       3716
       3716
       +
                  }

     

       3717
       3717
       +
                },

     

       3718
       3718
       +
                "destroyed": [ "Mf40b5f831efa7233b9eb1c7f" ],

     

       3719
       3719
       +
                ...

     

       3720
       3720
       +
              }, "0" ]]

     

       3721
       3721
       +
       

     

       3722
       3722
       +
          The client moves this draft to a different account.  The only way to

     

       3723
       3723
       +
          do this is via the "Email/copy" method.  It MUST set a new

     

       3724
       3724
       +
          "mailboxIds" property, since the current value will not be valid

     

       3725
       3725
       +
          Mailbox ids in the destination account:

     

       3726
       3726
       +
       

     

       3727
       3727
       +
                        [[ "Email/copy", {

     

       3728
       3728
       +
                          "fromAccountId": "ue150411c",

     

       3729
       3729
       +
                          "accountId": "u6c6c41ac",

     

       3730
       3730
       +
                          "create": {

     

       3731
       3731
       +
                            "k45": {

     

       3732
       3732
       +
                              "id": "Md45b47b4877521042cec0938",

     

       3733
       3733
       +
                              "mailboxIds": {

     

       3734
       3734
       +
                                "75a4c956": true

     

       3735
       3735
       +
                              }

     

       3736
       3736
       +
                            }

     

       3737
       3737
       +
                          },

     

       3738
       3738
       +
                          "onSuccessDestroyOriginal": true

     

       3739
       3739
       +
                        }, "0" ]]

     

       3740
       3740
       +
       

     

       3741
       3741
       +
       

     

       3742
       3742
       +
       

     

       3743
       3743
       +
       

     

       3744
       3744
       +
       

     

       3745
       3745
       +
       

     

       3746
       3746
       +
       

     

       3747
       3747
       +
       

     

       3748
       3748
       +
       

     

       3749
       3749
       +
       

     

       3750
       3750
       +
       

     

       3751
       3751
       +
       

     

       3752
       3752
       +
       

     

       3753
       3753
       +
       

     

       3754
       3754
       +
       Jenkins & Newman             Standards Track                   [Page 67]

     

       3755
       3755
       +
       

     

       3756
       3756
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3757
       3757
       +
       

     

       3758
       3758
       +
       

     

       3759
       3759
       +
          The server successfully copies the Email and deletes the original.

     

       3760
       3760
       +
          Due to the implicit call to "Email/set", there are two responses to

     

       3761
       3761
       +
          the single method call, both with the same method call id:

     

       3762
       3762
       +
       

     

       3763
       3763
       +
              [[ "Email/copy", {

     

       3764
       3764
       +
                "fromAccountId": "ue150411c",

     

       3765
       3765
       +
                "accountId": "u6c6c41ac",

     

       3766
       3766
       +
                "oldState": "7ee7e9263a6d",

     

       3767
       3767
       +
                "newState": "5a0d2447ed26",

     

       3768
       3768
       +
                "created": {

     

       3769
       3769
       +
                  "k45": {

     

       3770
       3770
       +
                    "id": "M138f9954a5cd2423daeafa55",

     

       3771
       3771
       +
                    "blobId": "G6b9fb047cba722c48c611e79233d057c6b0b74e8",

     

       3772
       3772
       +
                    "threadId": "T2f242ea424a4079a",

     

       3773
       3773
       +
                    "size": 11721

     

       3774
       3774
       +
                  }

     

       3775
       3775
       +
                },

     

       3776
       3776
       +
                "notCreated": null

     

       3777
       3777
       +
              }, "0" ],

     

       3778
       3778
       +
              [ "Email/set", {

     

       3779
       3779
       +
                "accountId": "ue150411c",

     

       3780
       3780
       +
                "oldState": "780842",

     

       3781
       3781
       +
                "newState": "780871",

     

       3782
       3782
       +
                "destroyed": [ "Md45b47b4877521042cec0938" ],

     

       3783
       3783
       +
                ...

     

       3784
       3784
       +
              }, "0" ]]

     

       3785
       3785
       +
       

     

       3786
       3786
       +
       5.  Search Snippets

     

       3787
       3787
       +
       

     

       3788
       3788
       +
          When doing a search on a "String" property, the client may wish to

     

       3789
       3789
       +
          show the relevant section of the body that matches the search as a

     

       3790
       3790
       +
          preview and to highlight any matching terms in both this and the

     

       3791
       3791
       +
          subject of the Email.  Search snippets represent this data.

     

       3792
       3792
       +
       

     

       3793
       3793
       +
          A *SearchSnippet* object has the following properties:

     

       3794
       3794
       +
       

     

       3795
       3795
       +
          o  emailId: "Id"

     

       3796
       3796
       +
       

     

       3797
       3797
       +
             The Email id the snippet applies to.

     

       3798
       3798
       +
       

     

       3799
       3799
       +
       

     

       3800
       3800
       +
       

     

       3801
       3801
       +
       

     

       3802
       3802
       +
       

     

       3803
       3803
       +
       

     

       3804
       3804
       +
       

     

       3805
       3805
       +
       

     

       3806
       3806
       +
       

     

       3807
       3807
       +
       

     

       3808
       3808
       +
       

     

       3809
       3809
       +
       

     

       3810
       3810
       +
       Jenkins & Newman             Standards Track                   [Page 68]

     

       3811
       3811
       +
       

     

       3812
       3812
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3813
       3813
       +
       

     

       3814
       3814
       +
       

     

       3815
       3815
       +
          o  subject: "String|null"

     

       3816
       3816
       +
       

     

       3817
       3817
       +
             If text from the filter matches the subject, this is the subject

     

       3818
       3818
       +
             of the Email with the following transformations:

     

       3819
       3819
       +
       

     

       3820
       3820
       +
             1.  Any instance of the following three characters MUST be

     

       3821
       3821
       +
                 replaced by an appropriate HTML entity: & (ampersand), <

     

       3822
       3822
       +
                 (less-than sign), and > (greater-than sign) [HTML].  Other

     

       3823
       3823
       +
                 characters MAY also be replaced with an HTML entity form.

     

       3824
       3824
       +
       

     

       3825
       3825
       +
             2.  The matching words/phrases from the filter are wrapped in HTML

     

       3826
       3826
       +
                 "<mark></mark>" tags.

     

       3827
       3827
       +
       

     

       3828
       3828
       +
             If the subject does not match text from the filter, this property

     

       3829
       3829
       +
             is null.

     

       3830
       3830
       +
       

     

       3831
       3831
       +
          o  preview: "String|null"

     

       3832
       3832
       +
       

     

       3833
       3833
       +
             If text from the filter matches the plaintext or HTML body, this

     

       3834
       3834
       +
             is the relevant section of the body (converted to plaintext if

     

       3835
       3835
       +
             originally HTML), with the same transformations as the "subject"

     

       3836
       3836
       +
             property.  It MUST NOT be bigger than 255 octets in size.  If the

     

       3837
       3837
       +
             body does not contain a match for the text from the filter, this

     

       3838
       3838
       +
             property is null.

     

       3839
       3839
       +
       

     

       3840
       3840
       +
          What is a relevant section of the body for preview is server defined.

     

       3841
       3841
       +
          If the server is unable to determine search snippets, it MUST return

     

       3842
       3842
       +
          null for both the "subject" and "preview" properties.

     

       3843
       3843
       +
       

     

       3844
       3844
       +
          Note that unlike most data types, a SearchSnippet DOES NOT have a

     

       3845
       3845
       +
          property called "id".

     

       3846
       3846
       +
       

     

       3847
       3847
       +
          The following JMAP method is supported.

     

       3848
       3848
       +
       

     

       3849
       3849
       +
       5.1.  SearchSnippet/get

     

       3850
       3850
       +
       

     

       3851
       3851
       +
          To fetch search snippets, make a call to "SearchSnippet/get".  It

     

       3852
       3852
       +
          takes the following arguments:

     

       3853
       3853
       +
       

     

       3854
       3854
       +
          o  accountId: "Id"

     

       3855
       3855
       +
       

     

       3856
       3856
       +
             The id of the account to use.

     

       3857
       3857
       +
       

     

       3858
       3858
       +
          o  filter: "FilterOperator|FilterCondition|null"

     

       3859
       3859
       +
       

     

       3860
       3860
       +
             The same filter as passed to "Email/query"; see the description of

     

       3861
       3861
       +
             this method in Section 4.4 for details.

     

       3862
       3862
       +
       

     

       3863
       3863
       +
       

     

       3864
       3864
       +
       

     

       3865
       3865
       +
       

     

       3866
       3866
       +
       Jenkins & Newman             Standards Track                   [Page 69]

     

       3867
       3867
       +
       

     

       3868
       3868
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3869
       3869
       +
       

     

       3870
       3870
       +
       

     

       3871
       3871
       +
          o  emailIds: "Id[]"

     

       3872
       3872
       +
       

     

       3873
       3873
       +
             The ids of the Emails to fetch snippets for.

     

       3874
       3874
       +
       

     

       3875
       3875
       +
          The response has the following arguments:

     

       3876
       3876
       +
       

     

       3877
       3877
       +
          o  accountId: "Id"

     

       3878
       3878
       +
       

     

       3879
       3879
       +
             The id of the account used for the call.

     

       3880
       3880
       +
       

     

       3881
       3881
       +
          o  list: "SearchSnippet[]"

     

       3882
       3882
       +
       

     

       3883
       3883
       +
             An array of SearchSnippet objects for the requested Email ids.

     

       3884
       3884
       +
             This may not be in the same order as the ids that were in the

     

       3885
       3885
       +
             request.

     

       3886
       3886
       +
       

     

       3887
       3887
       +
          o  notFound: "Id[]|null"

     

       3888
       3888
       +
       

     

       3889
       3889
       +
             An array of Email ids requested that could not be found, or null

     

       3890
       3890
       +
             if all ids were found.

     

       3891
       3891
       +
       

     

       3892
       3892
       +
          As the search snippets are derived from the message content and the

     

       3893
       3893
       +
          algorithm for doing so could change over time, fetching the same

     

       3894
       3894
       +
          snippets a second time MAY return a different result.  However, the

     

       3895
       3895
       +
          previous value is not considered incorrect, so there is no state

     

       3896
       3896
       +
          string or update mechanism needed.

     

       3897
       3897
       +
       

     

       3898
       3898
       +
          The following additional errors may be returned instead of the

     

       3899
       3899
       +
          "SearchSnippet/get" response:

     

       3900
       3900
       +
       

     

       3901
       3901
       +
          "requestTooLarge": The number of "emailIds" requested by the client

     

       3902
       3902
       +
          exceeds the maximum number the server is willing to process in a

     

       3903
       3903
       +
          single method call.

     

       3904
       3904
       +
       

     

       3905
       3905
       +
          "unsupportedFilter": The server is unable to process the given

     

       3906
       3906
       +
          "filter" for any reason.

     

       3907
       3907
       +
       

     

       3908
       3908
       +
       

     

       3909
       3909
       +
       

     

       3910
       3910
       +
       

     

       3911
       3911
       +
       

     

       3912
       3912
       +
       

     

       3913
       3913
       +
       

     

       3914
       3914
       +
       

     

       3915
       3915
       +
       

     

       3916
       3916
       +
       

     

       3917
       3917
       +
       

     

       3918
       3918
       +
       

     

       3919
       3919
       +
       

     

       3920
       3920
       +
       

     

       3921
       3921
       +
       

     

       3922
       3922
       +
       Jenkins & Newman             Standards Track                   [Page 70]

     

       3923
       3923
       +
       

     

       3924
       3924
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3925
       3925
       +
       

     

       3926
       3926
       +
       

     

       3927
       3927
       +
       5.2.  Example

     

       3928
       3928
       +
       

     

       3929
       3929
       +
          Here, we did an "Email/query" to search for any Email in the account

     

       3930
       3930
       +
          containing the word "foo"; now, we are fetching the search snippets

     

       3931
       3931
       +
          for some of the ids that were returned in the results:

     

       3932
       3932
       +
       

     

       3933
       3933
       +
                            [[ "SearchSnippet/get", {

     

       3934
       3934
       +
                              "accountId": "ue150411c",

     

       3935
       3935
       +
                              "filter": {

     

       3936
       3936
       +
                                "text": "foo"

     

       3937
       3937
       +
                              },

     

       3938
       3938
       +
                              "emailIds": [

     

       3939
       3939
       +
                                "M44200ec123de277c0c1ce69c",

     

       3940
       3940
       +
                                "M7bcbcb0b58d7729686e83d99",

     

       3941
       3941
       +
                                "M28d12783a0969584b6deaac0",

     

       3942
       3942
       +
                                ...

     

       3943
       3943
       +
                              ]

     

       3944
       3944
       +
                            }, "0" ]]

     

       3945
       3945
       +
       

     

       3946
       3946
       +
          Example response:

     

       3947
       3947
       +
       

     

       3948
       3948
       +
          [[ "SearchSnippet/get", {

     

       3949
       3949
       +
            "accountId": "ue150411c",

     

       3950
       3950
       +
            "list": [{

     

       3951
       3951
       +
                "emailId": "M44200ec123de277c0c1ce69c",

     

       3952
       3952
       +
                "subject": null,

     

       3953
       3953
       +
                "preview": null

     

       3954
       3954
       +
            }, {

     

       3955
       3955
       +
                "emailId": "M7bcbcb0b58d7729686e83d99",

     

       3956
       3956
       +
                "subject": "The <mark>Foo</mark>sball competition",

     

       3957
       3957
       +
                "preview": "...year the <mark>foo</mark>sball competition will

     

       3958
       3958
       +
                  be held in the Stadium de ..."

     

       3959
       3959
       +
            }, {

     

       3960
       3960
       +
                "emailId": "M28d12783a0969584b6deaac0",

     

       3961
       3961
       +
                "subject": null,

     

       3962
       3962
       +
                "preview": "...the <mark>Foo</mark>/bar method results often

     

       3963
       3963
       +
                  returns &lt;1 widget rather than the complete..."

     

       3964
       3964
       +
            },

     

       3965
       3965
       +
            ...

     

       3966
       3966
       +
            ],

     

       3967
       3967
       +
            "notFound": null

     

       3968
       3968
       +
          }, "0" ]]

     

       3969
       3969
       +
       

     

       3970
       3970
       +
       

     

       3971
       3971
       +
       

     

       3972
       3972
       +
       

     

       3973
       3973
       +
       

     

       3974
       3974
       +
       

     

       3975
       3975
       +
       

     

       3976
       3976
       +
       

     

       3977
       3977
       +
       

     

       3978
       3978
       +
       Jenkins & Newman             Standards Track                   [Page 71]

     

       3979
       3979
       +
       

     

       3980
       3980
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       3981
       3981
       +
       

     

       3982
       3982
       +
       

     

       3983
       3983
       +
       6.  Identities

     

       3984
       3984
       +
       

     

       3985
       3985
       +
          An *Identity* object stores information about an email address or

     

       3986
       3986
       +
          domain the user may send from.  It has the following properties:

     

       3987
       3987
       +
       

     

       3988
       3988
       +
          o  id: "Id" (immutable; server-set)

     

       3989
       3989
       +
       

     

       3990
       3990
       +
             The id of the Identity.

     

       3991
       3991
       +
       

     

       3992
       3992
       +
          o  name: "String" (default: "")

     

       3993
       3993
       +
       

     

       3994
       3994
       +
             The "From" name the client SHOULD use when creating a new Email

     

       3995
       3995
       +
             from this Identity.

     

       3996
       3996
       +
       

     

       3997
       3997
       +
          o  email: "String" (immutable)

     

       3998
       3998
       +
       

     

       3999
       3999
       +
             The "From" email address the client MUST use when creating a new

     

       4000
       4000
       +
             Email from this Identity.  If the "mailbox" part of the address

     

       4001
       4001
       +
             (the section before the "@") is the single character "*" (e.g.,

     

       4002
       4002
       +
             "*@example.com"), the client may use any valid address ending in

     

       4003
       4003
       +
             that domain (e.g., "foo@example.com").

     

       4004
       4004
       +
       

     

       4005
       4005
       +
          o  replyTo: "EmailAddress[]|null" (default: null)

     

       4006
       4006
       +
       

     

       4007
       4007
       +
             The Reply-To value the client SHOULD set when creating a new Email

     

       4008
       4008
       +
             from this Identity.

     

       4009
       4009
       +
       

     

       4010
       4010
       +
          o  bcc: "EmailAddress[]|null" (default: null)

     

       4011
       4011
       +
       

     

       4012
       4012
       +
             The Bcc value the client SHOULD set when creating a new Email from

     

       4013
       4013
       +
             this Identity.

     

       4014
       4014
       +
       

     

       4015
       4015
       +
          o  textSignature: "String" (default: "")

     

       4016
       4016
       +
       

     

       4017
       4017
       +
             A signature the client SHOULD insert into new plaintext messages

     

       4018
       4018
       +
             that will be sent from this Identity.  Clients MAY ignore this

     

       4019
       4019
       +
             and/or combine this with a client-specific signature preference.

     

       4020
       4020
       +
       

     

       4021
       4021
       +
          o  htmlSignature: "String" (default: "")

     

       4022
       4022
       +
       

     

       4023
       4023
       +
             A signature the client SHOULD insert into new HTML messages that

     

       4024
       4024
       +
             will be sent from this Identity.  This text MUST be an HTML

     

       4025
       4025
       +
             snippet to be inserted into the "<body></body>" section of the

     

       4026
       4026
       +
             HTML.  Clients MAY ignore this and/or combine this with a client-

     

       4027
       4027
       +
             specific signature preference.

     

       4028
       4028
       +
       

     

       4029
       4029
       +
       

     

       4030
       4030
       +
       

     

       4031
       4031
       +
       

     

       4032
       4032
       +
       

     

       4033
       4033
       +
       

     

       4034
       4034
       +
       Jenkins & Newman             Standards Track                   [Page 72]

     

       4035
       4035
       +
       

     

       4036
       4036
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4037
       4037
       +
       

     

       4038
       4038
       +
       

     

       4039
       4039
       +
          o  mayDelete: "Boolean" (server-set)

     

       4040
       4040
       +
       

     

       4041
       4041
       +
             Is the user allowed to delete this Identity?  Servers may wish to

     

       4042
       4042
       +
             set this to false for the user's username or other default

     

       4043
       4043
       +
             address.  Attempts to destroy an Identity with "mayDelete: false"

     

       4044
       4044
       +
             will be rejected with a standard "forbidden" SetError.

     

       4045
       4045
       +
       

     

       4046
       4046
       +
          See the "Addresses" header form description in the Email object

     

       4047
       4047
       +
          (Section 4.1.2.3) for the definition of EmailAddress.

     

       4048
       4048
       +
       

     

       4049
       4049
       +
          Multiple identities with the same email address MAY exist, to allow

     

       4050
       4050
       +
          for different settings the user wants to pick between (for example,

     

       4051
       4051
       +
          with different names/signatures).

     

       4052
       4052
       +
       

     

       4053
       4053
       +
          The following JMAP methods are supported.

     

       4054
       4054
       +
       

     

       4055
       4055
       +
       6.1.  Identity/get

     

       4056
       4056
       +
       

     

       4057
       4057
       +
          This is a standard "/get" method as described in [RFC8620],

     

       4058
       4058
       +
          Section 5.1.  The "ids" argument may be null to fetch all at once.

     

       4059
       4059
       +
       

     

       4060
       4060
       +
       6.2.  Identity/changes

     

       4061
       4061
       +
       

     

       4062
       4062
       +
          This is a standard "/changes" method as described in [RFC8620],

     

       4063
       4063
       +
          Section 5.2.

     

       4064
       4064
       +
       

     

       4065
       4065
       +
       6.3.  Identity/set

     

       4066
       4066
       +
       

     

       4067
       4067
       +
          This is a standard "/set" method as described in [RFC8620],

     

       4068
       4068
       +
          Section 5.3.  The following extra SetError types are defined:

     

       4069
       4069
       +
       

     

       4070
       4070
       +
          For "create":

     

       4071
       4071
       +
       

     

       4072
       4072
       +
          o  "forbiddenFrom": The user is not allowed to send from the address

     

       4073
       4073
       +
             given as the "email" property of the Identity.

     

       4074
       4074
       +
       

     

       4075
       4075
       +
       6.4.  Example

     

       4076
       4076
       +
       

     

       4077
       4077
       +
          Request:

     

       4078
       4078
       +
       

     

       4079
       4079
       +
                                  [ "Identity/get", {

     

       4080
       4080
       +
                                    "accountId": "acme"

     

       4081
       4081
       +
                                  }, "0" ]

     

       4082
       4082
       +
       

     

       4083
       4083
       +
       

     

       4084
       4084
       +
       

     

       4085
       4085
       +
       

     

       4086
       4086
       +
       

     

       4087
       4087
       +
       

     

       4088
       4088
       +
       

     

       4089
       4089
       +
       

     

       4090
       4090
       +
       Jenkins & Newman             Standards Track                   [Page 73]

     

       4091
       4091
       +
       

     

       4092
       4092
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4093
       4093
       +
       

     

       4094
       4094
       +
       

     

       4095
       4095
       +
          with response:

     

       4096
       4096
       +
       

     

       4097
       4097
       +
               [ "Identity/get", {

     

       4098
       4098
       +
                 "accountId": "acme",

     

       4099
       4099
       +
                 "state": "99401312ae-11-333",

     

       4100
       4100
       +
                 "list": [

     

       4101
       4101
       +
                   {

     

       4102
       4102
       +
                     "id": "XD-3301-222-11_22AAz",

     

       4103
       4103
       +
                     "name": "Joe Bloggs",

     

       4104
       4104
       +
                     "email": "joe@example.com",

     

       4105
       4105
       +
                     "replyTo": null,

     

       4106
       4106
       +
                     "bcc": [{

     

       4107
       4107
       +
                       "name": null,

     

       4108
       4108
       +
                       "email": "joe+archive@example.com"

     

       4109
       4109
       +
                     }],

     

       4110
       4110
       +
                     "textSignature": "-- \nJoe Bloggs\nMaster of Email",

     

       4111
       4111
       +
                     "htmlSignature": "<div><b>Joe Bloggs</b></div>

     

       4112
       4112
       +
                       <div>Master of Email</div>",

     

       4113
       4113
       +
                     "mayDelete": false

     

       4114
       4114
       +
                   },

     

       4115
       4115
       +
                   {

     

       4116
       4116
       +
                     "id": "XD-9911312-11_22AAz",

     

       4117
       4117
       +
                     "name": "Joe B",

     

       4118
       4118
       +
                     "email": "*@example.com",

     

       4119
       4119
       +
                     "replyTo": null,

     

       4120
       4120
       +
                     "bcc": null,

     

       4121
       4121
       +
                     "textSignature": "",

     

       4122
       4122
       +
                     "htmlSignature": "",

     

       4123
       4123
       +
                     "mayDelete": true

     

       4124
       4124
       +
                   }

     

       4125
       4125
       +
                 ],

     

       4126
       4126
       +
                 "notFound": []

     

       4127
       4127
       +
               }, "0" ]

     

       4128
       4128
       +
       

     

       4129
       4129
       +
       7.  Email Submission

     

       4130
       4130
       +
       

     

       4131
       4131
       +
          An *EmailSubmission* object represents the submission of an Email for

     

       4132
       4132
       +
          delivery to one or more recipients.  It has the following properties:

     

       4133
       4133
       +
       

     

       4134
       4134
       +
          o  id: "Id" (immutable; server-set)

     

       4135
       4135
       +
       

     

       4136
       4136
       +
             The id of the EmailSubmission.

     

       4137
       4137
       +
       

     

       4138
       4138
       +
          o  identityId: "Id" (immutable)

     

       4139
       4139
       +
       

     

       4140
       4140
       +
             The id of the Identity to associate with this submission.

     

       4141
       4141
       +
       

     

       4142
       4142
       +
       

     

       4143
       4143
       +
       

     

       4144
       4144
       +
       

     

       4145
       4145
       +
       

     

       4146
       4146
       +
       Jenkins & Newman             Standards Track                   [Page 74]

     

       4147
       4147
       +
       

     

       4148
       4148
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4149
       4149
       +
       

     

       4150
       4150
       +
       

     

       4151
       4151
       +
          o  emailId: "Id" (immutable)

     

       4152
       4152
       +
       

     

       4153
       4153
       +
             The id of the Email to send.  The Email being sent does not have

     

       4154
       4154
       +
             to be a draft, for example, when "redirecting" an existing Email

     

       4155
       4155
       +
             to a different address.

     

       4156
       4156
       +
       

     

       4157
       4157
       +
          o  threadId: "Id" (immutable; server-set)

     

       4158
       4158
       +
       

     

       4159
       4159
       +
             The Thread id of the Email to send.  This is set by the server to

     

       4160
       4160
       +
             the "threadId" property of the Email referenced by the "emailId".

     

       4161
       4161
       +
       

     

       4162
       4162
       +
          o  envelope: "Envelope|null" (immutable)

     

       4163
       4163
       +
       

     

       4164
       4164
       +
             Information for use when sending via SMTP.  An *Envelope* object

     

       4165
       4165
       +
             has the following properties:

     

       4166
       4166
       +
       

     

       4167
       4167
       +
             *  mailFrom: "Address"

     

       4168
       4168
       +
       

     

       4169
       4169
       +
                The email address to use as the return address in the SMTP

     

       4170
       4170
       +
                submission, plus any parameters to pass with the MAIL FROM

     

       4171
       4171
       +
                address.  The JMAP server MAY allow the address to be the empty

     

       4172
       4172
       +
                string.

     

       4173
       4173
       +
       

     

       4174
       4174
       +
                When a JMAP server performs an SMTP message submission, it MAY

     

       4175
       4175
       +
                use the same id string for the ENVID parameter [RFC3461] and

     

       4176
       4176
       +
                the EmailSubmission object id.  Servers that do this MAY

     

       4177
       4177
       +
                replace a client-provided value for ENVID with a server-

     

       4178
       4178
       +
                provided value.

     

       4179
       4179
       +
       

     

       4180
       4180
       +
             *  rcptTo: "Address[]"

     

       4181
       4181
       +
       

     

       4182
       4182
       +
                The email addresses to send the message to, and any RCPT TO

     

       4183
       4183
       +
                parameters to pass with the recipient.

     

       4184
       4184
       +
       

     

       4185
       4185
       +
             An *Address* object has the following properties:

     

       4186
       4186
       +
       

     

       4187
       4187
       +
             *  email: "String"

     

       4188
       4188
       +
       

     

       4189
       4189
       +
                The email address being represented by the object.  This is a

     

       4190
       4190
       +
                "Mailbox" as used in the Reverse-path or Forward-path of the

     

       4191
       4191
       +
                MAIL FROM or RCPT TO command in [RFC5321].

     

       4192
       4192
       +
       

     

       4193
       4193
       +
             *  parameters: "Object|null"

     

       4194
       4194
       +
       

     

       4195
       4195
       +
                Any parameters to send with the email address (either mail-

     

       4196
       4196
       +
                parameter or rcpt-parameter as appropriate, as specified in

     

       4197
       4197
       +
                [RFC5321]).  If supplied, each key in the object is a parameter

     

       4198
       4198
       +
                name, and the value is either the parameter value (type

     

       4199
       4199
       +
       

     

       4200
       4200
       +
       

     

       4201
       4201
       +
       

     

       4202
       4202
       +
       Jenkins & Newman             Standards Track                   [Page 75]

     

       4203
       4203
       +
       

     

       4204
       4204
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4205
       4205
       +
       

     

       4206
       4206
       +
       

     

       4207
       4207
       +
                "String") or null if the parameter does not take a value.  For

     

       4208
       4208
       +
                both name and value, any xtext or unitext encodings are removed

     

       4209
       4209
       +
                (see [RFC3461] and [RFC6533]) and JSON string encoding is

     

       4210
       4210
       +
                applied.

     

       4211
       4211
       +
       

     

       4212
       4212
       +
             If the "envelope" property is null or omitted on creation, the

     

       4213
       4213
       +
             server MUST generate this from the referenced Email as follows:

     

       4214
       4214
       +
       

     

       4215
       4215
       +
             *  "mailFrom": The email address in the Sender header field, if

     

       4216
       4216
       +
                present; otherwise, it's the email address in the From header

     

       4217
       4217
       +
                field, if present.  In either case, no parameters are added.

     

       4218
       4218
       +
       

     

       4219
       4219
       +
                If multiple addresses are present in one of these header

     

       4220
       4220
       +
                fields, or there is more than one Sender/From header field, the

     

       4221
       4221
       +
                server SHOULD reject the EmailSubmission as invalid; otherwise,

     

       4222
       4222
       +
                it MUST take the first address in the last Sender/From header

     

       4223
       4223
       +
                field.

     

       4224
       4224
       +
       

     

       4225
       4225
       +
                If the address found from this is not allowed by the Identity

     

       4226
       4226
       +
                associated with this submission, the "email" property from the

     

       4227
       4227
       +
                Identity MUST be used instead.

     

       4228
       4228
       +
       

     

       4229
       4229
       +
             *  "rcptTo": The deduplicated set of email addresses from the To,

     

       4230
       4230
       +
                Cc, and Bcc header fields, if present, with no parameters for

     

       4231
       4231
       +
                any of them.

     

       4232
       4232
       +
       

     

       4233
       4233
       +
          o  sendAt: "UTCDate" (immutable; server-set)

     

       4234
       4234
       +
       

     

       4235
       4235
       +
             The date the submission was/will be released for delivery.  If the

     

       4236
       4236
       +
             client successfully used FUTURERELEASE [RFC4865] with the

     

       4237
       4237
       +
             submission, this MUST be the time when the server will release the

     

       4238
       4238
       +
             message; otherwise, it MUST be the time the EmailSubmission was

     

       4239
       4239
       +
             created.

     

       4240
       4240
       +
       

     

       4241
       4241
       +
          o  undoStatus: "String"

     

       4242
       4242
       +
       

     

       4243
       4243
       +
             This represents whether the submission may be canceled.  This is

     

       4244
       4244
       +
             server set on create and MUST be one of the following values:

     

       4245
       4245
       +
       

     

       4246
       4246
       +
             *  "pending": It may be possible to cancel this submission.

     

       4247
       4247
       +
       

     

       4248
       4248
       +
             *  "final": The message has been relayed to at least one recipient

     

       4249
       4249
       +
                in a manner that cannot be recalled.  It is no longer possible

     

       4250
       4250
       +
                to cancel this submission.

     

       4251
       4251
       +
       

     

       4252
       4252
       +
             *  "canceled": The submission was canceled and will not be

     

       4253
       4253
       +
                delivered to any recipient.

     

       4254
       4254
       +
       

     

       4255
       4255
       +
       

     

       4256
       4256
       +
       

     

       4257
       4257
       +
       

     

       4258
       4258
       +
       Jenkins & Newman             Standards Track                   [Page 76]

     

       4259
       4259
       +
       

     

       4260
       4260
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4261
       4261
       +
       

     

       4262
       4262
       +
       

     

       4263
       4263
       +
             On systems that do not support unsending, the value of this

     

       4264
       4264
       +
             property will always be "final".  On systems that do support

     

       4265
       4265
       +
             canceling submission, it will start as "pending" and MAY

     

       4266
       4266
       +
             transition to "final" when the server knows it definitely cannot

     

       4267
       4267
       +
             recall the message, but it MAY just remain "pending".  If in

     

       4268
       4268
       +
             pending state, a client can attempt to cancel the submission by

     

       4269
       4269
       +
             setting this property to "canceled"; if the update succeeds, the

     

       4270
       4270
       +
             submission was successfully canceled, and the message has not been

     

       4271
       4271
       +
             delivered to any of the original recipients.

     

       4272
       4272
       +
       

     

       4273
       4273
       +
          o  deliveryStatus: "String[DeliveryStatus]|null" (server-set)

     

       4274
       4274
       +
       

     

       4275
       4275
       +
             This represents the delivery status for each of the submission's

     

       4276
       4276
       +
             recipients, if known.  This property MAY not be supported by all

     

       4277
       4277
       +
             servers, in which case it will remain null.  Servers that support

     

       4278
       4278
       +
             it SHOULD update the EmailSubmission object each time the status

     

       4279
       4279
       +
             of any of the recipients changes, even if some recipients are

     

       4280
       4280
       +
             still being retried.

     

       4281
       4281
       +
       

     

       4282
       4282
       +
             This value is a map from the email address of each recipient to a

     

       4283
       4283
       +
             DeliveryStatus object.

     

       4284
       4284
       +
       

     

       4285
       4285
       +
             A *DeliveryStatus* object has the following properties:

     

       4286
       4286
       +
       

     

       4287
       4287
       +
             *  smtpReply: "String"

     

       4288
       4288
       +
       

     

       4289
       4289
       +
                The SMTP reply string returned for this recipient when the

     

       4290
       4290
       +
                server last tried to relay the message, or in a later Delivery

     

       4291
       4291
       +
                Status Notification (DSN, as defined in [RFC3464]) response for

     

       4292
       4292
       +
                the message.  This SHOULD be the response to the RCPT TO stage,

     

       4293
       4293
       +
                unless this was accepted and the message as a whole was

     

       4294
       4294
       +
                rejected at the end of the DATA stage, in which case the DATA

     

       4295
       4295
       +
                stage reply SHOULD be used instead.

     

       4296
       4296
       +
       

     

       4297
       4297
       +
                Multi-line SMTP responses should be concatenated to a single

     

       4298
       4298
       +
                string as follows:

     

       4299
       4299
       +
       

     

       4300
       4300
       +
                +  The hyphen following the SMTP code on all but the last line

     

       4301
       4301
       +
                   is replaced with a space.

     

       4302
       4302
       +
       

     

       4303
       4303
       +
                +  Any prefix in common with the first line is stripped from

     

       4304
       4304
       +
                   lines after the first.

     

       4305
       4305
       +
       

     

       4306
       4306
       +
                +  CRLF is replaced by a space.

     

       4307
       4307
       +
       

     

       4308
       4308
       +
       

     

       4309
       4309
       +
       

     

       4310
       4310
       +
       

     

       4311
       4311
       +
       

     

       4312
       4312
       +
       

     

       4313
       4313
       +
       

     

       4314
       4314
       +
       Jenkins & Newman             Standards Track                   [Page 77]

     

       4315
       4315
       +
       

     

       4316
       4316
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4317
       4317
       +
       

     

       4318
       4318
       +
       

     

       4319
       4319
       +
                For example:

     

       4320
       4320
       +
       

     

       4321
       4321
       +
                 550-5.7.1 Our system has detected that this message is

     

       4322
       4322
       +
                 550 5.7.1 likely spam.

     

       4323
       4323
       +
       

     

       4324
       4324
       +
                would become:

     

       4325
       4325
       +
       

     

       4326
       4326
       +
           550 5.7.1 Our system has detected that this message is likely spam.

     

       4327
       4327
       +
       

     

       4328
       4328
       +
                For messages relayed via an alternative to SMTP, the server MAY

     

       4329
       4329
       +
                generate a synthetic string representing the status instead.

     

       4330
       4330
       +
                If it does this, the string MUST be of the following form:

     

       4331
       4331
       +
       

     

       4332
       4332
       +
                +  A 3-digit SMTP reply code, as defined in [RFC5321],

     

       4333
       4333
       +
                   Section 4.2.3.

     

       4334
       4334
       +
       

     

       4335
       4335
       +
                +  Then a single space character.

     

       4336
       4336
       +
       

     

       4337
       4337
       +
                +  Then an SMTP Enhanced Mail System Status Code as defined in

     

       4338
       4338
       +
                   [RFC3463], with a registry defined in [RFC5248].

     

       4339
       4339
       +
       

     

       4340
       4340
       +
                +  Then a single space character.

     

       4341
       4341
       +
       

     

       4342
       4342
       +
                +  Then an implementation-specific information string with a

     

       4343
       4343
       +
                   human-readable explanation of the response.

     

       4344
       4344
       +
       

     

       4345
       4345
       +
             *  delivered: "String"

     

       4346
       4346
       +
       

     

       4347
       4347
       +
                Represents whether the message has been successfully delivered

     

       4348
       4348
       +
                to the recipient.  This MUST be one of the following values:

     

       4349
       4349
       +
       

     

       4350
       4350
       +
                +  "queued": The message is in a local mail queue and the

     

       4351
       4351
       +
                   status will change once it exits the local mail queues.  The

     

       4352
       4352
       +
                   "smtpReply" property may still change.

     

       4353
       4353
       +
       

     

       4354
       4354
       +
                +  "yes": The message was successfully delivered to the mail

     

       4355
       4355
       +
                   store of the recipient.  The "smtpReply" property is final.

     

       4356
       4356
       +
       

     

       4357
       4357
       +
                +  "no": Delivery to the recipient permanently failed.  The

     

       4358
       4358
       +
                   "smtpReply" property is final.

     

       4359
       4359
       +
       

     

       4360
       4360
       +
                +  "unknown": The final delivery status is unknown, (e.g., it

     

       4361
       4361
       +
                   was relayed to an external machine and no further

     

       4362
       4362
       +
                   information is available).  The "smtpReply" property may

     

       4363
       4363
       +
                   still change if a DSN arrives.

     

       4364
       4364
       +
       

     

       4365
       4365
       +
       

     

       4366
       4366
       +
       

     

       4367
       4367
       +
       

     

       4368
       4368
       +
       

     

       4369
       4369
       +
       

     

       4370
       4370
       +
       Jenkins & Newman             Standards Track                   [Page 78]

     

       4371
       4371
       +
       

     

       4372
       4372
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4373
       4373
       +
       

     

       4374
       4374
       +
       

     

       4375
       4375
       +
                Note that successful relaying to an external SMTP server SHOULD

     

       4376
       4376
       +
                NOT be taken as an indication that the message has successfully

     

       4377
       4377
       +
                reached the final mail store.  In this case though, the server

     

       4378
       4378
       +
                may receive a DSN response, if requested.

     

       4379
       4379
       +
       

     

       4380
       4380
       +
                If a DSN is received for the recipient with Action equal to

     

       4381
       4381
       +
                "delivered", as per [RFC3464], Section 2.3.3, then the

     

       4382
       4382
       +
                "delivered" property SHOULD be set to "yes"; if the Action

     

       4383
       4383
       +
                equals "failed", the property SHOULD be set to "no".  Receipt

     

       4384
       4384
       +
                of any other DSN SHOULD NOT affect this property.

     

       4385
       4385
       +
       

     

       4386
       4386
       +
                The server MAY also set this property based on other feedback

     

       4387
       4387
       +
                channels.

     

       4388
       4388
       +
       

     

       4389
       4389
       +
             *  displayed: "String"

     

       4390
       4390
       +
       

     

       4391
       4391
       +
                Represents whether the message has been displayed to the

     

       4392
       4392
       +
                recipient.  This MUST be one of the following values:

     

       4393
       4393
       +
       

     

       4394
       4394
       +
                +  "unknown": The display status is unknown.  This is the

     

       4395
       4395
       +
                   initial value.

     

       4396
       4396
       +
       

     

       4397
       4397
       +
                +  "yes": The recipient's system claims the message content has

     

       4398
       4398
       +
                   been displayed to the recipient.  Note that there is no

     

       4399
       4399
       +
                   guarantee that the recipient has noticed, read, or

     

       4400
       4400
       +
                   understood the content.

     

       4401
       4401
       +
       

     

       4402
       4402
       +
                If a Message Disposition Notification (MDN) is received for

     

       4403
       4403
       +
                this recipient with Disposition-Type (as per [RFC8098],

     

       4404
       4404
       +
                Section 3.2.6.2) equal to "displayed", this property SHOULD be

     

       4405
       4405
       +
                set to "yes".

     

       4406
       4406
       +
       

     

       4407
       4407
       +
                The server MAY also set this property based on other feedback

     

       4408
       4408
       +
                channels.

     

       4409
       4409
       +
       

     

       4410
       4410
       +
          o  dsnBlobIds: "Id[]" (server-set)

     

       4411
       4411
       +
       

     

       4412
       4412
       +
             A list of blob ids for DSNs [RFC3464] received for this

     

       4413
       4413
       +
             submission, in order of receipt, oldest first.  The blob is the

     

       4414
       4414
       +
             whole MIME message (with a top-level content-type of "multipart/

     

       4415
       4415
       +
             report"), as received.

     

       4416
       4416
       +
       

     

       4417
       4417
       +
          o  mdnBlobIds: "Id[]" (server-set)

     

       4418
       4418
       +
       

     

       4419
       4419
       +
             A list of blob ids for MDNs [RFC8098] received for this

     

       4420
       4420
       +
             submission, in order of receipt, oldest first.  The blob is the

     

       4421
       4421
       +
             whole MIME message (with a top-level content-type of "multipart/

     

       4422
       4422
       +
             report"), as received.

     

       4423
       4423
       +
       

     

       4424
       4424
       +
       

     

       4425
       4425
       +
       

     

       4426
       4426
       +
       Jenkins & Newman             Standards Track                   [Page 79]

     

       4427
       4427
       +
       

     

       4428
       4428
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4429
       4429
       +
       

     

       4430
       4430
       +
       

     

       4431
       4431
       +
          JMAP servers MAY choose not to expose DSN and MDN responses as Email

     

       4432
       4432
       +
          objects if they correlate to an EmailSubmission object.  It SHOULD

     

       4433
       4433
       +
          only do this if it exposes them in the "dsnBlobIds" and "mdnblobIds"

     

       4434
       4434
       +
          fields instead, and it expects the user to be using clients capable

     

       4435
       4435
       +
          of fetching and displaying delivery status via the EmailSubmission

     

       4436
       4436
       +
          object.

     

       4437
       4437
       +
       

     

       4438
       4438
       +
          For efficiency, a server MAY destroy EmailSubmission objects at any

     

       4439
       4439
       +
          time after the message is successfully sent or after it has finished

     

       4440
       4440
       +
          retrying to send the message.  For very basic SMTP proxies, this MAY

     

       4441
       4441
       +
          be immediately after creation, as it has no way to assign a real id

     

       4442
       4442
       +
          and return the information again if fetched later.

     

       4443
       4443
       +
       

     

       4444
       4444
       +
          The following JMAP methods are supported.

     

       4445
       4445
       +
       

     

       4446
       4446
       +
       7.1.  EmailSubmission/get

     

       4447
       4447
       +
       

     

       4448
       4448
       +
          This is a standard "/get" method as described in [RFC8620],

     

       4449
       4449
       +
          Section 5.1.

     

       4450
       4450
       +
       

     

       4451
       4451
       +
       7.2.  EmailSubmission/changes

     

       4452
       4452
       +
       

     

       4453
       4453
       +
          This is a standard "/changes" method as described in [RFC8620],

     

       4454
       4454
       +
          Section 5.2.

     

       4455
       4455
       +
       

     

       4456
       4456
       +
       7.3.  EmailSubmission/query

     

       4457
       4457
       +
       

     

       4458
       4458
       +
          This is a standard "/query" method as described in [RFC8620],

     

       4459
       4459
       +
          Section 5.5.

     

       4460
       4460
       +
       

     

       4461
       4461
       +
          A *FilterCondition* object has the following properties, any of which

     

       4462
       4462
       +
          may be omitted:

     

       4463
       4463
       +
       

     

       4464
       4464
       +
          o  identityIds: "Id[]"

     

       4465
       4465
       +
       

     

       4466
       4466
       +
             The EmailSubmission "identityId" property must be in this list to

     

       4467
       4467
       +
             match the condition.

     

       4468
       4468
       +
       

     

       4469
       4469
       +
          o  emailIds: "Id[]"

     

       4470
       4470
       +
       

     

       4471
       4471
       +
             The EmailSubmission "emailId" property must be in this list to

     

       4472
       4472
       +
             match the condition.

     

       4473
       4473
       +
       

     

       4474
       4474
       +
          o  threadIds: "Id[]"

     

       4475
       4475
       +
       

     

       4476
       4476
       +
             The EmailSubmission "threadId" property must be in this list to

     

       4477
       4477
       +
             match the condition.

     

       4478
       4478
       +
       

     

       4479
       4479
       +
       

     

       4480
       4480
       +
       

     

       4481
       4481
       +
       

     

       4482
       4482
       +
       Jenkins & Newman             Standards Track                   [Page 80]

     

       4483
       4483
       +
       

     

       4484
       4484
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4485
       4485
       +
       

     

       4486
       4486
       +
       

     

       4487
       4487
       +
          o  undoStatus: "String"

     

       4488
       4488
       +
       

     

       4489
       4489
       +
             The EmailSubmission "undoStatus" property must be identical to the

     

       4490
       4490
       +
             value given to match the condition.

     

       4491
       4491
       +
       

     

       4492
       4492
       +
          o  before: "UTCDate"

     

       4493
       4493
       +
       

     

       4494
       4494
       +
             The "sendAt" property of the EmailSubmission object must be before

     

       4495
       4495
       +
             this date-time to match the condition.

     

       4496
       4496
       +
       

     

       4497
       4497
       +
          o  after: "UTCDate"

     

       4498
       4498
       +
       

     

       4499
       4499
       +
             The "sendAt" property of the EmailSubmission object must be the

     

       4500
       4500
       +
             same as or after this date-time to match the condition.

     

       4501
       4501
       +
       

     

       4502
       4502
       +
          An EmailSubmission object matches the FilterCondition if and only if

     

       4503
       4503
       +
          all of the given conditions match.  If zero properties are specified,

     

       4504
       4504
       +
          it is automatically true for all objects.

     

       4505
       4505
       +
       

     

       4506
       4506
       +
          The following EmailSubmission properties MUST be supported for

     

       4507
       4507
       +
          sorting:

     

       4508
       4508
       +
       

     

       4509
       4509
       +
          o  "emailId"

     

       4510
       4510
       +
       

     

       4511
       4511
       +
          o  "threadId"

     

       4512
       4512
       +
       

     

       4513
       4513
       +
          o  "sentAt"

     

       4514
       4514
       +
       

     

       4515
       4515
       +
       7.4.  EmailSubmission/queryChanges

     

       4516
       4516
       +
       

     

       4517
       4517
       +
          This is a standard "/queryChanges" method as described in [RFC8620],

     

       4518
       4518
       +
          Section 5.6.

     

       4519
       4519
       +
       

     

       4520
       4520
       +
       7.5.  EmailSubmission/set

     

       4521
       4521
       +
       

     

       4522
       4522
       +
          This is a standard "/set" method as described in [RFC8620],

     

       4523
       4523
       +
          Section 5.3 with the following two additional request arguments:

     

       4524
       4524
       +
       

     

       4525
       4525
       +
          o  onSuccessUpdateEmail: "Id[PatchObject]|null"

     

       4526
       4526
       +
       

     

       4527
       4527
       +
             A map of EmailSubmission id to an object containing properties to

     

       4528
       4528
       +
             update on the Email object referenced by the EmailSubmission if

     

       4529
       4529
       +
             the create/update/destroy succeeds.  (For references to

     

       4530
       4530
       +
             EmailSubmissions created in the same "/set" invocation, this is

     

       4531
       4531
       +
             equivalent to a creation-reference, so the id will be the creation

     

       4532
       4532
       +
             id prefixed with a "#".)

     

       4533
       4533
       +
       

     

       4534
       4534
       +
       

     

       4535
       4535
       +
       

     

       4536
       4536
       +
       

     

       4537
       4537
       +
       

     

       4538
       4538
       +
       Jenkins & Newman             Standards Track                   [Page 81]

     

       4539
       4539
       +
       

     

       4540
       4540
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4541
       4541
       +
       

     

       4542
       4542
       +
       

     

       4543
       4543
       +
          o  onSuccessDestroyEmail: "Id[]|null"

     

       4544
       4544
       +
       

     

       4545
       4545
       +
             A list of EmailSubmission ids for which the Email with the

     

       4546
       4546
       +
             corresponding "emailId" should be destroyed if the create/update/

     

       4547
       4547
       +
             destroy succeeds.  (For references to EmailSubmission creations,

     

       4548
       4548
       +
             this is equivalent to a creation-reference, so the id will be the

     

       4549
       4549
       +
             creation id prefixed with a "#".)

     

       4550
       4550
       +
       

     

       4551
       4551
       +
          After all create/update/destroy items in the "EmailSubmission/set"

     

       4552
       4552
       +
          invocation have been processed, a single implicit "Email/set" call

     

       4553
       4553
       +
          MUST be made to perform any changes requested in these two arguments.

     

       4554
       4554
       +
          The response to this MUST be returned after the "EmailSubmission/set"

     

       4555
       4555
       +
          response.

     

       4556
       4556
       +
       

     

       4557
       4557
       +
          An Email is sent by creating an EmailSubmission object.  When

     

       4558
       4558
       +
          processing each create, the server must check that the message is

     

       4559
       4559
       +
          valid, and the user has sufficient authorisation to send it.  If the

     

       4560
       4560
       +
          creation succeeds, the message will be sent to the recipients given

     

       4561
       4561
       +
          in the envelope "rcptTo" parameter.  The server MUST remove any Bcc

     

       4562
       4562
       +
          header field present on the message during delivery.  The server MAY

     

       4563
       4563
       +
          add or remove other header fields from the submitted message or make

     

       4564
       4564
       +
          further alterations in accordance with the server's policy during

     

       4565
       4565
       +
          delivery.

     

       4566
       4566
       +
       

     

       4567
       4567
       +
          If the referenced Email is destroyed at any point after the

     

       4568
       4568
       +
          EmailSubmission object is created, this MUST NOT change the behaviour

     

       4569
       4569
       +
          of the submission (i.e., it does not cancel a future send).  The

     

       4570
       4570
       +
          "emailId" and "threadId" properties of the EmailSubmission object

     

       4571
       4571
       +
          remain, but trying to fetch them (with a standard "Email/get" call)

     

       4572
       4572
       +
          will return a "notFound" error if the corresponding objects have been

     

       4573
       4573
       +
          destroyed.

     

       4574
       4574
       +
       

     

       4575
       4575
       +
          Similarly, destroying an EmailSubmission object MUST NOT affect the

     

       4576
       4576
       +
          deliveries it represents.  It purely removes the record of the

     

       4577
       4577
       +
          submission.  The server MAY automatically destroy EmailSubmission

     

       4578
       4578
       +
          objects after some time or in response to other triggers, and MAY

     

       4579
       4579
       +
          forbid the client from manually destroying EmailSubmission objects.

     

       4580
       4580
       +
       

     

       4581
       4581
       +
          If the message to be sent is larger than the server supports sending,

     

       4582
       4582
       +
          a standard "tooLarge" SetError MUST be returned.  A "maxSize"

     

       4583
       4583
       +
          "UnsignedInt" property MUST be present on the SetError specifying the

     

       4584
       4584
       +
          maximum size of a message that may be sent, in octets.

     

       4585
       4585
       +
       

     

       4586
       4586
       +
          If the Email or Identity id given cannot be found, the submission

     

       4587
       4587
       +
          creation is rejected with a standard "invalidProperties" SetError.

     

       4588
       4588
       +
       

     

       4589
       4589
       +
       

     

       4590
       4590
       +
       

     

       4591
       4591
       +
       

     

       4592
       4592
       +
       

     

       4593
       4593
       +
       

     

       4594
       4594
       +
       Jenkins & Newman             Standards Track                   [Page 82]

     

       4595
       4595
       +
       

     

       4596
       4596
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4597
       4597
       +
       

     

       4598
       4598
       +
       

     

       4599
       4599
       +
          The following extra SetError types are defined:

     

       4600
       4600
       +
       

     

       4601
       4601
       +
          For "create":

     

       4602
       4602
       +
       

     

       4603
       4603
       +
          o  "invalidEmail" - The Email to be sent is invalid in some way.  The

     

       4604
       4604
       +
             SetError SHOULD contain a property called "properties" of type

     

       4605
       4605
       +
             "String[]" that lists *all* the properties of the Email that were

     

       4606
       4606
       +
             invalid.

     

       4607
       4607
       +
       

     

       4608
       4608
       +
          o  "tooManyRecipients" - The envelope (supplied or generated) has

     

       4609
       4609
       +
             more recipients than the server allows.  A "maxRecipients"

     

       4610
       4610
       +
             "UnsignedInt" property MUST also be present on the SetError

     

       4611
       4611
       +
             specifying the maximum number of allowed recipients.

     

       4612
       4612
       +
       

     

       4613
       4613
       +
          o  "noRecipients" - The envelope (supplied or generated) does not

     

       4614
       4614
       +
             have any rcptTo email addresses.

     

       4615
       4615
       +
       

     

       4616
       4616
       +
          o  "invalidRecipients" - The "rcptTo" property of the envelope

     

       4617
       4617
       +
             (supplied or generated) contains at least one rcptTo value, which

     

       4618
       4618
       +
             is not a valid email address for sending to.  An

     

       4619
       4619
       +
             "invalidRecipients" "String[]" property MUST also be present on

     

       4620
       4620
       +
             the SetError, which is a list of the invalid addresses.

     

       4621
       4621
       +
       

     

       4622
       4622
       +
          o  "forbiddenMailFrom" - The server does not permit the user to send

     

       4623
       4623
       +
             a message with the envelope From address [RFC5321].

     

       4624
       4624
       +
       

     

       4625
       4625
       +
          o  "forbiddenFrom" - The server does not permit the user to send a

     

       4626
       4626
       +
             message with the From header field [RFC5322] of the message to be

     

       4627
       4627
       +
             sent.

     

       4628
       4628
       +
       

     

       4629
       4629
       +
          o  "forbiddenToSend" - The user does not have permission to send at

     

       4630
       4630
       +
             all right now for some reason.  A "description" "String" property

     

       4631
       4631
       +
             MAY be present on the SetError object to display to the user why

     

       4632
       4632
       +
             they are not permitted.

     

       4633
       4633
       +
       

     

       4634
       4634
       +
          For "update":

     

       4635
       4635
       +
       

     

       4636
       4636
       +
          o  "cannotUnsend" - The client attempted to update the "undoStatus"

     

       4637
       4637
       +
             of a valid EmailSubmission object from "pending" to "canceled",

     

       4638
       4638
       +
             but the message cannot be unsent.

     

       4639
       4639
       +
       

     

       4640
       4640
       +
       

     

       4641
       4641
       +
       

     

       4642
       4642
       +
       

     

       4643
       4643
       +
       

     

       4644
       4644
       +
       

     

       4645
       4645
       +
       

     

       4646
       4646
       +
       

     

       4647
       4647
       +
       

     

       4648
       4648
       +
       

     

       4649
       4649
       +
       

     

       4650
       4650
       +
       Jenkins & Newman             Standards Track                   [Page 83]

     

       4651
       4651
       +
       

     

       4652
       4652
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4653
       4653
       +
       

     

       4654
       4654
       +
       

     

       4655
       4655
       +
       7.5.1.  Example

     

       4656
       4656
       +
       

     

       4657
       4657
       +
          The following example presumes a draft of the Email to be sent has

     

       4658
       4658
       +
          already been saved, and its Email id is "M7f6ed5bcfd7e2604d1753f6c".

     

       4659
       4659
       +
          This call then sends the Email immediately, and if successful,

     

       4660
       4660
       +
          removes the "$draft" flag and moves it from the drafts folder (which

     

       4661
       4661
       +
          has Mailbox id "7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e") to the sent

     

       4662
       4662
       +
          folder (which we presume has Mailbox id "73dbcb4b-bffc-48bd-8c2a-

     

       4663
       4663
       +
          a2e91ca672f6").

     

       4664
       4664
       +
       

     

       4665
       4665
       +
             [[ "EmailSubmission/set", {

     

       4666
       4666
       +
               "accountId": "ue411d190",

     

       4667
       4667
       +
               "create": {

     

       4668
       4668
       +
                 "k1490": {

     

       4669
       4669
       +
                   "identityId": "I64588216",

     

       4670
       4670
       +
                   "emailId": "M7f6ed5bcfd7e2604d1753f6c",

     

       4671
       4671
       +
                   "envelope": {

     

       4672
       4672
       +
                     "mailFrom": {

     

       4673
       4673
       +
                       "email": "john@example.com",

     

       4674
       4674
       +
                       "parameters": null

     

       4675
       4675
       +
                     },

     

       4676
       4676
       +
                     "rcptTo": [{

     

       4677
       4677
       +
                       "email": "jane@example.com",

     

       4678
       4678
       +
                       "parameters": null

     

       4679
       4679
       +
                     },

     

       4680
       4680
       +
                     ...

     

       4681
       4681
       +
                     ]

     

       4682
       4682
       +
                   }

     

       4683
       4683
       +
                 }

     

       4684
       4684
       +
               },

     

       4685
       4685
       +
               "onSuccessUpdateEmail": {

     

       4686
       4686
       +
                 "#k1490": {

     

       4687
       4687
       +
                   "mailboxIds/7cb4e8ee-df87-4757-b9c4-2ea1ca41b38e": null,

     

       4688
       4688
       +
                   "mailboxIds/73dbcb4b-bffc-48bd-8c2a-a2e91ca672f6": true,

     

       4689
       4689
       +
                   "keywords/$draft": null

     

       4690
       4690
       +
                 }

     

       4691
       4691
       +
               }

     

       4692
       4692
       +
             }, "0" ]]

     

       4693
       4693
       +
       

     

       4694
       4694
       +
       

     

       4695
       4695
       +
       

     

       4696
       4696
       +
       

     

       4697
       4697
       +
       

     

       4698
       4698
       +
       

     

       4699
       4699
       +
       

     

       4700
       4700
       +
       

     

       4701
       4701
       +
       

     

       4702
       4702
       +
       

     

       4703
       4703
       +
       

     

       4704
       4704
       +
       

     

       4705
       4705
       +
       

     

       4706
       4706
       +
       Jenkins & Newman             Standards Track                   [Page 84]

     

       4707
       4707
       +
       

     

       4708
       4708
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4709
       4709
       +
       

     

       4710
       4710
       +
       

     

       4711
       4711
       +
          A successful response might look like this.  Note that there are two

     

       4712
       4712
       +
          responses due to the implicit "Email/set" call, but both have the

     

       4713
       4713
       +
          same method call id as they are due to the same call in the request:

     

       4714
       4714
       +
       

     

       4715
       4715
       +
                  [[ "EmailSubmission/set", {

     

       4716
       4716
       +
                    "accountId": "ue411d190",

     

       4717
       4717
       +
                    "oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",

     

       4718
       4718
       +
                    "newState": "355421f6-8aed-4cf4-a0c4-7377e951af36",

     

       4719
       4719
       +
                    "created": {

     

       4720
       4720
       +
                      "k1490": {

     

       4721
       4721
       +
                        "id": "ES-3bab7f9a-623e-4acf-99a5-2e67facb02a0"

     

       4722
       4722
       +
                      }

     

       4723
       4723
       +
                    }

     

       4724
       4724
       +
                  }, "0" ],

     

       4725
       4725
       +
                  [ "Email/set", {

     

       4726
       4726
       +
                    "accountId": "ue411d190",

     

       4727
       4727
       +
                    "oldState": "778193",

     

       4728
       4728
       +
                    "newState": "778197",

     

       4729
       4729
       +
                    "updated": {

     

       4730
       4730
       +
                        "M7f6ed5bcfd7e2604d1753f6c": null

     

       4731
       4731
       +
                    }

     

       4732
       4732
       +
                  }, "0" ]]

     

       4733
       4733
       +
       

     

       4734
       4734
       +
          Suppose instead an admin has removed sending rights for the user, so

     

       4735
       4735
       +
          the submission is rejected with a "forbiddenToSend" error.  The

     

       4736
       4736
       +
          description argument of the error is intended for display to the

     

       4737
       4737
       +
          user, so it should be localised appropriately.  Let's suppose the

     

       4738
       4738
       +
          request was sent with an Accept-Language header like this:

     

       4739
       4739
       +
       

     

       4740
       4740
       +
                           Accept-Language: de;q=0.9,en;q=0.8

     

       4741
       4741
       +
       

     

       4742
       4742
       +
       

     

       4743
       4743
       +
       

     

       4744
       4744
       +
       

     

       4745
       4745
       +
       

     

       4746
       4746
       +
       

     

       4747
       4747
       +
       

     

       4748
       4748
       +
       

     

       4749
       4749
       +
       

     

       4750
       4750
       +
       

     

       4751
       4751
       +
       

     

       4752
       4752
       +
       

     

       4753
       4753
       +
       

     

       4754
       4754
       +
       

     

       4755
       4755
       +
       

     

       4756
       4756
       +
       

     

       4757
       4757
       +
       

     

       4758
       4758
       +
       

     

       4759
       4759
       +
       

     

       4760
       4760
       +
       

     

       4761
       4761
       +
       

     

       4762
       4762
       +
       Jenkins & Newman             Standards Track                   [Page 85]

     

       4763
       4763
       +
       

     

       4764
       4764
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4765
       4765
       +
       

     

       4766
       4766
       +
       

     

       4767
       4767
       +
          The server should attempt to choose the best localisation from those

     

       4768
       4768
       +
          it has available based on the Accept-Language header, as described in

     

       4769
       4769
       +
          [RFC8620], Section 3.8.  If the server has English, French, and

     

       4770
       4770
       +
          German translations, it would choose German as the preferred language

     

       4771
       4771
       +
          and return a response like this:

     

       4772
       4772
       +
       

     

       4773
       4773
       +
       [[ "EmailSubmission/set", {

     

       4774
       4774
       +
         "accountId": "ue411d190",

     

       4775
       4775
       +
         "oldState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",

     

       4776
       4776
       +
         "newState": "012421s6-8nrq-4ps4-n0p4-9330r951ns21",

     

       4777
       4777
       +
         "notCreated": {

     

       4778
       4778
       +
           "k1490": {

     

       4779
       4779
       +
             "type": "forbiddenToSend",

     

       4780
       4780
       +
             "description": "Verzeihung, wegen verdaechtiger Aktivitaeten Ihres

     

       4781
       4781
       +
              Benutzerkontos haben wir den Versand von Nachrichten gesperrt.

     

       4782
       4782
       +
              Bitte wenden Sie sich fuer Hilfe an unser Support Team."

     

       4783
       4783
       +
           }

     

       4784
       4784
       +
         }

     

       4785
       4785
       +
       }, "0" ]]

     

       4786
       4786
       +
       

     

       4787
       4787
       +
       8.  Vacation Response

     

       4788
       4788
       +
       

     

       4789
       4789
       +
          A vacation response sends an automatic reply when a message is

     

       4790
       4790
       +
          delivered to the mail store, informing the original sender that their

     

       4791
       4791
       +
          message may not be read for some time.

     

       4792
       4792
       +
       

     

       4793
       4793
       +
          Automated message sending can produce undesirable behaviour.  To

     

       4794
       4794
       +
          avoid this, implementors MUST follow the recommendations set forth in

     

       4795
       4795
       +
          [RFC3834].

     

       4796
       4796
       +
       

     

       4797
       4797
       +
          The *VacationResponse* object represents the state of vacation-

     

       4798
       4798
       +
          response-related settings for an account.  It has the following

     

       4799
       4799
       +
          properties:

     

       4800
       4800
       +
       

     

       4801
       4801
       +
          o  id: "Id" (immutable; server-set)

     

       4802
       4802
       +
       

     

       4803
       4803
       +
             The id of the object.  There is only ever one VacationResponse

     

       4804
       4804
       +
             object, and its id is "singleton".

     

       4805
       4805
       +
       

     

       4806
       4806
       +
          o  isEnabled: "Boolean"

     

       4807
       4807
       +
       

     

       4808
       4808
       +
             Should a vacation response be sent if a message arrives between

     

       4809
       4809
       +
             the "fromDate" and "toDate"?

     

       4810
       4810
       +
       

     

       4811
       4811
       +
       

     

       4812
       4812
       +
       

     

       4813
       4813
       +
       

     

       4814
       4814
       +
       

     

       4815
       4815
       +
       

     

       4816
       4816
       +
       

     

       4817
       4817
       +
       

     

       4818
       4818
       +
       Jenkins & Newman             Standards Track                   [Page 86]

     

       4819
       4819
       +
       

     

       4820
       4820
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4821
       4821
       +
       

     

       4822
       4822
       +
       

     

       4823
       4823
       +
          o  fromDate: "UTCDate|null"

     

       4824
       4824
       +
       

     

       4825
       4825
       +
             If "isEnabled" is true, messages that arrive on or after this

     

       4826
       4826
       +
             date-time (but before the "toDate" if defined) should receive the

     

       4827
       4827
       +
             user's vacation response.  If null, the vacation response is

     

       4828
       4828
       +
             effective immediately.

     

       4829
       4829
       +
       

     

       4830
       4830
       +
          o  toDate: "UTCDate|null"

     

       4831
       4831
       +
       

     

       4832
       4832
       +
             If "isEnabled" is true, messages that arrive before this date-time

     

       4833
       4833
       +
             (but on or after the "fromDate" if defined) should receive the

     

       4834
       4834
       +
             user's vacation response.  If null, the vacation response is

     

       4835
       4835
       +
             effective indefinitely.

     

       4836
       4836
       +
       

     

       4837
       4837
       +
          o  subject: "String|null"

     

       4838
       4838
       +
       

     

       4839
       4839
       +
             The subject that will be used by the message sent in response to

     

       4840
       4840
       +
             messages when the vacation response is enabled.  If null, an

     

       4841
       4841
       +
             appropriate subject SHOULD be set by the server.

     

       4842
       4842
       +
       

     

       4843
       4843
       +
          o  textBody: "String|null"

     

       4844
       4844
       +
       

     

       4845
       4845
       +
             The plaintext body to send in response to messages when the

     

       4846
       4846
       +
             vacation response is enabled.  If this is null, the server SHOULD

     

       4847
       4847
       +
             generate a plaintext body part from the "htmlBody" when sending

     

       4848
       4848
       +
             vacation responses but MAY choose to send the response as HTML

     

       4849
       4849
       +
             only.  If both "textBody" and "htmlBody" are null, an appropriate

     

       4850
       4850
       +
             default body SHOULD be generated for responses by the server.

     

       4851
       4851
       +
       

     

       4852
       4852
       +
          o  htmlBody: "String|null"

     

       4853
       4853
       +
       

     

       4854
       4854
       +
             The HTML body to send in response to messages when the vacation

     

       4855
       4855
       +
             response is enabled.  If this is null, the server MAY choose to

     

       4856
       4856
       +
             generate an HTML body part from the "textBody" when sending

     

       4857
       4857
       +
             vacation responses or MAY choose to send the response as plaintext

     

       4858
       4858
       +
             only.

     

       4859
       4859
       +
       

     

       4860
       4860
       +
          The following JMAP methods are supported.

     

       4861
       4861
       +
       

     

       4862
       4862
       +
       8.1.  VacationResponse/get

     

       4863
       4863
       +
       

     

       4864
       4864
       +
          This is a standard "/get" method as described in [RFC8620],

     

       4865
       4865
       +
          Section 5.1.

     

       4866
       4866
       +
       

     

       4867
       4867
       +
          There MUST only be exactly one VacationResponse object in an account.

     

       4868
       4868
       +
          It MUST have the id "singleton".

     

       4869
       4869
       +
       

     

       4870
       4870
       +
       

     

       4871
       4871
       +
       

     

       4872
       4872
       +
       

     

       4873
       4873
       +
       

     

       4874
       4874
       +
       Jenkins & Newman             Standards Track                   [Page 87]

     

       4875
       4875
       +
       

     

       4876
       4876
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4877
       4877
       +
       

     

       4878
       4878
       +
       

     

       4879
       4879
       +
       8.2.  VacationResponse/set

     

       4880
       4880
       +
       

     

       4881
       4881
       +
          This is a standard "/set" method as described in [RFC8620],

     

       4882
       4882
       +
          Section 5.3.

     

       4883
       4883
       +
       

     

       4884
       4884
       +
       9.  Security Considerations

     

       4885
       4885
       +
       

     

       4886
       4886
       +
          All security considerations of JMAP [RFC8620] apply to this

     

       4887
       4887
       +
          specification.  Additional considerations specific to the data types

     

       4888
       4888
       +
          and functionality introduced by this document are described in the

     

       4889
       4889
       +
          following subsections.

     

       4890
       4890
       +
       

     

       4891
       4891
       +
       9.1.  EmailBodyPart Value

     

       4892
       4892
       +
       

     

       4893
       4893
       +
          Service providers typically perform security filtering on incoming

     

       4894
       4894
       +
          messages, and it's important that the detection of content-type and

     

       4895
       4895
       +
          charset for the security filter aligns with the heuristics performed

     

       4896
       4896
       +
          by JMAP servers.  Servers that apply heuristics to determine the

     

       4897
       4897
       +
          content-type or charset for an EmailBodyValue SHOULD document the

     

       4898
       4898
       +
          heuristics and provide a mechanism to turn them off in the event they

     

       4899
       4899
       +
          are misaligned with the security filter used at a particular mail

     

       4900
       4900
       +
          host.

     

       4901
       4901
       +
       

     

       4902
       4902
       +
          Automatic conversion of charsets that allow hidden channels for ASCII

     

       4903
       4903
       +
          text, such as UTF-7, have been problematic for security filters in

     

       4904
       4904
       +
          the past, so server implementations can mitigate this risk by having

     

       4905
       4905
       +
          such conversions off-by-default and/or separately configurable.

     

       4906
       4906
       +
       

     

       4907
       4907
       +
          To allow the client to restrict the volume of data it can receive in

     

       4908
       4908
       +
          response to a request, a maximum length may be requested for the data

     

       4909
       4909
       +
          returned for a textual body part.  However, truncating the data may

     

       4910
       4910
       +
          change the semantic meaning, for example, truncating a URL changes

     

       4911
       4911
       +
          its location.  Servers that scan for links to malicious sites should

     

       4912
       4912
       +
          take care to either ensure truncation is not at a semantically

     

       4913
       4913
       +
          significant point or rescan the truncated value for malicious content

     

       4914
       4914
       +
          before returning it.

     

       4915
       4915
       +
       

     

       4916
       4916
       +
       9.2.  HTML Email Display

     

       4917
       4917
       +
       

     

       4918
       4918
       +
          HTML message bodies provide richer formatting for messages but

     

       4919
       4919
       +
          present a number of security challenges, especially when embedded in

     

       4920
       4920
       +
          a webmail context in combination with interface HTML.  Clients that

     

       4921
       4921
       +
          render HTML messages should carefully consider the potential risks,

     

       4922
       4922
       +
          including:

     

       4923
       4923
       +
       

     

       4924
       4924
       +
       

     

       4925
       4925
       +
       

     

       4926
       4926
       +
       

     

       4927
       4927
       +
       

     

       4928
       4928
       +
       

     

       4929
       4929
       +
       

     

       4930
       4930
       +
       Jenkins & Newman             Standards Track                   [Page 88]

     

       4931
       4931
       +
       

     

       4932
       4932
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4933
       4933
       +
       

     

       4934
       4934
       +
       

     

       4935
       4935
       +
          o  Embedded JavaScript can rewrite the message to change its content

     

       4936
       4936
       +
             on subsequent opening, allowing users to be mislead.  In webmail

     

       4937
       4937
       +
             systems, if run in the same origin as the interface, it can access

     

       4938
       4938
       +
             and exfiltrate all private data accessible to the user, including

     

       4939
       4939
       +
             all other messages and potentially contacts, calendar events,

     

       4940
       4940
       +
             settings, and credentials.  It can also rewrite the interface to

     

       4941
       4941
       +
             undetectably phish passwords.  A compromise is likely to be

     

       4942
       4942
       +
             persistent, not just for the duration of page load, due to

     

       4943
       4943
       +
             exfiltration of session credentials or installation of a service

     

       4944
       4944
       +
             worker that can intercept all subsequent network requests

     

       4945
       4945
       +
             (however, this would only be possible if blob downloads are also

     

       4946
       4946
       +
             available on the same origin, and the service worker script is

     

       4947
       4947
       +
             attached to the message).

     

       4948
       4948
       +
       

     

       4949
       4949
       +
          o  HTML documents may load content directly from the Internet rather

     

       4950
       4950
       +
             than just referencing attached resources.  For example, you may

     

       4951
       4951
       +
             have an "<img>" tag with an external "src" attribute.  This may

     

       4952
       4952
       +
             leak to the sender when a message is opened, as well as the IP

     

       4953
       4953
       +
             address of the recipient.  Cookies may also be sent and set by the

     

       4954
       4954
       +
             server, allowing tracking between different messages and even

     

       4955
       4955
       +
             website visits and advertising profiles.

     

       4956
       4956
       +
       

     

       4957
       4957
       +
          o  In webmail systems, CSS can break the layout or create phishing

     

       4958
       4958
       +
             vulnerabilities.  For example, the use of "position:fixed" can

     

       4959
       4959
       +
             allow a message to draw content outside of its normal bounds,

     

       4960
       4960
       +
             potentially clickjacking a real interface element.

     

       4961
       4961
       +
       

     

       4962
       4962
       +
          o  If in a webmail context and not inside a separate frame, any

     

       4963
       4963
       +
             styles defined in CSS rules will apply to interface elements as

     

       4964
       4964
       +
             well if the selector matches, allowing the interface to be

     

       4965
       4965
       +
             modified.  Similarly, any interface styles that match elements in

     

       4966
       4966
       +
             the message will alter their appearance, potentially breaking the

     

       4967
       4967
       +
             layout of the message.

     

       4968
       4968
       +
       

     

       4969
       4969
       +
          o  The link text in HTML has no necessary correlation with the actual

     

       4970
       4970
       +
             target of the link, which can be used to make phishing attacks

     

       4971
       4971
       +
             more convincing.

     

       4972
       4972
       +
       

     

       4973
       4973
       +
          o  Links opened from a message or embedded external content may leak

     

       4974
       4974
       +
             private info in the Referer header sent by default in most

     

       4975
       4975
       +
             systems.

     

       4976
       4976
       +
       

     

       4977
       4977
       +
          o  Forms can be used to mimic login boxes, providing a potent

     

       4978
       4978
       +
             phishing vector if allowed to submit directly from the message

     

       4979
       4979
       +
             display.

     

       4980
       4980
       +
       

     

       4981
       4981
       +
       

     

       4982
       4982
       +
       

     

       4983
       4983
       +
       

     

       4984
       4984
       +
       

     

       4985
       4985
       +
       

     

       4986
       4986
       +
       Jenkins & Newman             Standards Track                   [Page 89]

     

       4987
       4987
       +
       

     

       4988
       4988
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       4989
       4989
       +
       

     

       4990
       4990
       +
       

     

       4991
       4991
       +
          There are a number of ways clients can mitigate these issues, and a

     

       4992
       4992
       +
          defence-in-depth approach that uses a combination of techniques will

     

       4993
       4993
       +
          provide the strongest security.

     

       4994
       4994
       +
       

     

       4995
       4995
       +
          o  HTML can be filtered before rendering, stripping potentially

     

       4996
       4996
       +
             malicious content.  Sanitising HTML correctly is tricky, and

     

       4997
       4997
       +
             implementors are strongly recommended to use a well-tested library

     

       4998
       4998
       +
             with a carefully vetted whitelist-only approach.  New features

     

       4999
       4999
       +
             with unexpected security characteristics may be added to HTML

     

       5000
       5000
       +
             rendering engines in the future; a blacklist approach is likely to

     

       5001
       5001
       +
             result in security issues.

     

       5002
       5002
       +
       

     

       5003
       5003
       +
             Subtle differences in parsing of HTML can introduce security

     

       5004
       5004
       +
             flaws: to filter with 100% accuracy, you need to use the same

     

       5005
       5005
       +
             parser that the HTML rendering engine will use.

     

       5006
       5006
       +
       

     

       5007
       5007
       +
          o  Encapsulating the message in an "<iframe sandbox>", as defined in

     

       5008
       5008
       +
             [HTML], Section 4.7.6, can help mitigate a number of risks.  This

     

       5009
       5009
       +
             will:

     

       5010
       5010
       +
       

     

       5011
       5011
       +
             *  Disable JavaScript.

     

       5012
       5012
       +
       

     

       5013
       5013
       +
             *  Disable form submission.

     

       5014
       5014
       +
       

     

       5015
       5015
       +
             *  Prevent drawing outside of its bounds or conflicts between

     

       5016
       5016
       +
                message CSS and interface CSS.

     

       5017
       5017
       +
       

     

       5018
       5018
       +
             *  Establish a unique anonymous origin, separate to the containing

     

       5019
       5019
       +
                origin.

     

       5020
       5020
       +
       

     

       5021
       5021
       +
          o  A strong Content Security Policy (see <https://www.w3.org/TR/

     

       5022
       5022
       +
             CSP3/>) can, among other things, block JavaScript and the loading

     

       5023
       5023
       +
             of external content should it manage to evade the filter.

     

       5024
       5024
       +
       

     

       5025
       5025
       +
          o  The leakage of information in the Referer header can be mitigated

     

       5026
       5026
       +
             with the use of a referrer policy (see <https://www.w3.org/TR/

     

       5027
       5027
       +
             referrer-policy/>).

     

       5028
       5028
       +
       

     

       5029
       5029
       +
          o  A "crossorigin=anonymous" attribute on tags that load remote

     

       5030
       5030
       +
             content can prevent cookies from being sent.

     

       5031
       5031
       +
       

     

       5032
       5032
       +
          o  If adding "target=_blank" to open links in new tabs, also add

     

       5033
       5033
       +
             "rel=noopener" to ensure the page that opens cannot change the URL

     

       5034
       5034
       +
             in the original tab to redirect the user to a phishing site.

     

       5035
       5035
       +
       

     

       5036
       5036
       +
          As highly complex software components, HTML rendering engines

     

       5037
       5037
       +
          increase the attack surface of a client considerably, especially when

     

       5038
       5038
       +
          being used to process untrusted, potentially malicious content.

     

       5039
       5039
       +
       

     

       5040
       5040
       +
       

     

       5041
       5041
       +
       

     

       5042
       5042
       +
       Jenkins & Newman             Standards Track                   [Page 90]

     

       5043
       5043
       +
       

     

       5044
       5044
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5045
       5045
       +
       

     

       5046
       5046
       +
       

     

       5047
       5047
       +
          Serious bugs have been found in image decoders, JavaScript engines,

     

       5048
       5048
       +
          and HTML parsers in the past, which could lead to full system

     

       5049
       5049
       +
          compromise.  Clients using an engine should ensure they get the

     

       5050
       5050
       +
          latest version and continue to incorporate any security patches

     

       5051
       5051
       +
          released by the vendor.

     

       5052
       5052
       +
       

     

       5053
       5053
       +
       9.3.  Multiple Part Display

     

       5054
       5054
       +
       

     

       5055
       5055
       +
          Messages may consist of multiple parts to be displayed sequentially

     

       5056
       5056
       +
          as a body.  Clients MUST render each part in isolation and MUST NOT

     

       5057
       5057
       +
          concatenate the raw text values to render.  Doing so may change the

     

       5058
       5058
       +
          overall semantics of the message.  If the client or server is

     

       5059
       5059
       +
          decrypting a Pretty Good Privacy (PGP) or S/MIME encrypted part,

     

       5060
       5060
       +
          concatenating with other parts may leak the decrypted text to an

     

       5061
       5061
       +
          attacker, as described in [EFAIL].

     

       5062
       5062
       +
       

     

       5063
       5063
       +
       9.4.  Email Submission

     

       5064
       5064
       +
       

     

       5065
       5065
       +
          SMTP submission servers [RFC6409] use a number of mechanisms to

     

       5066
       5066
       +
          mitigate damage caused by compromised user accounts and end-user

     

       5067
       5067
       +
          systems including rate limiting, anti-virus/anti-spam milters (mail

     

       5068
       5068
       +
          filters), and other technologies.  The technologies work better when

     

       5069
       5069
       +
          they have more information about the client connection.  If JMAP

     

       5070
       5070
       +
          email submission is implemented as a proxy to an SMTP submission

     

       5071
       5071
       +
          server, it is useful to communicate this information from the JMAP

     

       5072
       5072
       +
          proxy to the submission server.  The de facto XCLIENT extension to

     

       5073
       5073
       +
          SMTP [XCLIENT] can be used to do this, but use of an authenticated

     

       5074
       5074
       +
          channel is recommended to limit use of that extension to explicitly

     

       5075
       5075
       +
          authorised proxies.

     

       5076
       5076
       +
       

     

       5077
       5077
       +
          JMAP servers that proxy to an SMTP submission server SHOULD allow use

     

       5078
       5078
       +
          of the submissions port [RFC8314].  Implementation of a mechanism

     

       5079
       5079
       +
          similar to SMTP XCLIENT is strongly encouraged.  While Simple

     

       5080
       5080
       +
          Authentication and Security Layer (SASL) PLAIN over TLS [RFC4616] is

     

       5081
       5081
       +
          presently the mandatory-to-implement mechanism for interoperability

     

       5082
       5082
       +
          with SMTP submission servers [RFC4954], a JMAP submission proxy

     

       5083
       5083
       +
          SHOULD implement and prefer a stronger mechanism for this use case

     

       5084
       5084
       +
          such as TLS client certificate authentication with SASL EXTERNAL

     

       5085
       5085
       +
          ([RFC4422], Appendix A) or Salted Challenge Response Authentication

     

       5086
       5086
       +
          Mechanism (SCRAM) [RFC7677].

     

       5087
       5087
       +
       

     

       5088
       5088
       +
          In the event the JMAP server directly relays mail to SMTP servers in

     

       5089
       5089
       +
          other administrative domains, implementation of the de facto [milter]

     

       5090
       5090
       +
          protocol is strongly encouraged to integrate with third-party

     

       5091
       5091
       +
          products that address security issues including anti-virus/anti-spam,

     

       5092
       5092
       +
          reputation protection, compliance archiving, and data loss

     

       5093
       5093
       +
          prevention.  Proxying to a local SMTP submission server may be a

     

       5094
       5094
       +
          simpler way to provide such security services.

     

       5095
       5095
       +
       

     

       5096
       5096
       +
       

     

       5097
       5097
       +
       

     

       5098
       5098
       +
       Jenkins & Newman             Standards Track                   [Page 91]

     

       5099
       5099
       +
       

     

       5100
       5100
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5101
       5101
       +
       

     

       5102
       5102
       +
       

     

       5103
       5103
       +
       9.5.  Partial Account Access

     

       5104
       5104
       +
       

     

       5105
       5105
       +
          A user may only have permission to access a subset of the data that

     

       5106
       5106
       +
          exists in an account.  To avoid leaking unauthorised information, in

     

       5107
       5107
       +
          such a situation, the server MUST treat any data the user does not

     

       5108
       5108
       +
          have permission to access the same as if it did not exist.

     

       5109
       5109
       +
       

     

       5110
       5110
       +
          For example, suppose user A has an account with two Mailboxes, inbox

     

       5111
       5111
       +
          and sent, but only shares the inbox with user B.  In this case, when

     

       5112
       5112
       +
          user B fetches Mailboxes for this account, the server MUST behave as

     

       5113
       5113
       +
          though the sent Mailbox did not exist.  Similarly, when querying or

     

       5114
       5114
       +
          fetching Email objects, it MUST treat any messages that just belong

     

       5115
       5115
       +
          to the sent Mailbox as though they did not exist.  Fetching Thread

     

       5116
       5116
       +
          objects MUST only return ids for Email objects the user has

     

       5117
       5117
       +
          permission to access; if none, the Thread again MUST be treated the

     

       5118
       5118
       +
          same as if it did not exist.

     

       5119
       5119
       +
       

     

       5120
       5120
       +
          If the server forbids a single account from having two identical

     

       5121
       5121
       +
          messages, or two messages with the same Message-Id header field, a

     

       5122
       5122
       +
          user with write access can use the error returned by trying to

     

       5123
       5123
       +
          create/import such a message to detect whether it already exists in

     

       5124
       5124
       +
          an inaccessible portion of the account.

     

       5125
       5125
       +
       

     

       5126
       5126
       +
       9.6.  Permission to Send from an Address

     

       5127
       5127
       +
       

     

       5128
       5128
       +
          In recent years, the email ecosystem has moved towards associating

     

       5129
       5129
       +
          trust with the From address in the message [RFC5322], particularly

     

       5130
       5130
       +
          with schemes such as Domain-based Message Authentication, Reporting,

     

       5131
       5131
       +
          and Conformance (DMARC) [RFC7489].

     

       5132
       5132
       +
       

     

       5133
       5133
       +
          The set of Identity objects (see Section 6) in an account lets the

     

       5134
       5134
       +
          client know which email addresses the user has permission to send

     

       5135
       5135
       +
          from.  Each email submission is associated with an Identity, and

     

       5136
       5136
       +
          servers SHOULD reject submissions where the From header field of the

     

       5137
       5137
       +
          message does not correspond to the associated Identity.

     

       5138
       5138
       +
       

     

       5139
       5139
       +
          The server MAY allow an exception to send an exact copy of an

     

       5140
       5140
       +
          existing message received into the mail store to another address

     

       5141
       5141
       +
          (otherwise known as "redirecting" or "bouncing"), although it is

     

       5142
       5142
       +
          RECOMMENDED the server limit this to destinations the user has

     

       5143
       5143
       +
          verified they also control.

     

       5144
       5144
       +
       

     

       5145
       5145
       +
          If the user attempts to create a new Identity object, the server MUST

     

       5146
       5146
       +
          reject it with the appropriate error if the user does not have

     

       5147
       5147
       +
          permission to use that email address to send from.

     

       5148
       5148
       +
       

     

       5149
       5149
       +
       

     

       5150
       5150
       +
       

     

       5151
       5151
       +
       

     

       5152
       5152
       +
       

     

       5153
       5153
       +
       

     

       5154
       5154
       +
       Jenkins & Newman             Standards Track                   [Page 92]

     

       5155
       5155
       +
       

     

       5156
       5156
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5157
       5157
       +
       

     

       5158
       5158
       +
       

     

       5159
       5159
       +
          The SMTP MAIL FROM address [RFC5321] is often confused with the From

     

       5160
       5160
       +
          message header field [RFC5322].  The user generally only ever sees

     

       5161
       5161
       +
          the address in the message header field, and this is the primary one

     

       5162
       5162
       +
          to enforce.  However, the server MUST also enforce appropriate

     

       5163
       5163
       +
          restrictions on the MAIL FROM address [RFC5321] to stop the user from

     

       5164
       5164
       +
          flooding a third-party address with bounces and non-delivery notices.

     

       5165
       5165
       +
       

     

       5166
       5166
       +
          The JMAP submission model provides separate errors for impermissible

     

       5167
       5167
       +
          addresses in either context.

     

       5168
       5168
       +
       

     

       5169
       5169
       +
       10.  IANA Considerations

     

       5170
       5170
       +
       

     

       5171
       5171
       +
       10.1.  JMAP Capability Registration for "mail"

     

       5172
       5172
       +
       

     

       5173
       5173
       +
          IANA has registered the "mail" JMAP Capability as follows:

     

       5174
       5174
       +
       

     

       5175
       5175
       +
          Capability Name: urn:ietf:params:jmap:mail

     

       5176
       5176
       +
       

     

       5177
       5177
       +
          Specification document: this document

     

       5178
       5178
       +
       

     

       5179
       5179
       +
          Intended use: common

     

       5180
       5180
       +
       

     

       5181
       5181
       +
          Change Controller: IETF

     

       5182
       5182
       +
       

     

       5183
       5183
       +
          Security and privacy considerations: this document, Section 9

     

       5184
       5184
       +
       

     

       5185
       5185
       +
       10.2.  JMAP Capability Registration for "submission"

     

       5186
       5186
       +
       

     

       5187
       5187
       +
          IANA has registered the "submission" JMAP Capability as follows:

     

       5188
       5188
       +
       

     

       5189
       5189
       +
          Capability Name: urn:ietf:params:jmap:submission

     

       5190
       5190
       +
       

     

       5191
       5191
       +
          Specification document: this document

     

       5192
       5192
       +
       

     

       5193
       5193
       +
          Intended use: common

     

       5194
       5194
       +
       

     

       5195
       5195
       +
          Change Controller: IETF

     

       5196
       5196
       +
       

     

       5197
       5197
       +
          Security and privacy considerations: this document, Section 9

     

       5198
       5198
       +
       

     

       5199
       5199
       +
       

     

       5200
       5200
       +
       

     

       5201
       5201
       +
       

     

       5202
       5202
       +
       

     

       5203
       5203
       +
       

     

       5204
       5204
       +
       

     

       5205
       5205
       +
       

     

       5206
       5206
       +
       

     

       5207
       5207
       +
       

     

       5208
       5208
       +
       

     

       5209
       5209
       +
       

     

       5210
       5210
       +
       Jenkins & Newman             Standards Track                   [Page 93]

     

       5211
       5211
       +
       

     

       5212
       5212
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5213
       5213
       +
       

     

       5214
       5214
       +
       

     

       5215
       5215
       +
       10.3.  JMAP Capability Registration for "vacationresponse"

     

       5216
       5216
       +
       

     

       5217
       5217
       +
          IANA has registered the "vacationresponse" JMAP Capability as

     

       5218
       5218
       +
          follows:

     

       5219
       5219
       +
       

     

       5220
       5220
       +
          Capability Name: urn:ietf:params:jmap:vacationresponse

     

       5221
       5221
       +
       

     

       5222
       5222
       +
          Specification document: this document

     

       5223
       5223
       +
       

     

       5224
       5224
       +
          Intended use: common

     

       5225
       5225
       +
       

     

       5226
       5226
       +
          Change Controller: IETF

     

       5227
       5227
       +
       

     

       5228
       5228
       +
          Security and privacy considerations: this document, Section 9

     

       5229
       5229
       +
       

     

       5230
       5230
       +
       10.4.  IMAP and JMAP Keywords Registry

     

       5231
       5231
       +
       

     

       5232
       5232
       +
          This document makes two changes to the IMAP keywords registry as

     

       5233
       5233
       +
          defined in [RFC5788].

     

       5234
       5234
       +
       

     

       5235
       5235
       +
          First, the name of the registry is changed to the "IMAP and JMAP

     

       5236
       5236
       +
          Keywords" registry.

     

       5237
       5237
       +
       

     

       5238
       5238
       +
          Second, a scope column is added to the template and registry

     

       5239
       5239
       +
          indicating whether a keyword applies to "IMAP-only", "JMAP-only",

     

       5240
       5240
       +
          "both", or "reserved".  All keywords already in the IMAP keyword

     

       5241
       5241
       +
          registry have been marked with a scope of "both".  The "reserved"

     

       5242
       5242
       +
          status can be used to prevent future registration of a name that

     

       5243
       5243
       +
          would be confusing if registered.  Registration of keywords with

     

       5244
       5244
       +
          scope "reserved" omit most fields in the registration template (see

     

       5245
       5245
       +
          registration of "$recent" below for an example); such registrations

     

       5246
       5246
       +
          are intended to be infrequent.

     

       5247
       5247
       +
       

     

       5248
       5248
       +
          IMAP clients MAY silently ignore any keywords marked "JMAP-only" or

     

       5249
       5249
       +
          "reserved" in the event they appear in protocol.  JMAP clients MAY

     

       5250
       5250
       +
          silently ignore any keywords marked "IMAP-only" or "reserved" in the

     

       5251
       5251
       +
          event they appear in protocol.

     

       5252
       5252
       +
       

     

       5253
       5253
       +
          New "JMAP-only" keywords are registered in the following subsections.

     

       5254
       5254
       +
          These keywords correspond to IMAP system keywords and are thus not

     

       5255
       5255
       +
          appropriate for use in IMAP.  These keywords cannot be subsequently

     

       5256
       5256
       +
          registered for use in IMAP except via standards action.

     

       5257
       5257
       +
       

     

       5258
       5258
       +
       

     

       5259
       5259
       +
       

     

       5260
       5260
       +
       

     

       5261
       5261
       +
       

     

       5262
       5262
       +
       

     

       5263
       5263
       +
       

     

       5264
       5264
       +
       

     

       5265
       5265
       +
       

     

       5266
       5266
       +
       Jenkins & Newman             Standards Track                   [Page 94]

     

       5267
       5267
       +
       

     

       5268
       5268
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5269
       5269
       +
       

     

       5270
       5270
       +
       

     

       5271
       5271
       +
       10.4.1.  Registration of JMAP Keyword "$draft"

     

       5272
       5272
       +
       

     

       5273
       5273
       +
          This registers the "JMAP-only" keyword "$draft" in the "IMAP and JMAP

     

       5274
       5274
       +
          Keywords" registry.

     

       5275
       5275
       +
       

     

       5276
       5276
       +
          Keyword name: $draft

     

       5277
       5277
       +
       

     

       5278
       5278
       +
          Scope: JMAP-only

     

       5279
       5279
       +
       

     

       5280
       5280
       +
          Purpose (description): This is set when the user wants to treat the

     

       5281
       5281
       +
          message as a draft the user is composing.  This is the JMAP

     

       5282
       5282
       +
          equivalent of the IMAP \Draft flag.

     

       5283
       5283
       +
       

     

       5284
       5284
       +
          Private or Shared on a server: BOTH

     

       5285
       5285
       +
       

     

       5286
       5286
       +
          Is it an advisory keyword or may it cause an automatic action:

     

       5287
       5287
       +
          Automatic.  If the account has an IMAP mailbox marked with the

     

       5288
       5288
       +
          \Drafts special use attribute [RFC6154], setting this flag MAY cause

     

       5289
       5289
       +
          the message to appear in that mailbox automatically.  Certain JMAP

     

       5290
       5290
       +
          computed values such as "unreadEmails" will change as a result of

     

       5291
       5291
       +
          changing this flag.  In addition, mail clients will typically present

     

       5292
       5292
       +
          draft messages in a composer window rather than a viewer window.

     

       5293
       5293
       +
       

     

       5294
       5294
       +
          When/by whom the keyword is set/cleared: This is typically set by a

     

       5295
       5295
       +
          JMAP client when referring to a draft message.  One model for draft

     

       5296
       5296
       +
          Emails would result in clearing this flag in an "EmailSubmission/set"

     

       5297
       5297
       +
          operation with an "onSuccessUpdateEmail" argument.  In a mail store

     

       5298
       5298
       +
          shared by JMAP and IMAP, this is also set and cleared as necessary so

     

       5299
       5299
       +
          it matches the IMAP \Draft flag.

     

       5300
       5300
       +
       

     

       5301
       5301
       +
          Related keywords: None

     

       5302
       5302
       +
       

     

       5303
       5303
       +
          Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]

     

       5304
       5304
       +
       

     

       5305
       5305
       +
          Security Considerations: A server implementing this keyword as a

     

       5306
       5306
       +
          shared keyword may disclose that a user considers the message a draft

     

       5307
       5307
       +
          message.  This information would be exposed to other users with read

     

       5308
       5308
       +
          permission for the Mailbox keywords.

     

       5309
       5309
       +
       

     

       5310
       5310
       +
          Published specification: this document

     

       5311
       5311
       +
       

     

       5312
       5312
       +
          Person & email address to contact for further information:

     

       5313
       5313
       +
          JMAP mailing list <jmap@ietf.org>

     

       5314
       5314
       +
       

     

       5315
       5315
       +
          Intended usage: COMMON

     

       5316
       5316
       +
       

     

       5317
       5317
       +
          Owner/Change controller: IESG

     

       5318
       5318
       +
       

     

       5319
       5319
       +
       

     

       5320
       5320
       +
       

     

       5321
       5321
       +
       

     

       5322
       5322
       +
       Jenkins & Newman             Standards Track                   [Page 95]

     

       5323
       5323
       +
       

     

       5324
       5324
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5325
       5325
       +
       

     

       5326
       5326
       +
       

     

       5327
       5327
       +
       10.4.2.  Registration of JMAP Keyword "$seen"

     

       5328
       5328
       +
       

     

       5329
       5329
       +
          This registers the "JMAP-only" keyword "$seen" in the "IMAP and JMAP

     

       5330
       5330
       +
          Keywords" registry.

     

       5331
       5331
       +
       

     

       5332
       5332
       +
          Keyword name: $seen

     

       5333
       5333
       +
       

     

       5334
       5334
       +
          Scope: JMAP-only

     

       5335
       5335
       +
       

     

       5336
       5336
       +
          Purpose (description): This is set when the user wants to treat the

     

       5337
       5337
       +
          message as read.  This is the JMAP equivalent of the IMAP \Seen flag.

     

       5338
       5338
       +
       

     

       5339
       5339
       +
          Private or Shared on a server: BOTH

     

       5340
       5340
       +
       

     

       5341
       5341
       +
          Is it an advisory keyword or may it cause an automatic action:

     

       5342
       5342
       +
          Advisory.  However, certain JMAP computed values such as

     

       5343
       5343
       +
          "unreadEmails" will change as a result of changing this flag.

     

       5344
       5344
       +
       

     

       5345
       5345
       +
          When/by whom the keyword is set/cleared: This is set by a JMAP client

     

       5346
       5346
       +
          when it presents the message content to the user; clients often offer

     

       5347
       5347
       +
          an option to clear this flag.  In a mail store shared by JMAP and

     

       5348
       5348
       +
          IMAP, this is also set and cleared as necessary so it matches the

     

       5349
       5349
       +
          IMAP \Seen flag.

     

       5350
       5350
       +
       

     

       5351
       5351
       +
          Related keywords: None

     

       5352
       5352
       +
       

     

       5353
       5353
       +
          Related IMAP/JMAP Capabilities: None

     

       5354
       5354
       +
       

     

       5355
       5355
       +
          Security Considerations: A server implementing this keyword as a

     

       5356
       5356
       +
          shared keyword may disclose that a user considers the message to have

     

       5357
       5357
       +
          been read.  This information would be exposed to other users with

     

       5358
       5358
       +
          read permission for the Mailbox keywords.

     

       5359
       5359
       +
       

     

       5360
       5360
       +
          Published specification: this document

     

       5361
       5361
       +
       

     

       5362
       5362
       +
          Person & email address to contact for further information:

     

       5363
       5363
       +
          JMAP mailing list <jmap@ietf.org>

     

       5364
       5364
       +
       

     

       5365
       5365
       +
          Intended usage: COMMON

     

       5366
       5366
       +
       

     

       5367
       5367
       +
          Owner/Change controller: IESG

     

       5368
       5368
       +
       

     

       5369
       5369
       +
       

     

       5370
       5370
       +
       

     

       5371
       5371
       +
       

     

       5372
       5372
       +
       

     

       5373
       5373
       +
       

     

       5374
       5374
       +
       

     

       5375
       5375
       +
       

     

       5376
       5376
       +
       

     

       5377
       5377
       +
       

     

       5378
       5378
       +
       Jenkins & Newman             Standards Track                   [Page 96]

     

       5379
       5379
       +
       

     

       5380
       5380
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5381
       5381
       +
       

     

       5382
       5382
       +
       

     

       5383
       5383
       +
       10.4.3.  Registration of JMAP Keyword "$flagged"

     

       5384
       5384
       +
       

     

       5385
       5385
       +
          This registers the "JMAP-only" keyword "$flagged" in the "IMAP and

     

       5386
       5386
       +
          JMAP Keywords" registry.

     

       5387
       5387
       +
       

     

       5388
       5388
       +
          Keyword name: $flagged

     

       5389
       5389
       +
       

     

       5390
       5390
       +
          Scope: JMAP-only

     

       5391
       5391
       +
       

     

       5392
       5392
       +
          Purpose (description): This is set when the user wants to treat the

     

       5393
       5393
       +
          message as flagged for urgent/special attention.  This is the JMAP

     

       5394
       5394
       +
          equivalent of the IMAP \Flagged flag.

     

       5395
       5395
       +
       

     

       5396
       5396
       +
          Private or Shared on a server: BOTH

     

       5397
       5397
       +
       

     

       5398
       5398
       +
          Is it an advisory keyword or may it cause an automatic action:

     

       5399
       5399
       +
          Automatic.  If the account has an IMAP mailbox marked with the

     

       5400
       5400
       +
          \Flagged special use attribute [RFC6154], setting this flag MAY cause

     

       5401
       5401
       +
          the message to appear in that mailbox automatically.

     

       5402
       5402
       +
       

     

       5403
       5403
       +
          When/by whom the keyword is set/cleared: JMAP clients typically allow

     

       5404
       5404
       +
          a user to set/clear this flag as desired.  In a mail store shared by

     

       5405
       5405
       +
          JMAP and IMAP, this is also set and cleared as necessary so it

     

       5406
       5406
       +
          matches the IMAP \Flagged flag.

     

       5407
       5407
       +
       

     

       5408
       5408
       +
          Related keywords: None

     

       5409
       5409
       +
       

     

       5410
       5410
       +
          Related IMAP/JMAP Capabilities: SPECIAL-USE [RFC6154]

     

       5411
       5411
       +
       

     

       5412
       5412
       +
          Security Considerations: A server implementing this keyword as a

     

       5413
       5413
       +
          shared keyword may disclose that a user considers the message as

     

       5414
       5414
       +
          flagged for urgent/special attention.  This information would be

     

       5415
       5415
       +
          exposed to other users with read permission for the Mailbox keywords.

     

       5416
       5416
       +
       

     

       5417
       5417
       +
          Published specification: this document

     

       5418
       5418
       +
       

     

       5419
       5419
       +
          Person & email address to contact for further information:

     

       5420
       5420
       +
          JMAP mailing list <jmap@ietf.org>

     

       5421
       5421
       +
       

     

       5422
       5422
       +
          Intended usage: COMMON

     

       5423
       5423
       +
       

     

       5424
       5424
       +
          Owner/Change controller: IESG

     

       5425
       5425
       +
       

     

       5426
       5426
       +
       

     

       5427
       5427
       +
       

     

       5428
       5428
       +
       

     

       5429
       5429
       +
       

     

       5430
       5430
       +
       

     

       5431
       5431
       +
       

     

       5432
       5432
       +
       

     

       5433
       5433
       +
       

     

       5434
       5434
       +
       Jenkins & Newman             Standards Track                   [Page 97]

     

       5435
       5435
       +
       

     

       5436
       5436
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5437
       5437
       +
       

     

       5438
       5438
       +
       

     

       5439
       5439
       +
       10.4.4.  Registration of JMAP Keyword "$answered"

     

       5440
       5440
       +
       

     

       5441
       5441
       +
          This registers the "JMAP-only" keyword "$answered" in the "IMAP and

     

       5442
       5442
       +
          JMAP Keywords" registry.

     

       5443
       5443
       +
       

     

       5444
       5444
       +
          Keyword name: $answered

     

       5445
       5445
       +
       

     

       5446
       5446
       +
          Scope: JMAP-only

     

       5447
       5447
       +
       

     

       5448
       5448
       +
          Purpose (description): This is set when the message has been

     

       5449
       5449
       +
          answered.

     

       5450
       5450
       +
       

     

       5451
       5451
       +
          Private or Shared on a server: BOTH

     

       5452
       5452
       +
       

     

       5453
       5453
       +
          Is it an advisory keyword or may it cause an automatic action:

     

       5454
       5454
       +
          Advisory.

     

       5455
       5455
       +
       

     

       5456
       5456
       +
          When/by whom the keyword is set/cleared: JMAP clients typically set

     

       5457
       5457
       +
          this when submitting a reply or answer to the message.  It may be set

     

       5458
       5458
       +
          by the "EmailSubmission/set" operation with an "onSuccessUpdateEmail"

     

       5459
       5459
       +
          argument.  In a mail store shared by JMAP and IMAP, this is also set

     

       5460
       5460
       +
          and cleared as necessary so it matches the IMAP \Answered flag.

     

       5461
       5461
       +
       

     

       5462
       5462
       +
          Related keywords: None

     

       5463
       5463
       +
       

     

       5464
       5464
       +
          Related IMAP/JMAP Capabilities: None

     

       5465
       5465
       +
       

     

       5466
       5466
       +
          Security Considerations: A server implementing this keyword as a

     

       5467
       5467
       +
          shared keyword may disclose that a user has replied to a message.

     

       5468
       5468
       +
          This information would be exposed to other users with read permission

     

       5469
       5469
       +
          for the Mailbox keywords.

     

       5470
       5470
       +
       

     

       5471
       5471
       +
          Published specification: this document

     

       5472
       5472
       +
       

     

       5473
       5473
       +
          Person & email address to contact for further information:

     

       5474
       5474
       +
          JMAP mailing list <jmap@ietf.org>

     

       5475
       5475
       +
       

     

       5476
       5476
       +
          Intended usage: COMMON

     

       5477
       5477
       +
       

     

       5478
       5478
       +
          Owner/Change controller: IESG

     

       5479
       5479
       +
       

     

       5480
       5480
       +
       

     

       5481
       5481
       +
       

     

       5482
       5482
       +
       

     

       5483
       5483
       +
       

     

       5484
       5484
       +
       

     

       5485
       5485
       +
       

     

       5486
       5486
       +
       

     

       5487
       5487
       +
       

     

       5488
       5488
       +
       

     

       5489
       5489
       +
       

     

       5490
       5490
       +
       Jenkins & Newman             Standards Track                   [Page 98]

     

       5491
       5491
       +
       

     

       5492
       5492
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5493
       5493
       +
       

     

       5494
       5494
       +
       

     

       5495
       5495
       +
       10.4.5.  Registration of "$recent" Keyword

     

       5496
       5496
       +
       

     

       5497
       5497
       +
          This registers the keyword "$recent" in the "IMAP and JMAP Keywords"

     

       5498
       5498
       +
          registry.

     

       5499
       5499
       +
       

     

       5500
       5500
       +
          Keyword name: $recent

     

       5501
       5501
       +
       

     

       5502
       5502
       +
          Scope: reserved

     

       5503
       5503
       +
       

     

       5504
       5504
       +
          Purpose (description): This keyword is not used to avoid confusion

     

       5505
       5505
       +
          with the IMAP \Recent system flag.

     

       5506
       5506
       +
       

     

       5507
       5507
       +
          Published specification: this document

     

       5508
       5508
       +
       

     

       5509
       5509
       +
          Person & email address to contact for further information:

     

       5510
       5510
       +
          JMAP mailing list <jmap@ietf.org>

     

       5511
       5511
       +
       

     

       5512
       5512
       +
          Owner/Change controller: IESG

     

       5513
       5513
       +
       

     

       5514
       5514
       +
       10.5.  IMAP Mailbox Name Attributes Registry

     

       5515
       5515
       +
       

     

       5516
       5516
       +
       10.5.1.  Registration of "inbox" Role

     

       5517
       5517
       +
       

     

       5518
       5518
       +
          This registers the "JMAP-only" "inbox" attribute in the "IMAP Mailbox

     

       5519
       5519
       +
          Name Attributes" registry, as established in [RFC8457].

     

       5520
       5520
       +
       

     

       5521
       5521
       +
          Attribute Name: Inbox

     

       5522
       5522
       +
       

     

       5523
       5523
       +
          Description: New mail is delivered here by default.

     

       5524
       5524
       +
       

     

       5525
       5525
       +
          Reference: This document, Section 10.5.1

     

       5526
       5526
       +
       

     

       5527
       5527
       +
          Usage Notes: JMAP only

     

       5528
       5528
       +
       

     

       5529
       5529
       +
       

     

       5530
       5530
       +
       

     

       5531
       5531
       +
       

     

       5532
       5532
       +
       

     

       5533
       5533
       +
       

     

       5534
       5534
       +
       

     

       5535
       5535
       +
       

     

       5536
       5536
       +
       

     

       5537
       5537
       +
       

     

       5538
       5538
       +
       

     

       5539
       5539
       +
       

     

       5540
       5540
       +
       

     

       5541
       5541
       +
       

     

       5542
       5542
       +
       

     

       5543
       5543
       +
       

     

       5544
       5544
       +
       

     

       5545
       5545
       +
       

     

       5546
       5546
       +
       Jenkins & Newman             Standards Track                   [Page 99]

     

       5547
       5547
       +
       

     

       5548
       5548
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5549
       5549
       +
       

     

       5550
       5550
       +
       

     

       5551
       5551
       +
       10.6.  JMAP Error Codes Registry

     

       5552
       5552
       +
       

     

       5553
       5553
       +
          The following subsections register several new error codes in the

     

       5554
       5554
       +
          "JMAP Error Codes" registry, as defined in [RFC8620].

     

       5555
       5555
       +
       

     

       5556
       5556
       +
       10.6.1.  mailboxHasChild

     

       5557
       5557
       +
       

     

       5558
       5558
       +
          JMAP Error Code: mailboxHasChild

     

       5559
       5559
       +
       

     

       5560
       5560
       +
          Intended use: common

     

       5561
       5561
       +
       

     

       5562
       5562
       +
          Change controller: IETF

     

       5563
       5563
       +
       

     

       5564
       5564
       +
          Reference: This document, Section 2.5

     

       5565
       5565
       +
       

     

       5566
       5566
       +
          Description: The Mailbox still has at least one child Mailbox.  The

     

       5567
       5567
       +
          client MUST remove these before it can delete the parent Mailbox.

     

       5568
       5568
       +
       

     

       5569
       5569
       +
       10.6.2.  mailboxHasEmail

     

       5570
       5570
       +
       

     

       5571
       5571
       +
          JMAP Error Code: mailboxHasEmail

     

       5572
       5572
       +
       

     

       5573
       5573
       +
          Intended use: common

     

       5574
       5574
       +
       

     

       5575
       5575
       +
          Change controller: IETF

     

       5576
       5576
       +
       

     

       5577
       5577
       +
          Reference: This document, Section 2.5

     

       5578
       5578
       +
       

     

       5579
       5579
       +
          Description: The Mailbox has at least one message assigned to it, and

     

       5580
       5580
       +
          the onDestroyRemoveEmails argument was false.

     

       5581
       5581
       +
       

     

       5582
       5582
       +
       10.6.3.  blobNotFound

     

       5583
       5583
       +
       

     

       5584
       5584
       +
          JMAP Error Code: blobNotFound

     

       5585
       5585
       +
       

     

       5586
       5586
       +
          Intended use: common

     

       5587
       5587
       +
       

     

       5588
       5588
       +
          Change controller: IETF

     

       5589
       5589
       +
       

     

       5590
       5590
       +
          Reference: This document, Section 4.6

     

       5591
       5591
       +
       

     

       5592
       5592
       +
          Description: At least one blob id referenced in the object doesn't

     

       5593
       5593
       +
          exist.

     

       5594
       5594
       +
       

     

       5595
       5595
       +
       

     

       5596
       5596
       +
       

     

       5597
       5597
       +
       

     

       5598
       5598
       +
       

     

       5599
       5599
       +
       

     

       5600
       5600
       +
       

     

       5601
       5601
       +
       

     

       5602
       5602
       +
       Jenkins & Newman             Standards Track                  [Page 100]

     

       5603
       5603
       +
       

     

       5604
       5604
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5605
       5605
       +
       

     

       5606
       5606
       +
       

     

       5607
       5607
       +
       10.6.4.  tooManyKeywords

     

       5608
       5608
       +
       

     

       5609
       5609
       +
          JMAP Error Code: tooManyKeywords

     

       5610
       5610
       +
       

     

       5611
       5611
       +
          Intended use: common

     

       5612
       5612
       +
       

     

       5613
       5613
       +
          Change controller: IETF

     

       5614
       5614
       +
       

     

       5615
       5615
       +
          Reference: This document, Section 4.6

     

       5616
       5616
       +
       

     

       5617
       5617
       +
          Description: The change to the Email's keywords would exceed a

     

       5618
       5618
       +
          server-defined maximum.

     

       5619
       5619
       +
       

     

       5620
       5620
       +
       10.6.5.  tooManyMailboxes

     

       5621
       5621
       +
       

     

       5622
       5622
       +
          JMAP Error Code: tooManyMailboxes

     

       5623
       5623
       +
       

     

       5624
       5624
       +
          Intended use: common

     

       5625
       5625
       +
       

     

       5626
       5626
       +
          Change controller: IETF

     

       5627
       5627
       +
       

     

       5628
       5628
       +
          Reference: This document, Section 4.6

     

       5629
       5629
       +
       

     

       5630
       5630
       +
          Description: The change to the set of Mailboxes that this Email is in

     

       5631
       5631
       +
          would exceed a server-defined maximum.

     

       5632
       5632
       +
       

     

       5633
       5633
       +
       10.6.6.  invalidEmail

     

       5634
       5634
       +
       

     

       5635
       5635
       +
          JMAP Error Code: invalidEmail

     

       5636
       5636
       +
       

     

       5637
       5637
       +
          Intended use: common

     

       5638
       5638
       +
       

     

       5639
       5639
       +
          Change controller: IETF

     

       5640
       5640
       +
       

     

       5641
       5641
       +
          Reference: This document, Section 7.5

     

       5642
       5642
       +
       

     

       5643
       5643
       +
          Description: The Email to be sent is invalid in some way.

     

       5644
       5644
       +
       

     

       5645
       5645
       +
       

     

       5646
       5646
       +
       

     

       5647
       5647
       +
       

     

       5648
       5648
       +
       

     

       5649
       5649
       +
       

     

       5650
       5650
       +
       

     

       5651
       5651
       +
       

     

       5652
       5652
       +
       

     

       5653
       5653
       +
       

     

       5654
       5654
       +
       

     

       5655
       5655
       +
       

     

       5656
       5656
       +
       

     

       5657
       5657
       +
       

     

       5658
       5658
       +
       Jenkins & Newman             Standards Track                  [Page 101]

     

       5659
       5659
       +
       

     

       5660
       5660
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5661
       5661
       +
       

     

       5662
       5662
       +
       

     

       5663
       5663
       +
       10.6.7.  tooManyRecipients

     

       5664
       5664
       +
       

     

       5665
       5665
       +
          JMAP Error Code: tooManyRecipients

     

       5666
       5666
       +
       

     

       5667
       5667
       +
          Intended use: common

     

       5668
       5668
       +
       

     

       5669
       5669
       +
          Change controller: IETF

     

       5670
       5670
       +
       

     

       5671
       5671
       +
          Reference: This document, Section 7.5

     

       5672
       5672
       +
       

     

       5673
       5673
       +
          Description: The envelope [RFC5321] (supplied or generated) has more

     

       5674
       5674
       +
          recipients than the server allows.

     

       5675
       5675
       +
       

     

       5676
       5676
       +
       10.6.8.  noRecipients

     

       5677
       5677
       +
       

     

       5678
       5678
       +
          JMAP Error Code: noRecipients

     

       5679
       5679
       +
       

     

       5680
       5680
       +
          Intended use: common

     

       5681
       5681
       +
       

     

       5682
       5682
       +
          Change controller: IETF

     

       5683
       5683
       +
       

     

       5684
       5684
       +
          Reference: This document, Section 7.5

     

       5685
       5685
       +
       

     

       5686
       5686
       +
          Description: The envelope [RFC5321] (supplied or generated) does not

     

       5687
       5687
       +
          have any rcptTo email addresses.

     

       5688
       5688
       +
       

     

       5689
       5689
       +
       10.6.9.  invalidRecipients

     

       5690
       5690
       +
       

     

       5691
       5691
       +
          JMAP Error Code: invalidRecipients

     

       5692
       5692
       +
       

     

       5693
       5693
       +
          Intended use: common

     

       5694
       5694
       +
       

     

       5695
       5695
       +
          Change controller: IETF

     

       5696
       5696
       +
       

     

       5697
       5697
       +
          Reference: This document, Section 7.5

     

       5698
       5698
       +
       

     

       5699
       5699
       +
          Description: The rcptTo property of the envelope [RFC5321] (supplied

     

       5700
       5700
       +
          or generated) contains at least one rcptTo value that is not a valid

     

       5701
       5701
       +
          email address for sending to.

     

       5702
       5702
       +
       

     

       5703
       5703
       +
       

     

       5704
       5704
       +
       

     

       5705
       5705
       +
       

     

       5706
       5706
       +
       

     

       5707
       5707
       +
       

     

       5708
       5708
       +
       

     

       5709
       5709
       +
       

     

       5710
       5710
       +
       

     

       5711
       5711
       +
       

     

       5712
       5712
       +
       

     

       5713
       5713
       +
       

     

       5714
       5714
       +
       Jenkins & Newman             Standards Track                  [Page 102]

     

       5715
       5715
       +
       

     

       5716
       5716
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5717
       5717
       +
       

     

       5718
       5718
       +
       

     

       5719
       5719
       +
       10.6.10.  forbiddenMailFrom

     

       5720
       5720
       +
       

     

       5721
       5721
       +
          JMAP Error Code: forbiddenMailFrom

     

       5722
       5722
       +
       

     

       5723
       5723
       +
          Intended use: common

     

       5724
       5724
       +
       

     

       5725
       5725
       +
          Change controller: IETF

     

       5726
       5726
       +
       

     

       5727
       5727
       +
          Reference: This document, Section 7.5

     

       5728
       5728
       +
       

     

       5729
       5729
       +
          Description: The server does not permit the user to send a message

     

       5730
       5730
       +
          with this envelope From address [RFC5321].

     

       5731
       5731
       +
       

     

       5732
       5732
       +
       10.6.11.  forbiddenFrom

     

       5733
       5733
       +
       

     

       5734
       5734
       +
          JMAP Error Code: forbiddenFrom

     

       5735
       5735
       +
       

     

       5736
       5736
       +
          Intended use: common

     

       5737
       5737
       +
       

     

       5738
       5738
       +
          Change controller: IETF

     

       5739
       5739
       +
       

     

       5740
       5740
       +
          Reference: This document, Sections 6.3 and 7.5

     

       5741
       5741
       +
       

     

       5742
       5742
       +
          Description: The server does not permit the user to send a message

     

       5743
       5743
       +
          with the From header field [RFC5322] of the message to be sent.

     

       5744
       5744
       +
       

     

       5745
       5745
       +
       10.6.12.  forbiddenToSend

     

       5746
       5746
       +
       

     

       5747
       5747
       +
          JMAP Error Code: forbiddenToSend

     

       5748
       5748
       +
       

     

       5749
       5749
       +
          Intended use: common

     

       5750
       5750
       +
       

     

       5751
       5751
       +
          Change controller: IETF

     

       5752
       5752
       +
       

     

       5753
       5753
       +
          Reference: This document, Section 7.5

     

       5754
       5754
       +
       

     

       5755
       5755
       +
          Description: The user does not have permission to send at all right

     

       5756
       5756
       +
          now.

     

       5757
       5757
       +
       

     

       5758
       5758
       +
       

     

       5759
       5759
       +
       

     

       5760
       5760
       +
       

     

       5761
       5761
       +
       

     

       5762
       5762
       +
       

     

       5763
       5763
       +
       

     

       5764
       5764
       +
       

     

       5765
       5765
       +
       

     

       5766
       5766
       +
       

     

       5767
       5767
       +
       

     

       5768
       5768
       +
       

     

       5769
       5769
       +
       

     

       5770
       5770
       +
       Jenkins & Newman             Standards Track                  [Page 103]

     

       5771
       5771
       +
       

     

       5772
       5772
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5773
       5773
       +
       

     

       5774
       5774
       +
       

     

       5775
       5775
       +
       11.  References

     

       5776
       5776
       +
       

     

       5777
       5777
       +
       11.1.  Normative References

     

       5778
       5778
       +
       

     

       5779
       5779
       +
          [HTML]     Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and

     

       5780
       5780
       +
                     S. Moon, "HTML 5.2", World Wide Web Consortium

     

       5781
       5781
       +
                     Recommendation REC-html52-20171214, December 2017,

     

       5782
       5782
       +
                     <https://www.w3.org/TR/html52/>.

     

       5783
       5783
       +
       

     

       5784
       5784
       +
          [RFC1870]  Klensin, J., Freed, N., and K. Moore, "SMTP Service

     

       5785
       5785
       +
                     Extension for Message Size Declaration", STD 10, RFC 1870,

     

       5786
       5786
       +
                     DOI 10.17487/RFC1870, November 1995,

     

       5787
       5787
       +
                     <https://www.rfc-editor.org/info/rfc1870>.

     

       5788
       5788
       +
       

     

       5789
       5789
       +
          [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail

     

       5790
       5790
       +
                     Extensions (MIME) Part One: Format of Internet Message

     

       5791
       5791
       +
                     Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,

     

       5792
       5792
       +
                     <https://www.rfc-editor.org/info/rfc2045>.

     

       5793
       5793
       +
       

     

       5794
       5794
       +
          [RFC2047]  Moore, K., "MIME (Multipurpose Internet Mail Extensions)

     

       5795
       5795
       +
                     Part Three: Message Header Extensions for Non-ASCII Text",

     

       5796
       5796
       +
                     RFC 2047, DOI 10.17487/RFC2047, November 1996,

     

       5797
       5797
       +
                     <https://www.rfc-editor.org/info/rfc2047>.

     

       5798
       5798
       +
       

     

       5799
       5799
       +
          [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate

     

       5800
       5800
       +
                     Requirement Levels", BCP 14, RFC 2119,

     

       5801
       5801
       +
                     DOI 10.17487/RFC2119, March 1997,

     

       5802
       5802
       +
                     <https://www.rfc-editor.org/info/rfc2119>.

     

       5803
       5803
       +
       

     

       5804
       5804
       +
          [RFC2231]  Freed, N. and K. Moore, "MIME Parameter Value and Encoded

     

       5805
       5805
       +
                     Word Extensions: Character Sets, Languages, and

     

       5806
       5806
       +
                     Continuations", RFC 2231, DOI 10.17487/RFC2231, November

     

       5807
       5807
       +
                     1997, <https://www.rfc-editor.org/info/rfc2231>.

     

       5808
       5808
       +
       

     

       5809
       5809
       +
          [RFC2369]  Neufeld, G. and J. Baer, "The Use of URLs as Meta-Syntax

     

       5810
       5810
       +
                     for Core Mail List Commands and their Transport through

     

       5811
       5811
       +
                     Message Header Fields", RFC 2369, DOI 10.17487/RFC2369,

     

       5812
       5812
       +
                     July 1998, <https://www.rfc-editor.org/info/rfc2369>.

     

       5813
       5813
       +
       

     

       5814
       5814
       +
          [RFC2392]  Levinson, E., "Content-ID and Message-ID Uniform Resource

     

       5815
       5815
       +
                     Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998,

     

       5816
       5816
       +
                     <https://www.rfc-editor.org/info/rfc2392>.

     

       5817
       5817
       +
       

     

       5818
       5818
       +
          [RFC2557]  Palme, J., Hopmann, A., and N. Shelness, "MIME

     

       5819
       5819
       +
                     Encapsulation of Aggregate Documents, such as HTML

     

       5820
       5820
       +
                     (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999,

     

       5821
       5821
       +
                     <https://www.rfc-editor.org/info/rfc2557>.

     

       5822
       5822
       +
       

     

       5823
       5823
       +
       

     

       5824
       5824
       +
       

     

       5825
       5825
       +
       

     

       5826
       5826
       +
       Jenkins & Newman             Standards Track                  [Page 104]

     

       5827
       5827
       +
       

     

       5828
       5828
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5829
       5829
       +
       

     

       5830
       5830
       +
       

     

       5831
       5831
       +
          [RFC2852]  Newman, D., "Deliver By SMTP Service Extension", RFC 2852,

     

       5832
       5832
       +
                     DOI 10.17487/RFC2852, June 2000,

     

       5833
       5833
       +
                     <https://www.rfc-editor.org/info/rfc2852>.

     

       5834
       5834
       +
       

     

       5835
       5835
       +
          [RFC3282]  Alvestrand, H., "Content Language Headers", RFC 3282,

     

       5836
       5836
       +
                     DOI 10.17487/RFC3282, May 2002,

     

       5837
       5837
       +
                     <https://www.rfc-editor.org/info/rfc3282>.

     

       5838
       5838
       +
       

     

       5839
       5839
       +
          [RFC3461]  Moore, K., "Simple Mail Transfer Protocol (SMTP) Service

     

       5840
       5840
       +
                     Extension for Delivery Status Notifications (DSNs)",

     

       5841
       5841
       +
                     RFC 3461, DOI 10.17487/RFC3461, January 2003,

     

       5842
       5842
       +
                     <https://www.rfc-editor.org/info/rfc3461>.

     

       5843
       5843
       +
       

     

       5844
       5844
       +
          [RFC3463]  Vaudreuil, G., "Enhanced Mail System Status Codes",

     

       5845
       5845
       +
                     RFC 3463, DOI 10.17487/RFC3463, January 2003,

     

       5846
       5846
       +
                     <https://www.rfc-editor.org/info/rfc3463>.

     

       5847
       5847
       +
       

     

       5848
       5848
       +
          [RFC3464]  Moore, K. and G. Vaudreuil, "An Extensible Message Format

     

       5849
       5849
       +
                     for Delivery Status Notifications", RFC 3464,

     

       5850
       5850
       +
                     DOI 10.17487/RFC3464, January 2003,

     

       5851
       5851
       +
                     <https://www.rfc-editor.org/info/rfc3464>.

     

       5852
       5852
       +
       

     

       5853
       5853
       +
          [RFC3834]  Moore, K., "Recommendations for Automatic Responses to

     

       5854
       5854
       +
                     Electronic Mail", RFC 3834, DOI 10.17487/RFC3834, August

     

       5855
       5855
       +
                     2004, <https://www.rfc-editor.org/info/rfc3834>.

     

       5856
       5856
       +
       

     

       5857
       5857
       +
          [RFC4314]  Melnikov, A., "IMAP4 Access Control List (ACL) Extension",

     

       5858
       5858
       +
                     RFC 4314, DOI 10.17487/RFC4314, December 2005,

     

       5859
       5859
       +
                     <https://www.rfc-editor.org/info/rfc4314>.

     

       5860
       5860
       +
       

     

       5861
       5861
       +
          [RFC4422]  Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple

     

       5862
       5862
       +
                     Authentication and Security Layer (SASL)", RFC 4422,

     

       5863
       5863
       +
                     DOI 10.17487/RFC4422, June 2006,

     

       5864
       5864
       +
                     <https://www.rfc-editor.org/info/rfc4422>.

     

       5865
       5865
       +
       

     

       5866
       5866
       +
          [RFC4616]  Zeilenga, K., Ed., "The PLAIN Simple Authentication and

     

       5867
       5867
       +
                     Security Layer (SASL) Mechanism", RFC 4616,

     

       5868
       5868
       +
                     DOI 10.17487/RFC4616, August 2006,

     

       5869
       5869
       +
                     <https://www.rfc-editor.org/info/rfc4616>.

     

       5870
       5870
       +
       

     

       5871
       5871
       +
          [RFC4865]  White, G. and G. Vaudreuil, "SMTP Submission Service

     

       5872
       5872
       +
                     Extension for Future Message Release", RFC 4865,

     

       5873
       5873
       +
                     DOI 10.17487/RFC4865, May 2007,

     

       5874
       5874
       +
                     <https://www.rfc-editor.org/info/rfc4865>.

     

       5875
       5875
       +
       

     

       5876
       5876
       +
       

     

       5877
       5877
       +
       

     

       5878
       5878
       +
       

     

       5879
       5879
       +
       

     

       5880
       5880
       +
       

     

       5881
       5881
       +
       

     

       5882
       5882
       +
       Jenkins & Newman             Standards Track                  [Page 105]

     

       5883
       5883
       +
       

     

       5884
       5884
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5885
       5885
       +
       

     

       5886
       5886
       +
       

     

       5887
       5887
       +
          [RFC4954]  Siemborski, R., Ed. and A. Melnikov, Ed., "SMTP Service

     

       5888
       5888
       +
                     Extension for Authentication", RFC 4954,

     

       5889
       5889
       +
                     DOI 10.17487/RFC4954, July 2007,

     

       5890
       5890
       +
                     <https://www.rfc-editor.org/info/rfc4954>.

     

       5891
       5891
       +
       

     

       5892
       5892
       +
          [RFC5198]  Klensin, J. and M. Padlipsky, "Unicode Format for Network

     

       5893
       5893
       +
                     Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,

     

       5894
       5894
       +
                     <https://www.rfc-editor.org/info/rfc5198>.

     

       5895
       5895
       +
       

     

       5896
       5896
       +
          [RFC5248]  Hansen, T. and J. Klensin, "A Registry for SMTP Enhanced

     

       5897
       5897
       +
                     Mail System Status Codes", BCP 138, RFC 5248,

     

       5898
       5898
       +
                     DOI 10.17487/RFC5248, June 2008,

     

       5899
       5899
       +
                     <https://www.rfc-editor.org/info/rfc5248>.

     

       5900
       5900
       +
       

     

       5901
       5901
       +
          [RFC5256]  Crispin, M. and K. Murchison, "Internet Message Access

     

       5902
       5902
       +
                     Protocol - SORT and THREAD Extensions", RFC 5256,

     

       5903
       5903
       +
                     DOI 10.17487/RFC5256, June 2008,

     

       5904
       5904
       +
                     <https://www.rfc-editor.org/info/rfc5256>.

     

       5905
       5905
       +
       

     

       5906
       5906
       +
          [RFC5321]  Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,

     

       5907
       5907
       +
                     DOI 10.17487/RFC5321, October 2008,

     

       5908
       5908
       +
                     <https://www.rfc-editor.org/info/rfc5321>.

     

       5909
       5909
       +
       

     

       5910
       5910
       +
          [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,

     

       5911
       5911
       +
                     DOI 10.17487/RFC5322, October 2008,

     

       5912
       5912
       +
                     <https://www.rfc-editor.org/info/rfc5322>.

     

       5913
       5913
       +
       

     

       5914
       5914
       +
          [RFC5788]  Melnikov, A. and D. Cridland, "IMAP4 Keyword Registry",

     

       5915
       5915
       +
                     RFC 5788, DOI 10.17487/RFC5788, March 2010,

     

       5916
       5916
       +
                     <https://www.rfc-editor.org/info/rfc5788>.

     

       5917
       5917
       +
       

     

       5918
       5918
       +
          [RFC6154]  Leiba, B. and J. Nicolson, "IMAP LIST Extension for

     

       5919
       5919
       +
                     Special-Use Mailboxes", RFC 6154, DOI 10.17487/RFC6154,

     

       5920
       5920
       +
                     March 2011, <https://www.rfc-editor.org/info/rfc6154>.

     

       5921
       5921
       +
       

     

       5922
       5922
       +
          [RFC6409]  Gellens, R. and J. Klensin, "Message Submission for Mail",

     

       5923
       5923
       +
                     STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011,

     

       5924
       5924
       +
                     <https://www.rfc-editor.org/info/rfc6409>.

     

       5925
       5925
       +
       

     

       5926
       5926
       +
          [RFC6532]  Yang, A., Steele, S., and N. Freed, "Internationalized

     

       5927
       5927
       +
                     Email Headers", RFC 6532, DOI 10.17487/RFC6532, February

     

       5928
       5928
       +
                     2012, <https://www.rfc-editor.org/info/rfc6532>.

     

       5929
       5929
       +
       

     

       5930
       5930
       +
          [RFC6533]  Hansen, T., Ed., Newman, C., and A. Melnikov,

     

       5931
       5931
       +
                     "Internationalized Delivery Status and Disposition

     

       5932
       5932
       +
                     Notifications", RFC 6533, DOI 10.17487/RFC6533, February

     

       5933
       5933
       +
                     2012, <https://www.rfc-editor.org/info/rfc6533>.

     

       5934
       5934
       +
       

     

       5935
       5935
       +
       

     

       5936
       5936
       +
       

     

       5937
       5937
       +
       

     

       5938
       5938
       +
       Jenkins & Newman             Standards Track                  [Page 106]

     

       5939
       5939
       +
       

     

       5940
       5940
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5941
       5941
       +
       

     

       5942
       5942
       +
       

     

       5943
       5943
       +
          [RFC6710]  Melnikov, A. and K. Carlberg, "Simple Mail Transfer

     

       5944
       5944
       +
                     Protocol Extension for Message Transfer Priorities",

     

       5945
       5945
       +
                     RFC 6710, DOI 10.17487/RFC6710, August 2012,

     

       5946
       5946
       +
                     <https://www.rfc-editor.org/info/rfc6710>.

     

       5947
       5947
       +
       

     

       5948
       5948
       +
          [RFC7677]  Hansen, T., "SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple

     

       5949
       5949
       +
                     Authentication and Security Layer (SASL) Mechanisms",

     

       5950
       5950
       +
                     RFC 7677, DOI 10.17487/RFC7677, November 2015,

     

       5951
       5951
       +
                     <https://www.rfc-editor.org/info/rfc7677>.

     

       5952
       5952
       +
       

     

       5953
       5953
       +
          [RFC8098]  Hansen, T., Ed. and A. Melnikov, Ed., "Message Disposition

     

       5954
       5954
       +
                     Notification", STD 85, RFC 8098, DOI 10.17487/RFC8098,

     

       5955
       5955
       +
                     February 2017, <https://www.rfc-editor.org/info/rfc8098>.

     

       5956
       5956
       +
       

     

       5957
       5957
       +
          [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC

     

       5958
       5958
       +
                     2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,

     

       5959
       5959
       +
                     May 2017, <https://www.rfc-editor.org/info/rfc8174>.

     

       5960
       5960
       +
       

     

       5961
       5961
       +
          [RFC8314]  Moore, K. and C. Newman, "Cleartext Considered Obsolete:

     

       5962
       5962
       +
                     Use of Transport Layer Security (TLS) for Email Submission

     

       5963
       5963
       +
                     and Access", RFC 8314, DOI 10.17487/RFC8314, January 2018,

     

       5964
       5964
       +
                     <https://www.rfc-editor.org/info/rfc8314>.

     

       5965
       5965
       +
       

     

       5966
       5966
       +
          [RFC8457]  Leiba, B., Ed., "IMAP "$Important" Keyword and

     

       5967
       5967
       +
                     "\Important" Special-Use Attribute", RFC 8457,

     

       5968
       5968
       +
                     DOI 10.17487/RFC8457, September 2018,

     

       5969
       5969
       +
                     <https://www.rfc-editor.org/info/rfc8457>.

     

       5970
       5970
       +
       

     

       5971
       5971
       +
          [RFC8474]  Gondwana, B., Ed., "IMAP Extension for Object

     

       5972
       5972
       +
                     Identifiers", RFC 8474, DOI 10.17487/RFC8474, September

     

       5973
       5973
       +
                     2018, <https://www.rfc-editor.org/info/rfc8474>.

     

       5974
       5974
       +
       

     

       5975
       5975
       +
          [RFC8620]  Jenkins, N. and C. Newman, "The JSON Meta Application

     

       5976
       5976
       +
                     Protocol", RFC 8620, DOI 10.17487/RFC8620, June 2019,

     

       5977
       5977
       +
                     <https://www.rfc-editor.org/info/rfc8620>.

     

       5978
       5978
       +
       

     

       5979
       5979
       +
       11.2.  Informative References

     

       5980
       5980
       +
       

     

       5981
       5981
       +
          [EFAIL]    Poddebniak, D., Dresen, C., Mueller, J., Ising, F.,

     

       5982
       5982
       +
                     Schinzel, S., Friedberger, S., Somorovsky, J., and J.

     

       5983
       5983
       +
                     Schwenk, "Efail: Breaking S/MIME and OpenPGP Email

     

       5984
       5984
       +
                     Encryption using Exfiltration Channels", August 2018,

     

       5985
       5985
       +
                     <https://www.usenix.org/system/files/conference/

     

       5986
       5986
       +
                     usenixsecurity18/sec18-poddebniak.pdf>.

     

       5987
       5987
       +
       

     

       5988
       5988
       +
          [milter]   Postfix, "Postfix before-queue Milter support", 2019,

     

       5989
       5989
       +
                     <http://www.postfix.org/MILTER_README.html>.

     

       5990
       5990
       +
       

     

       5991
       5991
       +
       

     

       5992
       5992
       +
       

     

       5993
       5993
       +
       

     

       5994
       5994
       +
       Jenkins & Newman             Standards Track                  [Page 107]

     

       5995
       5995
       +
       

     

       5996
       5996
       +
       RFC 8621                        JMAP Mail                    August 2019

     

       5997
       5997
       +
       

     

       5998
       5998
       +
       

     

       5999
       5999
       +
          [RFC3501]  Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION

     

       6000
       6000
       +
                     4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,

     

       6001
       6001
       +
                     <https://www.rfc-editor.org/info/rfc3501>.

     

       6002
       6002
       +
       

     

       6003
       6003
       +
          [RFC7489]  Kucherawy, M., Ed. and E. Zwicky, Ed., "Domain-based

     

       6004
       6004
       +
                     Message Authentication, Reporting, and Conformance

     

       6005
       6005
       +
                     (DMARC)", RFC 7489, DOI 10.17487/RFC7489, March 2015,

     

       6006
       6006
       +
                     <https://www.rfc-editor.org/info/rfc7489>.

     

       6007
       6007
       +
       

     

       6008
       6008
       +
          [XCLIENT]  Postfix, "Postfix XCLIENT Howto", 2019,

     

       6009
       6009
       +
                     <http://www.postfix.org/XCLIENT_README.html>.

     

       6010
       6010
       +
       

     

       6011
       6011
       +
       Authors' Addresses

     

       6012
       6012
       +
       

     

       6013
       6013
       +
          Neil Jenkins

     

       6014
       6014
       +
          Fastmail

     

       6015
       6015
       +
          PO Box 234, Collins St. West

     

       6016
       6016
       +
          Melbourne, VIC  8007

     

       6017
       6017
       +
          Australia

     

       6018
       6018
       +
       

     

       6019
       6019
       +
          Email: neilj@fastmailteam.com

     

       6020
       6020
       +
          URI:   https://www.fastmail.com

     

       6021
       6021
       +
       

     

       6022
       6022
       +
       

     

       6023
       6023
       +
          Chris Newman

     

       6024
       6024
       +
          Oracle

     

       6025
       6025
       +
          440 E. Huntington Dr., Suite 400

     

       6026
       6026
       +
          Arcadia, CA  91006

     

       6027
       6027
       +
          United States of America

     

       6028
       6028
       +
       

     

       6029
       6029
       +
          Email: chris.newman@oracle.com

     

       6030
       6030
       +
       

     

       6031
       6031
       +
       

     

       6032
       6032
       +
       

     

       6033
       6033
       +
       

     

       6034
       6034
       +
       

     

       6035
       6035
       +
       

     

       6036
       6036
       +
       

     

       6037
       6037
       +
       

     

       6038
       6038
       +
       

     

       6039
       6039
       +
       

     

       6040
       6040
       +
       

     

       6041
       6041
       +
       

     

       6042
       6042
       +
       

     

       6043
       6043
       +
       

     

       6044
       6044
       +
       

     

       6045
       6045
       +
       

     

       6046
       6046
       +
       

     

       6047
       6047
       +
       

     

       6048
       6048
       +
       

     

       6049
       6049
       +
       

     

       6050
       6050
       +
       Jenkins & Newman             Standards Track                  [Page 108]

     

       6051
       6051
       +

Compare changes