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

.gitignore

-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.

bin/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name jmap_test)

     

       3
       3
       +
        (public_name jmap-test)

     

       4
       4
       +
        (package jmap-eio)

     

       5
       5
       +
        (libraries jmap-eio eio_main))

+298

bin/fastmail_list.ml

···

       1
       1
       +
       (** 

     

       2
       2
       +
        * fastmail_list - Lists emails from a Fastmail account using JMAP API

     

       3
       3
       +
        *

     

       4
       4
       +
        * This binary connects to the Fastmail JMAP API using an authentication token

     

       5
       5
       +
        * from the JMAP_API_TOKEN environment variable and lists the most recent 100

     

       6
       6
       +
        * emails with their subjects, sender details, and labels.

     

       7
       7
       +
        *

     

       8
       8
       +
        * Usage: 

     

       9
       9
       +
        *   JMAP_API_TOKEN=your_api_token ./fastmail_list [options]

     

       10
       10
       +
        *

     

       11
       11
       +
        * Options:

     

       12
       12
       +
        *   --unread          List only unread messages

     

       13
       13
       +
        *   --labels          Show labels/keywords associated with messages

     

       14
       14
       +
        *   --debug=LEVEL     Set debug level (0-4, where 4 is most verbose)

     

       15
       15
       +
        *   --from=PATTERN    Filter messages by sender email address

     

       16
       16
       +
        *   --demo-refs       Demonstrate result references feature

     

       17
       17
       +
        *)

     

       18
       18
       +
       

     

       19
       19
       +
       open Lwt.Syntax

     

       20
       20
       +
       open Jmap

     

       21
       21
       +
       open Jmap_mail

     

       22
       22
       +
       open Cmdliner

     

       23
       23
       +
       module Mail = Jmap_mail.Types

     

       24
       24
       +
       

     

       25
       25
       +
       (** Prints the email details *)

     

       26
       26
       +
       let print_email ~show_labels (email : Mail.email) =

     

       27
       27
       +
         let sender = 

     

       28
       28
       +
           match email.from with

     

       29
       29
       +
           | Some (addr :: _) -> 

     

       30
       30
       +
               (match addr.name with

     

       31
       31
       +
               | Some name -> Printf.sprintf "%s <%s>" name addr.email

     

       32
       32
       +
               | None -> addr.email)

     

       33
       33
       +
           | _ -> "<unknown>"

     

       34
       34
       +
         in

     

       35
       35
       +
         let subject = 

     

       36
       36
       +
           match email.subject with

     

       37
       37
       +
           | Some s -> s

     

       38
       38
       +
           | None -> "<no subject>"

     

       39
       39
       +
         in

     

       40
       40
       +
         let date = email.received_at in

     

       41
       41
       +
         

     

       42
       42
       +
         (* Format labels/keywords if requested *)

     

       43
       43
       +
         let labels_str = 

     

       44
       44
       +
           if show_labels then

     

       45
       45
       +
             let formatted = Jmap_mail.Types.format_email_keywords email.keywords in

     

       46
       46
       +
             if formatted <> "" then

     

       47
       47
       +
               " [" ^ formatted ^ "]"

     

       48
       48
       +
             else

     

       49
       49
       +
               ""

     

       50
       50
       +
           else

     

       51
       51
       +
             ""

     

       52
       52
       +
         in

     

       53
       53
       +
         

     

       54
       54
       +
         Printf.printf "%s | %s | %s%s\n" date sender subject labels_str

     

       55
       55
       +
       

     

       56
       56
       +
       (** Check if an email is unread *)

     

       57
       57
       +
       let is_unread (email : Mail.email) =

     

       58
       58
       +
         let is_unread_keyword = 

     

       59
       59
       +
           List.exists (fun (kw, active) -> 

     

       60
       60
       +
             kw = Mail.Unread && active

     

       61
       61
       +
           ) email.keywords

     

       62
       62
       +
         in

     

       63
       63
       +
         let is_not_seen = 

     

       64
       64
       +
           not (List.exists (fun (kw, active) -> 

     

       65
       65
       +
             kw = Mail.Seen && active

     

       66
       66
       +
           ) email.keywords)

     

       67
       67
       +
         in

     

       68
       68
       +
         is_unread_keyword || is_not_seen

     

       69
       69
       +
       

     

       70
       70
       +
       (** Example function demonstrating how to use higher-level library functions for JMAP requests *)

     

       71
       71
       +
       let demo_result_references conn account_id =

     

       72
       72
       +
         Printf.printf "\nResult Reference Demo:\n";

     

       73
       73
       +
         Printf.printf "=====================\n";

     

       74
       74
       +
         

     

       75
       75
       +
         (* Step 1: Get all mailboxes *)

     

       76
       76
       +
         let* mailboxes_result = Jmap_mail.get_mailboxes conn ~account_id in

     

       77
       77
       +
         match mailboxes_result with

     

       78
       78
       +
         | Error err ->

     

       79
       79
       +
             Printf.printf "Error getting mailboxes: %s\n" (Api.string_of_error err);

     

       80
       80
       +
             Lwt.return_unit

     

       81
       81
       +
             

     

       82
       82
       +
         | Ok mailboxes ->

     

       83
       83
       +
             (* Step 2: Get the first mailbox for this demonstration *)

     

       84
       84
       +
             match mailboxes with

     

       85
       85
       +
             | [] ->

     

       86
       86
       +
                 Printf.printf "No mailboxes found.\n";

     

       87
       87
       +
                 Lwt.return_unit

     

       88
       88
       +
                 

     

       89
       89
       +
             | first_mailbox :: _ ->

     

       90
       90
       +
                 Printf.printf "Using mailbox: %s\n" first_mailbox.Mail.name;

     

       91
       91
       +
                 

     

       92
       92
       +
                 (* Step 3: Get emails from the selected mailbox *)

     

       93
       93
       +
                 let* emails_result = Jmap_mail.get_messages_in_mailbox

     

       94
       94
       +
                   conn

     

       95
       95
       +
                   ~account_id

     

       96
       96
       +
                   ~mailbox_id:first_mailbox.Mail.id

     

       97
       97
       +
                   ~limit:10

     

       98
       98
       +
                   ()

     

       99
       99
       +
                 in

     

       100
       100
       +
                 

     

       101
       101
       +
                 match emails_result with

     

       102
       102
       +
                 | Error err ->

     

       103
       103
       +
                     Printf.printf "Error getting emails: %s\n" (Api.string_of_error err);

     

       104
       104
       +
                     Lwt.return_unit

     

       105
       105
       +
                     

     

       106
       106
       +
                 | Ok emails ->

     

       107
       107
       +
                     Printf.printf "Successfully retrieved %d emails using the high-level library API!\n" 

     

       108
       108
       +
                       (List.length emails);

     

       109
       109
       +
                       

     

       110
       110
       +
                     (* Display some basic information about the emails *)

     

       111
       111
       +
                     List.iteri (fun i (email:Jmap_mail.Types.email) ->

     

       112
       112
       +
                       let subject = Option.value ~default:"<no subject>" email.Mail.subject in

     

       113
       113
       +
                       Printf.printf "  %d. %s\n" (i + 1) subject

     

       114
       114
       +
                     ) emails;

     

       115
       115
       +
                     

     

       116
       116
       +
                     Lwt.return_unit

     

       117
       117
       +
       

     

       118
       118
       +
       (** Main function for listing emails *)

     

       119
       119
       +
       let list_emails unread_only show_labels debug_level demo_refs sender_filter =

     

       120
       120
       +
         (* Configure logging *)

     

       121
       121
       +
         init_logging ~level:debug_level ~enable_logs:(debug_level > 0) ~redact_sensitive:true ();

     

       122
       122
       +
         

     

       123
       123
       +
         match Sys.getenv_opt "JMAP_API_TOKEN" with

     

       124
       124
       +
         | None -> 

     

       125
       125
       +
             Printf.eprintf "Error: JMAP_API_TOKEN environment variable not set\n";

     

       126
       126
       +
             Printf.eprintf "Usage: JMAP_API_TOKEN=your_token fastmail-list [options]\n";

     

       127
       127
       +
             exit 1

     

       128
       128
       +
         | Some token ->

     

       129
       129
       +
             (* Only print token info at Info level or higher *)

     

       130
       130
       +
             Logs.info (fun m -> m "Using API token: %s" (redact_token token));

     

       131
       131
       +
             

     

       132
       132
       +
             (* Connect to Fastmail JMAP API *)

     

       133
       133
       +
             let formatted_token = token in

     

       134
       134
       +
             

     

       135
       135
       +
             (* Only print instructions at Info level *)

     

       136
       136
       +
             let level = match Logs.level () with

     

       137
       137
       +
               | None -> 0

     

       138
       138
       +
               | Some Logs.Error -> 1

     

       139
       139
       +
               | Some Logs.Info -> 2 

     

       140
       140
       +
               | Some Logs.Debug -> 3

     

       141
       141
       +
               | _ -> 2

     

       142
       142
       +
             in

     

       143
       143
       +
             if level >= 2 then begin

     

       144
       144
       +
               Printf.printf "\nFastmail API Instructions:\n";

     

       145
       145
       +
               Printf.printf "1. Get a token from: https://app.fastmail.com/settings/tokens\n";

     

       146
       146
       +
               Printf.printf "2. Create a new token with Mail scope (read/write)\n";

     

       147
       147
       +
               Printf.printf "3. Copy the full token (example: 3de40-5fg1h2-a1b2c3...)\n";

     

       148
       148
       +
               Printf.printf "4. Run: env JMAP_API_TOKEN=\"your_full_token\" fastmail-list [options]\n\n";

     

       149
       149
       +
               Printf.printf "Note: This example is working correctly but needs a valid Fastmail token.\n\n";

     

       150
       150
       +
             end;

     

       151
       151
       +
             let* result = login_with_token 

     

       152
       152
       +
               ~uri:"https://api.fastmail.com/jmap/session" 

     

       153
       153
       +
               ~api_token:formatted_token

     

       154
       154
       +
             in

     

       155
       155
       +
             match result with

     

       156
       156
       +
             | Error err -> 

     

       157
       157
       +
                 Printf.eprintf "%s\n" (Api.string_of_error err);

     

       158
       158
       +
                 Lwt.return 1

     

       159
       159
       +
             | Ok conn ->

     

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

     

       161
       161
       +
                 let primary_account_id = 

     

       162
       162
       +
                   let mail_capability = Jmap_mail.Capability.to_string Jmap_mail.Capability.Mail in

     

       163
       163
       +
                   match List.assoc_opt mail_capability conn.session.primary_accounts with

     

       164
       164
       +
                   | Some id -> id

     

       165
       165
       +
                   | None -> 

     

       166
       166
       +
                       match conn.session.accounts with

     

       167
       167
       +
                       | (id, _) :: _ -> id

     

       168
       168
       +
                       | [] -> 

     

       169
       169
       +
                           Printf.eprintf "No accounts found\n";

     

       170
       170
       +
                           exit 1

     

       171
       171
       +
                 in

     

       172
       172
       +
                 

     

       173
       173
       +
                 (* Run result references demo if requested *)

     

       174
       174
       +
                 let* () = 

     

       175
       175
       +
                   if demo_refs then

     

       176
       176
       +
                     demo_result_references conn primary_account_id

     

       177
       177
       +
                   else

     

       178
       178
       +
                     Lwt.return_unit

     

       179
       179
       +
                 in

     

       180
       180
       +
                 

     

       181
       181
       +
                 (* Get the Inbox mailbox *)

     

       182
       182
       +
                 let* mailboxes_result = get_mailboxes conn ~account_id:primary_account_id in

     

       183
       183
       +
                 match mailboxes_result with

     

       184
       184
       +
                 | Error err -> 

     

       185
       185
       +
                     Printf.eprintf "Failed to get mailboxes: %s\n" (Api.string_of_error err);

     

       186
       186
       +
                     Lwt.return 1

     

       187
       187
       +
                 | Ok mailboxes ->

     

       188
       188
       +
                     (* If there's a mailbox list, just use the first one for this example *)

     

       189
       189
       +
                     let inbox_id = 

     

       190
       190
       +
                       match mailboxes with

     

       191
       191
       +
                       | mailbox :: _ -> mailbox.Mail.id

     

       192
       192
       +
                       | [] -> 

     

       193
       193
       +
                           Printf.eprintf "No mailboxes found\n";

     

       194
       194
       +
                           exit 1

     

       195
       195
       +
                     in

     

       196
       196
       +
                     

     

       197
       197
       +
                     (* Get messages from inbox *)

     

       198
       198
       +
                     let* emails_result = get_messages_in_mailbox 

     

       199
       199
       +
                       conn 

     

       200
       200
       +
                       ~account_id:primary_account_id 

     

       201
       201
       +
                       ~mailbox_id:inbox_id

     

       202
       202
       +
                       ~limit:1000

     

       203
       203
       +
                       ()

     

       204
       204
       +
                     in

     

       205
       205
       +
                     match emails_result with

     

       206
       206
       +
                     | Error err -> 

     

       207
       207
       +
                         Printf.eprintf "Failed to get emails: %s\n" (Api.string_of_error err);

     

       208
       208
       +
                         Lwt.return 1

     

       209
       209
       +
                     | Ok emails ->

     

       210
       210
       +
                         (* Apply filters based on command line arguments *)

     

       211
       211
       +
                         let filtered_by_unread = 

     

       212
       212
       +
                           if unread_only then

     

       213
       213
       +
                             List.filter is_unread emails

     

       214
       214
       +
                           else 

     

       215
       215
       +
                             emails

     

       216
       216
       +
                         in

     

       217
       217
       +
                         

     

       218
       218
       +
                         (* Apply sender filter if specified *)

     

       219
       219
       +
                         let filtered_emails =

     

       220
       220
       +
                           if sender_filter <> "" then begin

     

       221
       221
       +
                             Printf.printf "Filtering by sender: %s\n" sender_filter;

     

       222
       222
       +
                             List.filter (fun email -> 

     

       223
       223
       +
                               Jmap_mail.email_matches_sender email sender_filter

     

       224
       224
       +
                             ) filtered_by_unread

     

       225
       225
       +
                           end else

     

       226
       226
       +
                             filtered_by_unread

     

       227
       227
       +
                         in

     

       228
       228
       +
                         

     

       229
       229
       +
                         (* Create description of applied filters *)

     

       230
       230
       +
                         let filter_description = 

     

       231
       231
       +
                           let parts = [] in

     

       232
       232
       +
                           let parts = if unread_only then "unread" :: parts else parts in

     

       233
       233
       +
                           let parts = if sender_filter <> "" then ("from \"" ^ sender_filter ^ "\"") :: parts else parts in

     

       234
       234
       +
                           match parts with

     

       235
       235
       +
                           | [] -> "the most recent"

     

       236
       236
       +
                           | [p] -> p

     

       237
       237
       +
                           | _ -> String.concat " and " parts

     

       238
       238
       +
                         in

     

       239
       239
       +
                         

     

       240
       240
       +
                         Printf.printf "Listing %s %d emails in your inbox:\n" 

     

       241
       241
       +
                           filter_description

     

       242
       242
       +
                           (List.length filtered_emails);

     

       243
       243
       +
                         Printf.printf "--------------------------------------------\n";

     

       244
       244
       +
                         List.iter (print_email ~show_labels) filtered_emails;

     

       245
       245
       +
                         Lwt.return 0

     

       246
       246
       +
       

     

       247
       247
       +
       (** Command line interface *)

     

       248
       248
       +
       let unread_only =

     

       249
       249
       +
         let doc = "List only unread messages" in

     

       250
       250
       +
         Arg.(value & flag & info ["unread"] ~doc)

     

       251
       251
       +
       

     

       252
       252
       +
       let show_labels =

     

       253
       253
       +
         let doc = "Show labels/keywords associated with messages" in

     

       254
       254
       +
         Arg.(value & flag & info ["labels"] ~doc)

     

       255
       255
       +
       

     

       256
       256
       +
       let debug_level =

     

       257
       257
       +
         let doc = "Set debug level (0-4, where 4 is most verbose)" in

     

       258
       258
       +
         Arg.(value & opt int 0 & info ["debug"] ~docv:"LEVEL" ~doc)

     

       259
       259
       +
       

     

       260
       260
       +
       let demo_refs =

     

       261
       261
       +
         let doc = "Demonstrate result references feature" in

     

       262
       262
       +
         Arg.(value & flag & info ["demo-refs"] ~doc)

     

       263
       263
       +
       

     

       264
       264
       +
       let sender_filter =

     

       265
       265
       +
         let doc = "Filter messages by sender email address (supports wildcards: * and ?)" in

     

       266
       266
       +
         Arg.(value & opt string "" & info ["from"] ~docv:"PATTERN" ~doc)

     

       267
       267
       +
       

     

       268
       268
       +
       let cmd =

     

       269
       269
       +
         let doc = "List emails from a Fastmail account using JMAP API" in

     

       270
       270
       +
         let man = [

     

       271
       271
       +
           `S Manpage.s_description;

     

       272
       272
       +
           `P "This program connects to the Fastmail JMAP API using an authentication token 

     

       273
       273
       +
               from the JMAP_API_TOKEN environment variable and lists the most recent emails 

     

       274
       274
       +
               with their subjects, sender details, and labels.";

     

       275
       275
       +
           `P "You must obtain a Fastmail API token from https://app.fastmail.com/settings/tokens 

     

       276
       276
       +
               and set it in the JMAP_API_TOKEN environment variable.";

     

       277
       277
       +
           `S Manpage.s_environment;

     

       278
       278
       +
           `P "$(b,JMAP_API_TOKEN) The Fastmail API authentication token (required)";

     

       279
       279
       +
           `S Manpage.s_examples;

     

       280
       280
       +
           `P "List all emails:";

     

       281
       281
       +
           `P "  $(mname) $(i,JMAP_API_TOKEN=your_token)";

     

       282
       282
       +
           `P "List only unread emails:";

     

       283
       283
       +
           `P "  $(mname) $(i,JMAP_API_TOKEN=your_token) --unread";

     

       284
       284
       +
           `P "List emails from a specific sender:";

     

       285
       285
       +
           `P "  $(mname) $(i,JMAP_API_TOKEN=your_token) --from=user@example.com";

     

       286
       286
       +
           `P "List unread emails with labels:";

     

       287
       287
       +
           `P "  $(mname) $(i,JMAP_API_TOKEN=your_token) --unread --labels";

     

       288
       288
       +
         ] in

     

       289
       289
       +
         let info = Cmd.info "fastmail-list" ~doc ~man in

     

       290
       290
       +
         Cmd.v info Term.(const (fun u l d r s -> 

     

       291
       291
       +
           Lwt_main.run (list_emails u l d r s)

     

       292
       292
       +
         ) $ unread_only $ show_labels $ debug_level $ demo_refs $ sender_filter)

     

       293
       293
       +
       

     

       294
       294
       +
       (** Program entry point *)

     

       295
       295
       +
       let () = exit (Cmd.eval_value cmd |> function

     

       296
       296
       +
         | Ok (`Ok exit_code) -> exit_code

     

       297
       297
       +
         | Ok (`Version | `Help) -> 0

     

       298
       298
       +
         | Error _ -> 1)

+177

bin/fastmail_send.ml

···

       1
       1
       +
       (** JMAP email sending utility for Fastmail

     

       2
       2
       +
           

     

       3
       3
       +
           This utility sends an email via JMAP to recipients specified on the command line.

     

       4
       4
       +
           The subject is provided as a command-line argument, and the message body is read

     

       5
       5
       +
           from standard input.

     

       6
       6
       +
           

     

       7
       7
       +
           Usage:

     

       8
       8
       +
           fastmail_send --to=recipient@example.com [--to=another@example.com ...] --subject="Email subject"

     

       9
       9
       +
           

     

       10
       10
       +
           Environment variables:

     

       11
       11
       +
           - JMAP_API_TOKEN: Required. The Fastmail API token for authentication.

     

       12
       12
       +
           - JMAP_FROM_EMAIL: Optional. The sender's email address. If not provided, uses the first identity.

     

       13
       13
       +
           

     

       14
       14
       +
           @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7> RFC8621 Section 7

     

       15
       15
       +
       *)

     

       16
       16
       +
       

     

       17
       17
       +
       open Lwt.Syntax

     

       18
       18
       +
       open Cmdliner

     

       19
       19
       +
       

     

       20
       20
       +
       let log_error fmt = Fmt.epr ("\u{1b}[1;31mError: \u{1b}[0m" ^^ fmt ^^ "@.")

     

       21
       21
       +
       let log_info fmt = Fmt.pr ("\u{1b}[1;34mInfo: \u{1b}[0m" ^^ fmt ^^ "@.")

     

       22
       22
       +
       let log_success fmt = Fmt.pr ("\u{1b}[1;32mSuccess: \u{1b}[0m" ^^ fmt ^^ "@.")

     

       23
       23
       +
       

     

       24
       24
       +
       (** Read the entire message body from stdin *)

     

       25
       25
       +
       let read_message_body () =

     

       26
       26
       +
         let buffer = Buffer.create 1024 in

     

       27
       27
       +
         let rec read_lines () =

     

       28
       28
       +
           try

     

       29
       29
       +
             let line = input_line stdin in

     

       30
       30
       +
             Buffer.add_string buffer line;

     

       31
       31
       +
             Buffer.add_char buffer '\n';

     

       32
       32
       +
             read_lines ()

     

       33
       33
       +
           with

     

       34
       34
       +
           | End_of_file -> Buffer.contents buffer

     

       35
       35
       +
         in

     

       36
       36
       +
         read_lines ()

     

       37
       37
       +
       

     

       38
       38
       +
       (** Main function to send an email *)

     

       39
       39
       +
       let send_email to_addresses subject from_email =

     

       40
       40
       +
         (* Check for API token in environment *)

     

       41
       41
       +
         match Sys.getenv_opt "JMAP_API_TOKEN" with

     

       42
       42
       +
         | None -> 

     

       43
       43
       +
             log_error "JMAP_API_TOKEN environment variable not set";

     

       44
       44
       +
             exit 1

     

       45
       45
       +
         | Some token ->

     

       46
       46
       +
             (* Read message body from stdin *)

     

       47
       47
       +
             log_info "Reading message body from stdin (press Ctrl+D when finished)...";

     

       48
       48
       +
             let message_body = read_message_body () in

     

       49
       49
       +
             if message_body = "" then

     

       50
       50
       +
               log_info "No message body entered, using a blank message";

     

       51
       51
       +
             

     

       52
       52
       +
             (* Initialize JMAP connection *)

     

       53
       53
       +
             let fastmail_uri = "https://api.fastmail.com/jmap/session" in

     

       54
       54
       +
             Lwt_main.run begin

     

       55
       55
       +
               let* conn_result = Jmap_mail.login_with_token ~uri:fastmail_uri ~api_token:token in

     

       56
       56
       +
               match conn_result with

     

       57
       57
       +
               | Error err ->

     

       58
       58
       +
                   let msg = Jmap.Api.string_of_error err in

     

       59
       59
       +
                   log_error "Failed to connect to Fastmail: %s" msg;

     

       60
       60
       +
                   Lwt.return 1

     

       61
       61
       +
               | Ok conn ->

     

       62
       62
       +
                   (* Get primary account ID *)

     

       63
       63
       +
                   let account_id =

     

       64
       64
       +
                     (* Get the primary account - first personal account in the list *)

     

       65
       65
       +
                     let (_, _account) = List.find (fun (_, acc) -> 

     

       66
       66
       +
                       acc.Jmap.Types.is_personal) conn.session.accounts in

     

       67
       67
       +
                     (* Use the first account id as primary *)

     

       68
       68
       +
                     (match conn.session.primary_accounts with

     

       69
       69
       +
                      | (_, id) :: _ -> id

     

       70
       70
       +
                      | [] -> 

     

       71
       71
       +
                         (* Fallback if no primary accounts defined *)

     

       72
       72
       +
                         let (id, _) = List.hd conn.session.accounts in

     

       73
       73
       +
                         id)

     

       74
       74
       +
                   in

     

       75
       75
       +
                   

     

       76
       76
       +
                   (* Determine sender email address *)

     

       77
       77
       +
                   let* from_email_result = match from_email with

     

       78
       78
       +
                     | Some email -> Lwt.return_ok email

     

       79
       79
       +
                     | None -> 

     

       80
       80
       +
                         (* Get first available identity *)

     

       81
       81
       +
                         let* identities_result = Jmap_mail.get_identities conn ~account_id in

     

       82
       82
       +
                         match identities_result with

     

       83
       83
       +
                         | Ok [] -> 

     

       84
       84
       +
                             log_error "No identities found for account";

     

       85
       85
       +
                             Lwt.return_error "No identities found"

     

       86
       86
       +
                         | Ok (identity :: _) -> Lwt.return_ok identity.email

     

       87
       87
       +
                         | Error err -> 

     

       88
       88
       +
                             let msg = Jmap.Api.string_of_error err in

     

       89
       89
       +
                             log_error "Failed to get identities: %s" msg;

     

       90
       90
       +
                             Lwt.return_error msg

     

       91
       91
       +
                   in

     

       92
       92
       +
                   

     

       93
       93
       +
                   match from_email_result with

     

       94
       94
       +
                   | Error _msg -> Lwt.return 1

     

       95
       95
       +
                   | Ok from_email ->

     

       96
       96
       +
                       (* Send the email *)

     

       97
       97
       +
                       log_info "Sending email from %s to %s" 

     

       98
       98
       +
                         from_email 

     

       99
       99
       +
                         (String.concat ", " to_addresses);

     

       100
       100
       +
                       

     

       101
       101
       +
                       let* submission_result = 

     

       102
       102
       +
                         Jmap_mail.create_and_submit_email 

     

       103
       103
       +
                           conn 

     

       104
       104
       +
                           ~account_id 

     

       105
       105
       +
                           ~from:from_email

     

       106
       106
       +
                           ~to_addresses 

     

       107
       107
       +
                           ~subject 

     

       108
       108
       +
                           ~text_body:message_body 

     

       109
       109
       +
                           ()

     

       110
       110
       +
                       in

     

       111
       111
       +
                       

     

       112
       112
       +
                       match submission_result with

     

       113
       113
       +
                       | Error err ->

     

       114
       114
       +
                           let msg = Jmap.Api.string_of_error err in

     

       115
       115
       +
                           log_error "Failed to send email: %s" msg;

     

       116
       116
       +
                           Lwt.return 1

     

       117
       117
       +
                       | Ok submission_id ->

     

       118
       118
       +
                           log_success "Email sent successfully (Submission ID: %s)" submission_id;

     

       119
       119
       +
                           (* Wait briefly then check submission status *)

     

       120
       120
       +
                           let* () = Lwt_unix.sleep 1.0 in

     

       121
       121
       +
                           let* status_result = Jmap_mail.get_submission_status 

     

       122
       122
       +
                               conn 

     

       123
       123
       +
                               ~account_id 

     

       124
       124
       +
                               ~submission_id

     

       125
       125
       +
                           in

     

       126
       126
       +
                           

     

       127
       127
       +
                           (match status_result with

     

       128
       128
       +
                           | Ok status ->

     

       129
       129
       +
                               let status_text = match status.Jmap_mail.Types.undo_status with

     

       130
       130
       +
                                 | Some `pending -> "Pending"

     

       131
       131
       +
                                 | Some `final -> "Final (delivered)"

     

       132
       132
       +
                                 | Some `canceled -> "Canceled"

     

       133
       133
       +
                                 | None -> "Unknown"

     

       134
       134
       +
                               in

     

       135
       135
       +
                               log_info "Submission status: %s" status_text;

     

       136
       136
       +
                               

     

       137
       137
       +
                               (match status.Jmap_mail.Types.delivery_status with

     

       138
       138
       +
                               | Some statuses ->

     

       139
       139
       +
                                   List.iter (fun (email, status) ->

     

       140
       140
       +
                                     let delivery = match status.Jmap_mail.Types.delivered with

     

       141
       141
       +
                                       | Some "yes" -> "Delivered"

     

       142
       142
       +
                                       | Some "no" -> "Failed"

     

       143
       143
       +
                                       | Some "queued" -> "Queued"

     

       144
       144
       +
                                       | Some s -> s

     

       145
       145
       +
                                       | None -> "Unknown"

     

       146
       146
       +
                                     in

     

       147
       147
       +
                                     log_info "Delivery to %s: %s" email delivery

     

       148
       148
       +
                                   ) statuses

     

       149
       149
       +
                               | None -> ());

     

       150
       150
       +
                               Lwt.return 0

     

       151
       151
       +
                           | Error _ ->

     

       152
       152
       +
                               (* We don't fail if status check fails, as the email might still be sent *)

     

       153
       153
       +
                               Lwt.return 0)

     

       154
       154
       +
             end

     

       155
       155
       +
       

     

       156
       156
       +
       (** Command line interface *)

     

       157
       157
       +
       let to_addresses =

     

       158
       158
       +
         let doc = "Email address of the recipient (can be specified multiple times)" in

     

       159
       159
       +
         Arg.(value & opt_all string [] & info ["to"] ~docv:"EMAIL" ~doc)

     

       160
       160
       +
       

     

       161
       161
       +
       let subject =

     

       162
       162
       +
         let doc = "Subject line for the email" in

     

       163
       163
       +
         Arg.(required & opt (some string) None & info ["subject"] ~docv:"SUBJECT" ~doc)

     

       164
       164
       +
       

     

       165
       165
       +
       let from_email =

     

       166
       166
       +
         let doc = "Sender's email address (optional, defaults to primary identity)" in

     

       167
       167
       +
         Arg.(value & opt (some string) None & info ["from"] ~docv:"EMAIL" ~doc)

     

       168
       168
       +
       

     

       169
       169
       +
       let cmd =

     

       170
       170
       +
         let doc = "Send an email via JMAP to Fastmail" in

     

       171
       171
       +
         let info = Cmd.info "fastmail_send" ~doc in

     

       172
       172
       +
         Cmd.v info Term.(const send_email $ to_addresses $ subject $ from_email)

     

       173
       173
       +
       

     

       174
       174
       +
       let () = match Cmd.eval_value cmd with

     

       175
       175
       +
         | Ok (`Ok code) -> exit code

     

       176
       176
       +
         | Ok (`Version | `Help) -> exit 0

     

       177
       177
       +
         | Error _ -> exit 1

+114

bin/flag_color_test.ml

···

       1
       1
       +
       (** Demo of message flags and mailbox attributes functionality *)

     

       2
       2
       +
       

     

       3
       3
       +
       open Jmap_mail.Types

     

       4
       4
       +
       

     

       5
       5
       +
       (** Demonstrate flag color functionality *)

     

       6
       6
       +
       let demo_flag_colors () =

     

       7
       7
       +
         Printf.printf "Flag Color Demo:\n";

     

       8
       8
       +
         Printf.printf "================\n";

     

       9
       9
       +
         

     

       10
       10
       +
         (* Show all flag colors and their bit patterns *)

     

       11
       11
       +
         let colors = [Red; Orange; Yellow; Green; Blue; Purple; Gray] in

     

       12
       12
       +
         List.iter (fun color ->

     

       13
       13
       +
           let (bit0, bit1, bit2) = bits_of_flag_color color in

     

       14
       14
       +
           Printf.printf "Color: %-7s Bits: %d%d%d\n" 

     

       15
       15
       +
             (match color with

     

       16
       16
       +
              | Red -> "Red"

     

       17
       17
       +
              | Orange -> "Orange"

     

       18
       18
       +
              | Yellow -> "Yellow"

     

       19
       19
       +
              | Green -> "Green"

     

       20
       20
       +
              | Blue -> "Blue"

     

       21
       21
       +
              | Purple -> "Purple"

     

       22
       22
       +
              | Gray -> "Gray")

     

       23
       23
       +
             (if bit0 then 1 else 0)

     

       24
       24
       +
             (if bit1 then 1 else 0)

     

       25
       25
       +
             (if bit2 then 1 else 0)

     

       26
       26
       +
         ) colors;

     

       27
       27
       +
         

     

       28
       28
       +
         Printf.printf "\n"

     

       29
       29
       +
       

     

       30
       30
       +
       (** Demonstrate message keyword functionality *)

     

       31
       31
       +
       let demo_message_keywords () =

     

       32
       32
       +
         Printf.printf "Message Keywords Demo:\n";

     

       33
       33
       +
         Printf.printf "=====================\n";

     

       34
       34
       +
         

     

       35
       35
       +
         (* Show all standard message keywords and their string representations *)

     

       36
       36
       +
         let keywords = [

     

       37
       37
       +
           Notify; Muted; Followed; Memo; HasMemo; HasAttachment; HasNoAttachment;

     

       38
       38
       +
           AutoSent; Unsubscribed; CanUnsubscribe; Imported; IsTrusted; 

     

       39
       39
       +
           MaskedEmail; New; MailFlagBit0; MailFlagBit1; MailFlagBit2

     

       40
       40
       +
         ] in

     

       41
       41
       +
         

     

       42
       42
       +
         List.iter (fun kw ->

     

       43
       43
       +
           Printf.printf "%-15s -> %s\n"

     

       44
       44
       +
             (match kw with

     

       45
       45
       +
              | Notify -> "Notify"

     

       46
       46
       +
              | Muted -> "Muted"

     

       47
       47
       +
              | Followed -> "Followed"

     

       48
       48
       +
              | Memo -> "Memo"

     

       49
       49
       +
              | HasMemo -> "HasMemo"

     

       50
       50
       +
              | HasAttachment -> "HasAttachment" 

     

       51
       51
       +
              | HasNoAttachment -> "HasNoAttachment"

     

       52
       52
       +
              | AutoSent -> "AutoSent"

     

       53
       53
       +
              | Unsubscribed -> "Unsubscribed"

     

       54
       54
       +
              | CanUnsubscribe -> "CanUnsubscribe"

     

       55
       55
       +
              | Imported -> "Imported"

     

       56
       56
       +
              | IsTrusted -> "IsTrusted"

     

       57
       57
       +
              | MaskedEmail -> "MaskedEmail"

     

       58
       58
       +
              | New -> "New"

     

       59
       59
       +
              | MailFlagBit0 -> "MailFlagBit0"

     

       60
       60
       +
              | MailFlagBit1 -> "MailFlagBit1"

     

       61
       61
       +
              | MailFlagBit2 -> "MailFlagBit2"

     

       62
       62
       +
              | OtherKeyword s -> "Other: " ^ s)

     

       63
       63
       +
             (string_of_message_keyword kw)

     

       64
       64
       +
         ) keywords;

     

       65
       65
       +
         

     

       66
       66
       +
         Printf.printf "\n"

     

       67
       67
       +
       

     

       68
       68
       +
       (** Demonstrate mailbox attribute functionality *)

     

       69
       69
       +
       let demo_mailbox_attributes () =

     

       70
       70
       +
         Printf.printf "Mailbox Attributes Demo:\n";

     

       71
       71
       +
         Printf.printf "=======================\n";

     

       72
       72
       +
         

     

       73
       73
       +
         (* Show all standard mailbox attributes and their string representations *)

     

       74
       74
       +
         let attributes = [Snoozed; Scheduled; Memos] in

     

       75
       75
       +
         

     

       76
       76
       +
         List.iter (fun attr ->

     

       77
       77
       +
           Printf.printf "%-10s -> %s\n"

     

       78
       78
       +
             (match attr with

     

       79
       79
       +
              | Snoozed -> "Snoozed"

     

       80
       80
       +
              | Scheduled -> "Scheduled"

     

       81
       81
       +
              | Memos -> "Memos"

     

       82
       82
       +
              | OtherAttribute s -> "Other: " ^ s)

     

       83
       83
       +
             (string_of_mailbox_attribute attr)

     

       84
       84
       +
         ) attributes;

     

       85
       85
       +
         

     

       86
       86
       +
         Printf.printf "\n"

     

       87
       87
       +
       

     

       88
       88
       +
       (** Demonstrate formatting functionality *)

     

       89
       89
       +
       let demo_formatting () =

     

       90
       90
       +
         Printf.printf "Keyword Formatting Demo:\n";

     

       91
       91
       +
         Printf.printf "======================\n";

     

       92
       92
       +
         

     

       93
       93
       +
         (* Create a sample email with various keywords *)

     

       94
       94
       +
         let sample_keywords = [

     

       95
       95
       +
           (Flagged, true);                           (* Standard flag *)

     

       96
       96
       +
           (Custom "$MailFlagBit0", true);            (* Flag color bit *)

     

       97
       97
       +
           (Custom "$MailFlagBit2", true);            (* Flag color bit *)

     

       98
       98
       +
           (Custom "$notify", true);                  (* Message keyword *)

     

       99
       99
       +
           (Custom "$followed", true);                (* Message keyword *)

     

       100
       100
       +
           (Custom "$hasattachment", true);           (* Message keyword *)

     

       101
       101
       +
           (Seen, false);                             (* Inactive keyword *)

     

       102
       102
       +
           (Custom "$random", true);                  (* Unknown keyword *)

     

       103
       103
       +
         ] in

     

       104
       104
       +
         

     

       105
       105
       +
         (* Test formatted output *)

     

       106
       106
       +
         let formatted = format_email_keywords sample_keywords in

     

       107
       107
       +
         Printf.printf "Formatted keywords: %s\n\n" formatted

     

       108
       108
       +
       

     

       109
       109
       +
       (** Main entry point *)

     

       110
       110
       +
       let () =

     

       111
       111
       +
         demo_flag_colors ();

     

       112
       112
       +
         demo_message_keywords ();

     

       113
       113
       +
         demo_mailbox_attributes ();

     

       114
       114
       +
         demo_formatting ()

+141

bin/jmap_test.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP test client - connects to a JMAP server and queries recent emails *)

     

       7
       7
       +
       

     

       8
       8
       +
       let () =

     

       9
       9
       +
         (* Parse command line arguments *)

     

       10
       10
       +
         let usage = "Usage: jmap-test <session-url> <api-key>" in

     

       11
       11
       +
         let args = ref [] in

     

       12
       12
       +
         Arg.parse [] (fun arg -> args := arg :: !args) usage;

     

       13
       13
       +
         let session_url, api_key =

     

       14
       14
       +
           match List.rev !args with

     

       15
       15
       +
           | [url; key] -> (url, key)

     

       16
       16
       +
           | _ ->

     

       17
       17
       +
               prerr_endline usage;

     

       18
       18
       +
               exit 1

     

       19
       19
       +
         in

     

       20
       20
       +
       

     

       21
       21
       +
         (* Run with Eio *)

     

       22
       22
       +
         Eio_main.run @@ fun env ->

     

       23
       23
       +
         Eio.Switch.run @@ fun sw ->

     

       24
       24
       +
       

     

       25
       25
       +
         (* Create HTTP client with Bearer token auth *)

     

       26
       26
       +
         let requests = Requests.create ~sw env in

     

       27
       27
       +
         let auth = Requests.Auth.bearer ~token:api_key in

     

       28
       28
       +
       

     

       29
       29
       +
         Printf.printf "Connecting to %s...\n%!" session_url;

     

       30
       30
       +
       

     

       31
       31
       +
         (* Create JMAP client from session URL *)

     

       32
       32
       +
         match Jmap_eio.Client.create_from_url ~auth requests session_url with

     

       33
       33
       +
         | Error e ->

     

       34
       34
       +
             Printf.eprintf "Failed to connect: %s\n" (Jmap_eio.Client.error_to_string e);

     

       35
       35
       +
             exit 1

     

       36
       36
       +
         | Ok client ->

     

       37
       37
       +
             let session = Jmap_eio.Client.session client in

     

       38
       38
       +
             Printf.printf "Connected! Username: %s\n%!" (Jmap_proto.Session.username session);

     

       39
       39
       +
       

     

       40
       40
       +
             (* Get primary mail account *)

     

       41
       41
       +
             let primary_account_id =

     

       42
       42
       +
               match Jmap_proto.Session.primary_account_for Jmap_proto.Capability.mail session with

     

       43
       43
       +
               | Some id -> id

     

       44
       44
       +
               | None ->

     

       45
       45
       +
                   prerr_endline "No primary mail account found";

     

       46
       46
       +
                   exit 1

     

       47
       47
       +
             in

     

       48
       48
       +
             Printf.printf "Primary mail account: %s\n%!" (Jmap_proto.Id.to_string primary_account_id);

     

       49
       49
       +
       

     

       50
       50
       +
             (* Query for recent emails - get the 10 most recent *)

     

       51
       51
       +
             let sort = [Jmap_proto.Filter.comparator ~is_ascending:false "receivedAt"] in

     

       52
       52
       +
             let query_inv = Jmap_eio.Client.Build.email_query

     

       53
       53
       +
               ~call_id:"q1"

     

       54
       54
       +
               ~account_id:primary_account_id

     

       55
       55
       +
               ~sort

     

       56
       56
       +
               ~limit:10L

     

       57
       57
       +
               ()

     

       58
       58
       +
             in

     

       59
       59
       +
       

     

       60
       60
       +
             (* Build request with mail capability *)

     

       61
       61
       +
             let req = Jmap_eio.Client.Build.make_request

     

       62
       62
       +
               ~capabilities:[Jmap_proto.Capability.core; Jmap_proto.Capability.mail]

     

       63
       63
       +
               [query_inv]

     

       64
       64
       +
             in

     

       65
       65
       +
       

     

       66
       66
       +
             Printf.printf "Querying recent emails...\n%!";

     

       67
       67
       +
       

     

       68
       68
       +
             match Jmap_eio.Client.request client req with

     

       69
       69
       +
             | Error e ->

     

       70
       70
       +
                 Printf.eprintf "Query failed: %s\n" (Jmap_eio.Client.error_to_string e);

     

       71
       71
       +
                 exit 1

     

       72
       72
       +
             | Ok response ->

     

       73
       73
       +
                 (* Parse the query response *)

     

       74
       74
       +
                 match Jmap_eio.Client.Parse.parse_email_query ~call_id:"q1" response with

     

       75
       75
       +
                 | Error e ->

     

       76
       76
       +
                     Printf.eprintf "Failed to parse query response: %s\n" (Jsont.Error.to_string e);

     

       77
       77
       +
                     exit 1

     

       78
       78
       +
                 | Ok query_result ->

     

       79
       79
       +
                     let email_ids = query_result.ids in

     

       80
       80
       +
                     Printf.printf "Found %d emails\n%!" (List.length email_ids);

     

       81
       81
       +
       

     

       82
       82
       +
                     if List.length email_ids = 0 then (

     

       83
       83
       +
                       Printf.printf "No emails found.\n%!";

     

       84
       84
       +
                     ) else (

     

       85
       85
       +
                       (* Fetch the email details *)

     

       86
       86
       +
                       let get_inv = Jmap_eio.Client.Build.email_get

     

       87
       87
       +
                         ~call_id:"g1"

     

       88
       88
       +
                         ~account_id:primary_account_id

     

       89
       89
       +
                         ~ids:email_ids

     

       90
       90
       +
                         ~properties:["id"; "subject"; "from"; "receivedAt"; "preview"]

     

       91
       91
       +
                         ()

     

       92
       92
       +
                       in

     

       93
       93
       +
       

     

       94
       94
       +
                       let req2 = Jmap_eio.Client.Build.make_request

     

       95
       95
       +
                         ~capabilities:[Jmap_proto.Capability.core; Jmap_proto.Capability.mail]

     

       96
       96
       +
                         [get_inv]

     

       97
       97
       +
                       in

     

       98
       98
       +
       

     

       99
       99
       +
                       Printf.printf "Fetching email details...\n%!";

     

       100
       100
       +
       

     

       101
       101
       +
                       match Jmap_eio.Client.request client req2 with

     

       102
       102
       +
                       | Error e ->

     

       103
       103
       +
                           Printf.eprintf "Get failed: %s\n" (Jmap_eio.Client.error_to_string e);

     

       104
       104
       +
                           exit 1

     

       105
       105
       +
                       | Ok response2 ->

     

       106
       106
       +
                           match Jmap_eio.Client.Parse.parse_email_get ~call_id:"g1" response2 with

     

       107
       107
       +
                           | Error e ->

     

       108
       108
       +
                               Printf.eprintf "Failed to parse get response: %s\n" (Jsont.Error.to_string e);

     

       109
       109
       +
                               exit 1

     

       110
       110
       +
                           | Ok get_result ->

     

       111
       111
       +
                               Printf.printf "\n=== Recent Emails ===\n\n%!";

     

       112
       112
       +
                               List.iter (fun email ->

     

       113
       113
       +
                                 let id = Jmap_proto.Id.to_string (Jmap_mail.Email.id email) in

     

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

     

       115
       115
       +
                                 let from_addrs = Option.value (Jmap_mail.Email.from email) ~default:[] in

     

       116
       116
       +
                                 let from_str = match from_addrs with

     

       117
       117
       +
                                   | [] -> "(unknown sender)"

     

       118
       118
       +
                                   | addr :: _ ->

     

       119
       119
       +
                                       let name = Option.value (Jmap_mail.Email_address.name addr) ~default:"" in

     

       120
       120
       +
                                       let email_addr = Jmap_mail.Email_address.email addr in

     

       121
       121
       +
                                       if name = "" then email_addr

     

       122
       122
       +
                                       else Printf.sprintf "%s <%s>" name email_addr

     

       123
       123
       +
                                 in

     

       124
       124
       +
                                 let received =

     

       125
       125
       +
                                   Jmap_proto.Date.Utc.to_string (Jmap_mail.Email.received_at email)

     

       126
       126
       +
                                 in

     

       127
       127
       +
                                 let preview = Jmap_mail.Email.preview email in

     

       128
       128
       +
                                 let preview_short =

     

       129
       129
       +
                                   if String.length preview > 80 then

     

       130
       130
       +
                                     String.sub preview 0 77 ^ "..."

     

       131
       131
       +
                                   else preview

     

       132
       132
       +
                                 in

     

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

     

       134
       134
       +
                                 Printf.printf "From: %s\n" from_str;

     

       135
       135
       +
                                 Printf.printf "Date: %s\n" received;

     

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

     

       137
       137
       +
                                 Printf.printf "Preview: %s\n" preview_short;

     

       138
       138
       +
                                 Printf.printf "\n%!";

     

       139
       139
       +
                               ) get_result.list;

     

       140
       140
       +
                               Printf.printf "=== End of emails ===\n%!"

     

       141
       141
       +
                     )

+164

bin/tutorial_examples.ml

···

       1
       1
       +
       (* Examples from the tutorial *)

     

       2
       2
       +
       

     

       3
       3
       +
       open Lwt.Syntax

     

       4
       4
       +
       open Jmap

     

       5
       5
       +
       open Jmap_mail

     

       6
       6
       +
       

     

       7
       7
       +
       (* Example: Authentication *)

     

       8
       8
       +
       let auth_example () =

     

       9
       9
       +
         (* Using a Fastmail API token *)

     

       10
       10
       +
         let token = Sys.getenv_opt "JMAP_API_TOKEN" in

     

       11
       11
       +
         match token with

     

       12
       12
       +
         | None ->

     

       13
       13
       +
             Printf.eprintf "Error: JMAP_API_TOKEN environment variable not set\n";

     

       14
       14
       +
             Lwt.return_none

     

       15
       15
       +
         | Some token ->

     

       16
       16
       +
             let+ result = Jmap_mail.login_with_token 

     

       17
       17
       +
               ~uri:"https://api.fastmail.com/jmap/session" 

     

       18
       18
       +
               ~api_token:token

     

       19
       19
       +
             in

     

       20
       20
       +
         

     

       21
       21
       +
             (* Handle the result *)

     

       22
       22
       +
             match result with

     

       23
       23
       +
             | Ok conn -> 

     

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

     

       25
       25
       +
                 let account_id = 

     

       26
       26
       +
                   let mail_capability = Jmap_mail.Capability.to_string Jmap_mail.Capability.Mail in

     

       27
       27
       +
                   match List.assoc_opt mail_capability conn.session.primary_accounts with

     

       28
       28
       +
                   | Some id -> id

     

       29
       29
       +
                   | None -> 

     

       30
       30
       +
                       match conn.session.accounts with

     

       31
       31
       +
                       | (id, _) :: _ -> id

     

       32
       32
       +
                       | [] -> failwith "No accounts found"

     

       33
       33
       +
                 in

     

       34
       34
       +
                 Printf.printf "Authenticated successfully with account ID: %s\n" account_id;

     

       35
       35
       +
                 Some (conn, account_id)

     

       36
       36
       +
             | Error e -> 

     

       37
       37
       +
                 Printf.eprintf "Authentication error: %s\n" 

     

       38
       38
       +
                   (match e with

     

       39
       39
       +
                   | Api.Connection_error msg -> "Connection error: " ^ msg

     

       40
       40
       +
                   | Api.HTTP_error (code, body) -> Printf.sprintf "HTTP error %d: %s" code body

     

       41
       41
       +
                   | Api.Parse_error msg -> "Parse error: " ^ msg

     

       42
       42
       +
                   | Api.Authentication_error -> "Authentication error");

     

       43
       43
       +
                 None

     

       44
       44
       +
       

     

       45
       45
       +
       (* Example: Working with Mailboxes *)

     

       46
       46
       +
       let mailbox_example (conn, account_id) =

     

       47
       47
       +
         (* Get all mailboxes *)

     

       48
       48
       +
         let+ mailboxes_result = Jmap_mail.get_mailboxes conn ~account_id in

     

       49
       49
       +
         

     

       50
       50
       +
         match mailboxes_result with

     

       51
       51
       +
         | Ok mailboxes -> 

     

       52
       52
       +
             Printf.printf "Found %d mailboxes\n" (List.length mailboxes);

     

       53
       53
       +
             

     

       54
       54
       +
             (* Find inbox - for simplicity, just use the first mailbox *)

     

       55
       55
       +
             let inbox = match mailboxes with

     

       56
       56
       +
               | first :: _ -> Some first

     

       57
       57
       +
               | [] -> None

     

       58
       58
       +
             in

     

       59
       59
       +
             

     

       60
       60
       +
             (match inbox with

     

       61
       61
       +
             | Some m -> 

     

       62
       62
       +
                 Printf.printf "Inbox ID: %s, Name: %s\n" 

     

       63
       63
       +
                   m.Types.id 

     

       64
       64
       +
                   m.Types.name;

     

       65
       65
       +
                 Some (conn, account_id, m.Types.id)

     

       66
       66
       +
             | None -> 

     

       67
       67
       +
                 Printf.printf "No inbox found\n";

     

       68
       68
       +
                 None)

     

       69
       69
       +
         | Error e -> 

     

       70
       70
       +
             Printf.eprintf "Error getting mailboxes: %s\n" 

     

       71
       71
       +
               (match e with

     

       72
       72
       +
               | Api.Connection_error msg -> "Connection error: " ^ msg

     

       73
       73
       +
               | Api.HTTP_error (code, body) -> Printf.sprintf "HTTP error %d: %s" code body

     

       74
       74
       +
               | Api.Parse_error msg -> "Parse error: " ^ msg

     

       75
       75
       +
               | Api.Authentication_error -> "Authentication error");

     

       76
       76
       +
             None

     

       77
       77
       +
       

     

       78
       78
       +
       (* Example: Working with Emails *)

     

       79
       79
       +
       let email_example (conn, account_id, mailbox_id) =

     

       80
       80
       +
         (* Get emails from mailbox *)

     

       81
       81
       +
         let+ emails_result = Jmap_mail.get_messages_in_mailbox

     

       82
       82
       +
           conn

     

       83
       83
       +
           ~account_id

     

       84
       84
       +
           ~mailbox_id

     

       85
       85
       +
           ~limit:5

     

       86
       86
       +
           ()

     

       87
       87
       +
         in

     

       88
       88
       +
         

     

       89
       89
       +
         match emails_result with

     

       90
       90
       +
         | Ok emails -> begin

     

       91
       91
       +
             Printf.printf "Found %d emails\n" (List.length emails);

     

       92
       92
       +
             

     

       93
       93
       +
             (* Display emails *)

     

       94
       94
       +
             List.iter (fun (email:Jmap_mail.Types.email) ->

     

       95
       95
       +
               (* Using explicit module path for Types to avoid ambiguity *)

     

       96
       96
       +
               let module Mail = Jmap_mail.Types in

     

       97
       97
       +
               

     

       98
       98
       +
               (* Get sender info *)

     

       99
       99
       +
               let from = match email.Mail.from with

     

       100
       100
       +
                 | None -> "Unknown"

     

       101
       101
       +
                 | Some addrs -> 

     

       102
       102
       +
                     match addrs with

     

       103
       103
       +
                     | [] -> "Unknown"

     

       104
       104
       +
                     | addr :: _ -> 

     

       105
       105
       +
                         match addr.Mail.name with

     

       106
       106
       +
                         | None -> addr.Mail.email

     

       107
       107
       +
                         | Some name -> 

     

       108
       108
       +
                             Printf.sprintf "%s <%s>" name addr.Mail.email

     

       109
       109
       +
               in

     

       110
       110
       +
               

     

       111
       111
       +
               (* Check for unread status *)

     

       112
       112
       +
               let is_unread =

     

       113
       113
       +
                 List.exists (fun (kw, active) -> 

     

       114
       114
       +
                   match kw with

     

       115
       115
       +
                   | Mail.Unread -> active

     

       116
       116
       +
                   | Mail.Custom s when s = "$unread" -> active

     

       117
       117
       +
                   | _ -> false

     

       118
       118
       +
                 ) email.Mail.keywords

     

       119
       119
       +
               in

     

       120
       120
       +
               

     

       121
       121
       +
               (* Display email info *)

     

       122
       122
       +
               Printf.printf "[%s] %s - %s\n"

     

       123
       123
       +
                 (if is_unread then "UNREAD" else "READ")

     

       124
       124
       +
                 from

     

       125
       125
       +
                 (Option.value ~default:"(No Subject)" email.Mail.subject)

     

       126
       126
       +
             ) emails;

     

       127
       127
       +
             

     

       128
       128
       +
             match emails with

     

       129
       129
       +
             | [] -> None

     

       130
       130
       +
             | hd::_ -> Some (conn, account_id, hd.Jmap_mail.Types.id)

     

       131
       131
       +
         end

     

       132
       132
       +
         | Error e ->

     

       133
       133
       +
             Printf.eprintf "Error getting emails: %s\n" 

     

       134
       134
       +
               (match e with

     

       135
       135
       +
               | Api.Connection_error msg -> "Connection error: " ^ msg

     

       136
       136
       +
               | Api.HTTP_error (code, body) -> Printf.sprintf "HTTP error %d: %s" code body

     

       137
       137
       +
               | Api.Parse_error msg -> "Parse error: " ^ msg

     

       138
       138
       +
               | Api.Authentication_error -> "Authentication error");

     

       139
       139
       +
             None

     

       140
       140
       +
       

     

       141
       141
       +
       (* Run examples with Lwt *)

     

       142
       142
       +
       let () =

     

       143
       143
       +
         (* Set up logging *)

     

       144
       144
       +
         Jmap.init_logging ~level:2 ~enable_logs:true ~redact_sensitive:true ();

     

       145
       145
       +
         

     

       146
       146
       +
         (* Run the examples in sequence *)

     

       147
       147
       +
         let result = Lwt_main.run (

     

       148
       148
       +
           let* auth_result = auth_example () in

     

       149
       149
       +
           match auth_result with

     

       150
       150
       +
           | None -> Lwt.return 1

     

       151
       151
       +
           | Some conn_account ->

     

       152
       152
       +
               let* mailbox_result = mailbox_example conn_account in

     

       153
       153
       +
               match mailbox_result with

     

       154
       154
       +
               | None -> Lwt.return 1

     

       155
       155
       +
               | Some conn_account_mailbox ->

     

       156
       156
       +
                   let* email_result = email_example conn_account_mailbox in

     

       157
       157
       +
                   match email_result with

     

       158
       158
       +
                   | None -> Lwt.return 1

     

       159
       159
       +
                   | Some _ -> 

     

       160
       160
       +
                       Printf.printf "All examples completed successfully\n";

     

       161
       161
       +
                       Lwt.return 0

     

       162
       162
       +
         ) in

     

       163
       163
       +
         

     

       164
       164
       +
         exit result

+29 -10

dune-project

···

       1
       1
       -
       (lang dune 3.17)

     

       1
       1
       +
       (lang dune 3.0)

     

       2
       2
       +
       

     

       2
       3
        
       (name jmap)

     

       3
       4
        
       

     

       4
       4
       -
       (source (github avsm/jmap))

     

       5
       5
       +
       (generate_opam_files true)

     

       6
       6
       +
       

     

       7
       7
       +
       (source

     

       8
       8
       +
        (github avsm/ocaml-jmap))

     

       9
       9
       +
       

     

       10
       10
       +
       (authors "Anil Madhavapeddy <anil@recoil.org>")

     

       11
       11
       +
       

     

       12
       12
       +
       (maintainers "Anil Madhavapeddy <anil@recoil.org>")

     

       13
       13
       +
       

     

       5
       14
        
       (license ISC)

     

       6
       6
       -
       (authors "Anil Madhavapeddy")

     

       7
       7
       -
       (maintainers "anil@recoil.org")

     

       8
       15
        
       

     

       9
       9
       -
       (generate_opam_files true)

     

       16
       16
       +
       (documentation https://avsm.github.io/ocaml-jmap)

     

       10
       17
        
       

     

       11
       18
        
       (package

     

       12
       19
        
        (name jmap)

     

       13
       13
       -
        (synopsis "JMAP protocol")

     

       14
       14
       -
        (description "This is all still a work in progress")

     

       20
       20
       +
        (synopsis "JMAP protocol implementation for OCaml")

     

       21
       21
       +
        (description

     

       22
       22
       +
         "A complete implementation of the JSON Meta Application Protocol (JMAP) as specified in RFC 8620 (core) and RFC 8621 (mail).")

     

       23
       23
       +
        (depends

     

       24
       24
       +
         (ocaml (>= 4.14.0))

     

       25
       25
       +
         (jsont (>= 0.2.0))

     

       26
       26
       +
         (ptime (>= 1.0.0))))

     

       27
       27
       +
       

     

       28
       28
       +
       (package

     

       29
       29
       +
        (name jmap-eio)

     

       30
       30
       +
        (synopsis "JMAP client for Eio")

     

       31
       31
       +
        (description "High-level JMAP client using Eio for async I/O and the Requests HTTP library.")

     

       15
       32
        
        (depends

     

       16
       16
       -
         (ocaml (>= "5.2.0"))

     

       17
       17
       -
         ezjsonm

     

       18
       18
       -
         ptime))

     

       33
       33
       +
         (ocaml (>= 4.14.0))

     

       34
       34
       +
         (jmap (= :version))

     

       35
       35
       +
         (jsont (>= 0.2.0))

     

       36
       36
       +
         eio

     

       37
       37
       +
         requests))

+514

eio/client.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type error =

     

       7
       7
       +
         | Http_error of int * string

     

       8
       8
       +
         | Jmap_error of Jmap_proto.Error.Request_error.t

     

       9
       9
       +
         | Json_error of Jsont.Error.t

     

       10
       10
       +
         | Session_error of string

     

       11
       11
       +
         | Connection_error of string

     

       12
       12
       +
       

     

       13
       13
       +
       let pp_error fmt = function

     

       14
       14
       +
         | Http_error (code, msg) ->

     

       15
       15
       +
             Format.fprintf fmt "HTTP error %d: %s" code msg

     

       16
       16
       +
         | Jmap_error err ->

     

       17
       17
       +
             Format.fprintf fmt "JMAP error: %s"

     

       18
       18
       +
               (Jmap_proto.Error.Request_error.urn_to_string err.type_)

     

       19
       19
       +
         | Json_error err ->

     

       20
       20
       +
             Format.fprintf fmt "JSON error: %s" (Jsont.Error.to_string err)

     

       21
       21
       +
         | Session_error msg ->

     

       22
       22
       +
             Format.fprintf fmt "Session error: %s" msg

     

       23
       23
       +
         | Connection_error msg ->

     

       24
       24
       +
             Format.fprintf fmt "Connection error: %s" msg

     

       25
       25
       +
       

     

       26
       26
       +
       let error_to_string err =

     

       27
       27
       +
         Format.asprintf "%a" pp_error err

     

       28
       28
       +
       

     

       29
       29
       +
       exception Jmap_client_error of error

     

       30
       30
       +
       

     

       31
       31
       +
       type t = {

     

       32
       32
       +
         mutable session : Jmap_proto.Session.t;

     

       33
       33
       +
         requests : Requests.t;

     

       34
       34
       +
         auth : Requests.Auth.t option;

     

       35
       35
       +
         session_url : string;

     

       36
       36
       +
       }

     

       37
       37
       +
       

     

       38
       38
       +
       let session t = t.session

     

       39
       39
       +
       let api_url t = Jmap_proto.Session.api_url t.session

     

       40
       40
       +
       let upload_url t = Jmap_proto.Session.upload_url t.session

     

       41
       41
       +
       let download_url t = Jmap_proto.Session.download_url t.session

     

       42
       42
       +
       

     

       43
       43
       +
       let create ?auth ~session requests =

     

       44
       44
       +
         let session_url = Jmap_proto.Session.api_url session in

     

       45
       45
       +
         { session; requests; auth; session_url }

     

       46
       46
       +
       

     

       47
       47
       +
       let fetch_session ?auth requests url =

     

       48
       48
       +
         try

     

       49
       49
       +
           let response =

     

       50
       50
       +
             match auth with

     

       51
       51
       +
             | Some a -> Requests.get requests ~auth:a url

     

       52
       52
       +
             | None -> Requests.get requests url

     

       53
       53
       +
           in

     

       54
       54
       +
           if not (Requests.Response.ok response) then

     

       55
       55
       +
             Error (Http_error (Requests.Response.status_code response,

     

       56
       56
       +
                                "Failed to fetch session"))

     

       57
       57
       +
           else

     

       58
       58
       +
             let body = Requests.Response.text response in

     

       59
       59
       +
             match Codec.decode_session body with

     

       60
       60
       +
             | Ok session -> Ok session

     

       61
       61
       +
             | Error e -> Error (Json_error e)

     

       62
       62
       +
         with

     

       63
       63
       +
         | Eio.Io (Requests.Error.E err, _) ->

     

       64
       64
       +
           Error (Connection_error (Requests.Error.to_string err))

     

       65
       65
       +
         | exn -> Error (Session_error (Printexc.to_string exn))

     

       66
       66
       +
       

     

       67
       67
       +
       let create_from_url ?auth requests url =

     

       68
       68
       +
         match fetch_session ?auth requests url with

     

       69
       69
       +
         | Ok session ->

     

       70
       70
       +
             Ok { session; requests; auth; session_url = url }

     

       71
       71
       +
         | Error e -> Error e

     

       72
       72
       +
       

     

       73
       73
       +
       let create_from_url_exn ?auth requests url =

     

       74
       74
       +
         match create_from_url ?auth requests url with

     

       75
       75
       +
         | Ok t -> t

     

       76
       76
       +
         | Error e -> raise (Jmap_client_error e)

     

       77
       77
       +
       

     

       78
       78
       +
       let refresh_session t =

     

       79
       79
       +
         match fetch_session ?auth:t.auth t.requests t.session_url with

     

       80
       80
       +
         | Ok session ->

     

       81
       81
       +
             t.session <- session;

     

       82
       82
       +
             Ok ()

     

       83
       83
       +
         | Error e -> Error e

     

       84
       84
       +
       

     

       85
       85
       +
       let refresh_session_exn t =

     

       86
       86
       +
         match refresh_session t with

     

       87
       87
       +
         | Ok () -> ()

     

       88
       88
       +
         | Error e -> raise (Jmap_client_error e)

     

       89
       89
       +
       

     

       90
       90
       +
       let request t req =

     

       91
       91
       +
         try

     

       92
       92
       +
           match Codec.encode_request req with

     

       93
       93
       +
           | Error e -> Error (Json_error e)

     

       94
       94
       +
           | Ok body_str ->

     

       95
       95
       +
               let body = Requests.Body.of_string Requests.Mime.json body_str in

     

       96
       96
       +
               let url = api_url t in

     

       97
       97
       +
               let response =

     

       98
       98
       +
                 match t.auth with

     

       99
       99
       +
                 | Some auth -> Requests.post t.requests ~auth ~body url

     

       100
       100
       +
                 | None -> Requests.post t.requests ~body url

     

       101
       101
       +
               in

     

       102
       102
       +
               if not (Requests.Response.ok response) then

     

       103
       103
       +
                 Error (Http_error (Requests.Response.status_code response,

     

       104
       104
       +
                                    Requests.Response.text response))

     

       105
       105
       +
               else

     

       106
       106
       +
                 let response_body = Requests.Response.text response in

     

       107
       107
       +
                 match Codec.decode_response response_body with

     

       108
       108
       +
                 | Ok resp -> Ok resp

     

       109
       109
       +
                 | Error e -> Error (Json_error e)

     

       110
       110
       +
         with

     

       111
       111
       +
         | Eio.Io (Requests.Error.E err, _) ->

     

       112
       112
       +
           Error (Connection_error (Requests.Error.to_string err))

     

       113
       113
       +
         | exn -> Error (Connection_error (Printexc.to_string exn))

     

       114
       114
       +
       

     

       115
       115
       +
       let request_exn t req =

     

       116
       116
       +
         match request t req with

     

       117
       117
       +
         | Ok resp -> resp

     

       118
       118
       +
         | Error e -> raise (Jmap_client_error e)

     

       119
       119
       +
       

     

       120
       120
       +
       let expand_upload_url t ~account_id =

     

       121
       121
       +
         let template = upload_url t in

     

       122
       122
       +
         let account_id_str = Jmap_proto.Id.to_string account_id in

     

       123
       123
       +
         (* Simple template expansion for {accountId} *)

     

       124
       124
       +
         let re = Str.regexp "{accountId}" in

     

       125
       125
       +
         Str.global_replace re account_id_str template

     

       126
       126
       +
       

     

       127
       127
       +
       let upload t ~account_id ~content_type ~data =

     

       128
       128
       +
         try

     

       129
       129
       +
           let url = expand_upload_url t ~account_id in

     

       130
       130
       +
           let mime = Requests.Mime.of_string content_type in

     

       131
       131
       +
           let body = Requests.Body.of_string mime data in

     

       132
       132
       +
           let response =

     

       133
       133
       +
             match t.auth with

     

       134
       134
       +
             | Some auth -> Requests.post t.requests ~auth ~body url

     

       135
       135
       +
             | None -> Requests.post t.requests ~body url

     

       136
       136
       +
           in

     

       137
       137
       +
           if not (Requests.Response.ok response) then

     

       138
       138
       +
             Error (Http_error (Requests.Response.status_code response,

     

       139
       139
       +
                                Requests.Response.text response))

     

       140
       140
       +
           else

     

       141
       141
       +
             let response_body = Requests.Response.text response in

     

       142
       142
       +
             match Codec.decode_upload_response response_body with

     

       143
       143
       +
             | Ok upload_resp -> Ok upload_resp

     

       144
       144
       +
             | Error e -> Error (Json_error e)

     

       145
       145
       +
         with

     

       146
       146
       +
         | Eio.Io (Requests.Error.E err, _) ->

     

       147
       147
       +
           Error (Connection_error (Requests.Error.to_string err))

     

       148
       148
       +
         | exn -> Error (Connection_error (Printexc.to_string exn))

     

       149
       149
       +
       

     

       150
       150
       +
       let upload_exn t ~account_id ~content_type ~data =

     

       151
       151
       +
         match upload t ~account_id ~content_type ~data with

     

       152
       152
       +
         | Ok resp -> resp

     

       153
       153
       +
         | Error e -> raise (Jmap_client_error e)

     

       154
       154
       +
       

     

       155
       155
       +
       let expand_download_url t ~account_id ~blob_id ?name ?accept () =

     

       156
       156
       +
         let template = download_url t in

     

       157
       157
       +
         let account_id_str = Jmap_proto.Id.to_string account_id in

     

       158
       158
       +
         let blob_id_str = Jmap_proto.Id.to_string blob_id in

     

       159
       159
       +
         let name_str = Option.value name ~default:"download" in

     

       160
       160
       +
         let type_str = Option.value accept ~default:"application/octet-stream" in

     

       161
       161
       +
         (* Simple template expansion *)

     

       162
       162
       +
         template

     

       163
       163
       +
         |> Str.global_replace (Str.regexp "{accountId}") account_id_str

     

       164
       164
       +
         |> Str.global_replace (Str.regexp "{blobId}") blob_id_str

     

       165
       165
       +
         |> Str.global_replace (Str.regexp "{name}") (Uri.pct_encode name_str)

     

       166
       166
       +
         |> Str.global_replace (Str.regexp "{type}") (Uri.pct_encode type_str)

     

       167
       167
       +
       

     

       168
       168
       +
       let download t ~account_id ~blob_id ?name ?accept () =

     

       169
       169
       +
         try

     

       170
       170
       +
           let url = expand_download_url t ~account_id ~blob_id ?name ?accept () in

     

       171
       171
       +
           let response =

     

       172
       172
       +
             match t.auth with

     

       173
       173
       +
             | Some auth -> Requests.get t.requests ~auth url

     

       174
       174
       +
             | None -> Requests.get t.requests url

     

       175
       175
       +
           in

     

       176
       176
       +
           if not (Requests.Response.ok response) then

     

       177
       177
       +
             Error (Http_error (Requests.Response.status_code response,

     

       178
       178
       +
                                Requests.Response.text response))

     

       179
       179
       +
           else

     

       180
       180
       +
             Ok (Requests.Response.text response)

     

       181
       181
       +
         with

     

       182
       182
       +
         | Eio.Io (Requests.Error.E err, _) ->

     

       183
       183
       +
           Error (Connection_error (Requests.Error.to_string err))

     

       184
       184
       +
         | exn -> Error (Connection_error (Printexc.to_string exn))

     

       185
       185
       +
       

     

       186
       186
       +
       let download_exn t ~account_id ~blob_id ?name ?accept () =

     

       187
       187
       +
         match download t ~account_id ~blob_id ?name ?accept () with

     

       188
       188
       +
         | Ok data -> data

     

       189
       189
       +
         | Error e -> raise (Jmap_client_error e)

     

       190
       190
       +
       

     

       191
       191
       +
       (* Convenience builders *)

     

       192
       192
       +
       module Build = struct

     

       193
       193
       +
         open Jmap_proto

     

       194
       194
       +
       

     

       195
       195
       +
         let json_of_id id =

     

       196
       196
       +
           Jsont.String (Id.to_string id, Jsont.Meta.none)

     

       197
       197
       +
       

     

       198
       198
       +
         let json_of_id_list ids =

     

       199
       199
       +
           let items = List.map json_of_id ids in

     

       200
       200
       +
           Jsont.Array (items, Jsont.Meta.none)

     

       201
       201
       +
       

     

       202
       202
       +
         let json_of_string_list strs =

     

       203
       203
       +
           let items = List.map (fun s -> Jsont.String (s, Jsont.Meta.none)) strs in

     

       204
       204
       +
           Jsont.Array (items, Jsont.Meta.none)

     

       205
       205
       +
       

     

       206
       206
       +
         let json_of_int64 n =

     

       207
       207
       +
           Jsont.Number (Int64.to_float n, Jsont.Meta.none)

     

       208
       208
       +
       

     

       209
       209
       +
         let json_of_bool b =

     

       210
       210
       +
           Jsont.Bool (b, Jsont.Meta.none)

     

       211
       211
       +
       

     

       212
       212
       +
         let json_name s = (s, Jsont.Meta.none)

     

       213
       213
       +
       

     

       214
       214
       +
         let json_obj fields =

     

       215
       215
       +
           let fields' = List.map (fun (k, v) -> (json_name k, v)) fields in

     

       216
       216
       +
           Jsont.Object (fields', Jsont.Meta.none)

     

       217
       217
       +
       

     

       218
       218
       +
         let make_invocation ~name ~call_id args =

     

       219
       219
       +
           Invocation.create ~name ~arguments:(json_obj args) ~method_call_id:call_id

     

       220
       220
       +
       

     

       221
       221
       +
         let echo ~call_id data =

     

       222
       222
       +
           make_invocation ~name:"Core/echo" ~call_id

     

       223
       223
       +
             [ ("data", data) ]

     

       224
       224
       +
       

     

       225
       225
       +
         let mailbox_get ~call_id ~account_id ?ids ?properties () =

     

       226
       226
       +
           let args = [

     

       227
       227
       +
             ("accountId", json_of_id account_id);

     

       228
       228
       +
           ] in

     

       229
       229
       +
           let args = match ids with

     

       230
       230
       +
             | None -> args

     

       231
       231
       +
             | Some ids -> ("ids", json_of_id_list ids) :: args

     

       232
       232
       +
           in

     

       233
       233
       +
           let args = match properties with

     

       234
       234
       +
             | None -> args

     

       235
       235
       +
             | Some props -> ("properties", json_of_string_list props) :: args

     

       236
       236
       +
           in

     

       237
       237
       +
           make_invocation ~name:"Mailbox/get" ~call_id args

     

       238
       238
       +
       

     

       239
       239
       +
         let mailbox_changes ~call_id ~account_id ~since_state ?max_changes () =

     

       240
       240
       +
           let args = [

     

       241
       241
       +
             ("accountId", json_of_id account_id);

     

       242
       242
       +
             ("sinceState", Jsont.String (since_state, Jsont.Meta.none));

     

       243
       243
       +
           ] in

     

       244
       244
       +
           let args = match max_changes with

     

       245
       245
       +
             | None -> args

     

       246
       246
       +
             | Some n -> ("maxChanges", json_of_int64 n) :: args

     

       247
       247
       +
           in

     

       248
       248
       +
           make_invocation ~name:"Mailbox/changes" ~call_id args

     

       249
       249
       +
       

     

       250
       250
       +
         let encode_to_json jsont value =

     

       251
       251
       +
           match Jsont.Json.encode' jsont value with

     

       252
       252
       +
           | Ok j -> j

     

       253
       253
       +
           | Error _ -> json_obj []

     

       254
       254
       +
       

     

       255
       255
       +
         let encode_list_to_json jsont values =

     

       256
       256
       +
           match Jsont.Json.encode' (Jsont.list jsont) values with

     

       257
       257
       +
           | Ok j -> j

     

       258
       258
       +
           | Error _ -> Jsont.Array ([], Jsont.Meta.none)

     

       259
       259
       +
       

     

       260
       260
       +
         let mailbox_query ~call_id ~account_id ?filter ?sort ?position ?limit () =

     

       261
       261
       +
           let args = [

     

       262
       262
       +
             ("accountId", json_of_id account_id);

     

       263
       263
       +
           ] in

     

       264
       264
       +
           let args = match filter with

     

       265
       265
       +
             | None -> args

     

       266
       266
       +
             | Some f ->

     

       267
       267
       +
                 ("filter", encode_to_json Jmap_mail.Mail_filter.mailbox_filter_jsont f) :: args

     

       268
       268
       +
           in

     

       269
       269
       +
           let args = match sort with

     

       270
       270
       +
             | None -> args

     

       271
       271
       +
             | Some comparators ->

     

       272
       272
       +
                 ("sort", encode_list_to_json Filter.comparator_jsont comparators) :: args

     

       273
       273
       +
           in

     

       274
       274
       +
           let args = match position with

     

       275
       275
       +
             | None -> args

     

       276
       276
       +
             | Some n -> ("position", json_of_int64 n) :: args

     

       277
       277
       +
           in

     

       278
       278
       +
           let args = match limit with

     

       279
       279
       +
             | None -> args

     

       280
       280
       +
             | Some n -> ("limit", json_of_int64 n) :: args

     

       281
       281
       +
           in

     

       282
       282
       +
           make_invocation ~name:"Mailbox/query" ~call_id args

     

       283
       283
       +
       

     

       284
       284
       +
         let email_get ~call_id ~account_id ?ids ?properties ?body_properties

     

       285
       285
       +
             ?fetch_text_body_values ?fetch_html_body_values ?fetch_all_body_values

     

       286
       286
       +
             ?max_body_value_bytes () =

     

       287
       287
       +
           let args = [

     

       288
       288
       +
             ("accountId", json_of_id account_id);

     

       289
       289
       +
           ] in

     

       290
       290
       +
           let args = match ids with

     

       291
       291
       +
             | None -> args

     

       292
       292
       +
             | Some ids -> ("ids", json_of_id_list ids) :: args

     

       293
       293
       +
           in

     

       294
       294
       +
           let args = match properties with

     

       295
       295
       +
             | None -> args

     

       296
       296
       +
             | Some props -> ("properties", json_of_string_list props) :: args

     

       297
       297
       +
           in

     

       298
       298
       +
           let args = match body_properties with

     

       299
       299
       +
             | None -> args

     

       300
       300
       +
             | Some props -> ("bodyProperties", json_of_string_list props) :: args

     

       301
       301
       +
           in

     

       302
       302
       +
           let args = match fetch_text_body_values with

     

       303
       303
       +
             | None -> args

     

       304
       304
       +
             | Some b -> ("fetchTextBodyValues", json_of_bool b) :: args

     

       305
       305
       +
           in

     

       306
       306
       +
           let args = match fetch_html_body_values with

     

       307
       307
       +
             | None -> args

     

       308
       308
       +
             | Some b -> ("fetchHTMLBodyValues", json_of_bool b) :: args

     

       309
       309
       +
           in

     

       310
       310
       +
           let args = match fetch_all_body_values with

     

       311
       311
       +
             | None -> args

     

       312
       312
       +
             | Some b -> ("fetchAllBodyValues", json_of_bool b) :: args

     

       313
       313
       +
           in

     

       314
       314
       +
           let args = match max_body_value_bytes with

     

       315
       315
       +
             | None -> args

     

       316
       316
       +
             | Some n -> ("maxBodyValueBytes", json_of_int64 n) :: args

     

       317
       317
       +
           in

     

       318
       318
       +
           make_invocation ~name:"Email/get" ~call_id args

     

       319
       319
       +
       

     

       320
       320
       +
         let email_changes ~call_id ~account_id ~since_state ?max_changes () =

     

       321
       321
       +
           let args = [

     

       322
       322
       +
             ("accountId", json_of_id account_id);

     

       323
       323
       +
             ("sinceState", Jsont.String (since_state, Jsont.Meta.none));

     

       324
       324
       +
           ] in

     

       325
       325
       +
           let args = match max_changes with

     

       326
       326
       +
             | None -> args

     

       327
       327
       +
             | Some n -> ("maxChanges", json_of_int64 n) :: args

     

       328
       328
       +
           in

     

       329
       329
       +
           make_invocation ~name:"Email/changes" ~call_id args

     

       330
       330
       +
       

     

       331
       331
       +
         let email_query ~call_id ~account_id ?filter ?sort ?position ?limit

     

       332
       332
       +
             ?collapse_threads () =

     

       333
       333
       +
           let args = [

     

       334
       334
       +
             ("accountId", json_of_id account_id);

     

       335
       335
       +
           ] in

     

       336
       336
       +
           let args = match filter with

     

       337
       337
       +
             | None -> args

     

       338
       338
       +
             | Some f ->

     

       339
       339
       +
                 ("filter", encode_to_json Jmap_mail.Mail_filter.email_filter_jsont f) :: args

     

       340
       340
       +
           in

     

       341
       341
       +
           let args = match sort with

     

       342
       342
       +
             | None -> args

     

       343
       343
       +
             | Some comparators ->

     

       344
       344
       +
                 ("sort", encode_list_to_json Filter.comparator_jsont comparators) :: args

     

       345
       345
       +
           in

     

       346
       346
       +
           let args = match position with

     

       347
       347
       +
             | None -> args

     

       348
       348
       +
             | Some n -> ("position", json_of_int64 n) :: args

     

       349
       349
       +
           in

     

       350
       350
       +
           let args = match limit with

     

       351
       351
       +
             | None -> args

     

       352
       352
       +
             | Some n -> ("limit", json_of_int64 n) :: args

     

       353
       353
       +
           in

     

       354
       354
       +
           let args = match collapse_threads with

     

       355
       355
       +
             | None -> args

     

       356
       356
       +
             | Some b -> ("collapseThreads", json_of_bool b) :: args

     

       357
       357
       +
           in

     

       358
       358
       +
           make_invocation ~name:"Email/query" ~call_id args

     

       359
       359
       +
       

     

       360
       360
       +
         let thread_get ~call_id ~account_id ?ids () =

     

       361
       361
       +
           let args = [

     

       362
       362
       +
             ("accountId", json_of_id account_id);

     

       363
       363
       +
           ] in

     

       364
       364
       +
           let args = match ids with

     

       365
       365
       +
             | None -> args

     

       366
       366
       +
             | Some ids -> ("ids", json_of_id_list ids) :: args

     

       367
       367
       +
           in

     

       368
       368
       +
           make_invocation ~name:"Thread/get" ~call_id args

     

       369
       369
       +
       

     

       370
       370
       +
         let thread_changes ~call_id ~account_id ~since_state ?max_changes () =

     

       371
       371
       +
           let args = [

     

       372
       372
       +
             ("accountId", json_of_id account_id);

     

       373
       373
       +
             ("sinceState", Jsont.String (since_state, Jsont.Meta.none));

     

       374
       374
       +
           ] in

     

       375
       375
       +
           let args = match max_changes with

     

       376
       376
       +
             | None -> args

     

       377
       377
       +
             | Some n -> ("maxChanges", json_of_int64 n) :: args

     

       378
       378
       +
           in

     

       379
       379
       +
           make_invocation ~name:"Thread/changes" ~call_id args

     

       380
       380
       +
       

     

       381
       381
       +
         let identity_get ~call_id ~account_id ?ids ?properties () =

     

       382
       382
       +
           let args = [

     

       383
       383
       +
             ("accountId", json_of_id account_id);

     

       384
       384
       +
           ] in

     

       385
       385
       +
           let args = match ids with

     

       386
       386
       +
             | None -> args

     

       387
       387
       +
             | Some ids -> ("ids", json_of_id_list ids) :: args

     

       388
       388
       +
           in

     

       389
       389
       +
           let args = match properties with

     

       390
       390
       +
             | None -> args

     

       391
       391
       +
             | Some props -> ("properties", json_of_string_list props) :: args

     

       392
       392
       +
           in

     

       393
       393
       +
           make_invocation ~name:"Identity/get" ~call_id args

     

       394
       394
       +
       

     

       395
       395
       +
         let email_submission_get ~call_id ~account_id ?ids ?properties () =

     

       396
       396
       +
           let args = [

     

       397
       397
       +
             ("accountId", json_of_id account_id);

     

       398
       398
       +
           ] in

     

       399
       399
       +
           let args = match ids with

     

       400
       400
       +
             | None -> args

     

       401
       401
       +
             | Some ids -> ("ids", json_of_id_list ids) :: args

     

       402
       402
       +
           in

     

       403
       403
       +
           let args = match properties with

     

       404
       404
       +
             | None -> args

     

       405
       405
       +
             | Some props -> ("properties", json_of_string_list props) :: args

     

       406
       406
       +
           in

     

       407
       407
       +
           make_invocation ~name:"EmailSubmission/get" ~call_id args

     

       408
       408
       +
       

     

       409
       409
       +
         let email_submission_query ~call_id ~account_id ?filter ?sort ?position ?limit () =

     

       410
       410
       +
           let args = [

     

       411
       411
       +
             ("accountId", json_of_id account_id);

     

       412
       412
       +
           ] in

     

       413
       413
       +
           let args = match filter with

     

       414
       414
       +
             | None -> args

     

       415
       415
       +
             | Some f ->

     

       416
       416
       +
                 ("filter", encode_to_json Jmap_mail.Mail_filter.submission_filter_jsont f) :: args

     

       417
       417
       +
           in

     

       418
       418
       +
           let args = match sort with

     

       419
       419
       +
             | None -> args

     

       420
       420
       +
             | Some comparators ->

     

       421
       421
       +
                 ("sort", encode_list_to_json Filter.comparator_jsont comparators) :: args

     

       422
       422
       +
           in

     

       423
       423
       +
           let args = match position with

     

       424
       424
       +
             | None -> args

     

       425
       425
       +
             | Some n -> ("position", json_of_int64 n) :: args

     

       426
       426
       +
           in

     

       427
       427
       +
           let args = match limit with

     

       428
       428
       +
             | None -> args

     

       429
       429
       +
             | Some n -> ("limit", json_of_int64 n) :: args

     

       430
       430
       +
           in

     

       431
       431
       +
           make_invocation ~name:"EmailSubmission/query" ~call_id args

     

       432
       432
       +
       

     

       433
       433
       +
         let vacation_response_get ~call_id ~account_id () =

     

       434
       434
       +
           let args = [

     

       435
       435
       +
             ("accountId", json_of_id account_id);

     

       436
       436
       +
             ("ids", json_of_id_list [Jmap_mail.Vacation.singleton_id]);

     

       437
       437
       +
           ] in

     

       438
       438
       +
           make_invocation ~name:"VacationResponse/get" ~call_id args

     

       439
       439
       +
       

     

       440
       440
       +
         let make_request ?created_ids ~capabilities invocations =

     

       441
       441
       +
           Request.create

     

       442
       442
       +
             ~using:capabilities

     

       443
       443
       +
             ~method_calls:invocations

     

       444
       444
       +
             ?created_ids

     

       445
       445
       +
             ()

     

       446
       446
       +
       end

     

       447
       447
       +
       

     

       448
       448
       +
       (* Response parsing helpers *)

     

       449
       449
       +
       module Parse = struct

     

       450
       450
       +
         open Jmap_proto

     

       451
       451
       +
       

     

       452
       452
       +
         let decode_from_json jsont json =

     

       453
       453
       +
           Jsont.Json.decode' jsont json

     

       454
       454
       +
       

     

       455
       455
       +
         let find_invocation ~call_id response =

     

       456
       456
       +
           List.find_opt

     

       457
       457
       +
             (fun inv -> Invocation.method_call_id inv = call_id)

     

       458
       458
       +
             (Response.method_responses response)

     

       459
       459
       +
       

     

       460
       460
       +
         let get_invocation_exn ~call_id response =

     

       461
       461
       +
           match find_invocation ~call_id response with

     

       462
       462
       +
           | Some inv -> inv

     

       463
       463
       +
           | None -> failwith ("No invocation found with call_id: " ^ call_id)

     

       464
       464
       +
       

     

       465
       465
       +
         let parse_invocation jsont inv =

     

       466
       466
       +
           decode_from_json jsont (Invocation.arguments inv)

     

       467
       467
       +
       

     

       468
       468
       +
         let parse_response ~call_id jsont response =

     

       469
       469
       +
           let inv = get_invocation_exn ~call_id response in

     

       470
       470
       +
           parse_invocation jsont inv

     

       471
       471
       +
       

     

       472
       472
       +
         (* Typed response parsers *)

     

       473
       473
       +
       

     

       474
       474
       +
         let get_response obj_jsont =

     

       475
       475
       +
           Method.get_response_jsont obj_jsont

     

       476
       476
       +
       

     

       477
       477
       +
         let query_response = Method.query_response_jsont

     

       478
       478
       +
       

     

       479
       479
       +
         let changes_response = Method.changes_response_jsont

     

       480
       480
       +
       

     

       481
       481
       +
         let set_response obj_jsont =

     

       482
       482
       +
           Method.set_response_jsont obj_jsont

     

       483
       483
       +
       

     

       484
       484
       +
         (* Mail-specific parsers *)

     

       485
       485
       +
       

     

       486
       486
       +
         let mailbox_get_response =

     

       487
       487
       +
           get_response Jmap_mail.Mailbox.jsont

     

       488
       488
       +
       

     

       489
       489
       +
         let email_get_response =

     

       490
       490
       +
           get_response Jmap_mail.Email.jsont

     

       491
       491
       +
       

     

       492
       492
       +
         let thread_get_response =

     

       493
       493
       +
           get_response Jmap_mail.Thread.jsont

     

       494
       494
       +
       

     

       495
       495
       +
         let identity_get_response =

     

       496
       496
       +
           get_response Jmap_mail.Identity.jsont

     

       497
       497
       +
       

     

       498
       498
       +
         (* Convenience functions *)

     

       499
       499
       +
       

     

       500
       500
       +
         let parse_mailbox_get ~call_id response =

     

       501
       501
       +
           parse_response ~call_id mailbox_get_response response

     

       502
       502
       +
       

     

       503
       503
       +
         let parse_email_get ~call_id response =

     

       504
       504
       +
           parse_response ~call_id email_get_response response

     

       505
       505
       +
       

     

       506
       506
       +
         let parse_email_query ~call_id response =

     

       507
       507
       +
           parse_response ~call_id query_response response

     

       508
       508
       +
       

     

       509
       509
       +
         let parse_thread_get ~call_id response =

     

       510
       510
       +
           parse_response ~call_id thread_get_response response

     

       511
       511
       +
       

     

       512
       512
       +
         let parse_changes ~call_id response =

     

       513
       513
       +
           parse_response ~call_id changes_response response

     

       514
       514
       +
       end

+404

eio/client.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** High-level JMAP client using Requests

     

       7
       7
       +
       

     

       8
       8
       +
           This module provides a full-featured JMAP client with session management,

     

       9
       9
       +
           request execution, and blob upload/download capabilities. *)

     

       10
       10
       +
       

     

       11
       11
       +
       (** {1 Types} *)

     

       12
       12
       +
       

     

       13
       13
       +
       type t

     

       14
       14
       +
       (** A JMAP client with session state and HTTP connection management. *)

     

       15
       15
       +
       

     

       16
       16
       +
       type error =

     

       17
       17
       +
         | Http_error of int * string

     

       18
       18
       +
             (** HTTP error with status code and message. *)

     

       19
       19
       +
         | Jmap_error of Jmap_proto.Error.Request_error.t

     

       20
       20
       +
             (** JMAP protocol error at request level. *)

     

       21
       21
       +
         | Json_error of Jsont.Error.t

     

       22
       22
       +
             (** JSON encoding/decoding error. *)

     

       23
       23
       +
         | Session_error of string

     

       24
       24
       +
             (** Session fetch or parse error. *)

     

       25
       25
       +
         | Connection_error of string

     

       26
       26
       +
             (** Network connection error. *)

     

       27
       27
       +
       (** Error types that can occur during JMAP operations. *)

     

       28
       28
       +
       

     

       29
       29
       +
       val pp_error : Format.formatter -> error -> unit

     

       30
       30
       +
       (** Pretty-print an error. *)

     

       31
       31
       +
       

     

       32
       32
       +
       val error_to_string : error -> string

     

       33
       33
       +
       (** Convert an error to a string. *)

     

       34
       34
       +
       

     

       35
       35
       +
       exception Jmap_client_error of error

     

       36
       36
       +
       (** Exception wrapper for JMAP client errors. *)

     

       37
       37
       +
       

     

       38
       38
       +
       (** {1 Client Creation} *)

     

       39
       39
       +
       

     

       40
       40
       +
       val create :

     

       41
       41
       +
         ?auth:Requests.Auth.t ->

     

       42
       42
       +
         session:Jmap_proto.Session.t ->

     

       43
       43
       +
         Requests.t ->

     

       44
       44
       +
         t

     

       45
       45
       +
       (** [create ?auth ~session requests] creates a JMAP client from an existing

     

       46
       46
       +
           session and Requests instance.

     

       47
       47
       +
       

     

       48
       48
       +
           @param auth Authentication to use for requests.

     

       49
       49
       +
           @param session A pre-fetched JMAP session.

     

       50
       50
       +
           @param requests The Requests instance for HTTP operations. *)

     

       51
       51
       +
       

     

       52
       52
       +
       val create_from_url :

     

       53
       53
       +
         ?auth:Requests.Auth.t ->

     

       54
       54
       +
         Requests.t ->

     

       55
       55
       +
         string ->

     

       56
       56
       +
         (t, error) result

     

       57
       57
       +
       (** [create_from_url ?auth requests url] creates a JMAP client by fetching

     

       58
       58
       +
           the session from the given JMAP API URL or well-known URL.

     

       59
       59
       +
       

     

       60
       60
       +
           The URL can be either:

     

       61
       61
       +
           - A direct JMAP API URL (e.g., "https://api.example.com/jmap/")

     

       62
       62
       +
           - A well-known URL (e.g., "https://example.com/.well-known/jmap")

     

       63
       63
       +
       

     

       64
       64
       +
           @param auth Authentication to use for the session request and subsequent requests.

     

       65
       65
       +
           @param requests The Requests instance for HTTP operations.

     

       66
       66
       +
           @param url The JMAP API or well-known URL. *)

     

       67
       67
       +
       

     

       68
       68
       +
       val create_from_url_exn :

     

       69
       69
       +
         ?auth:Requests.Auth.t ->

     

       70
       70
       +
         Requests.t ->

     

       71
       71
       +
         string ->

     

       72
       72
       +
         t

     

       73
       73
       +
       (** [create_from_url_exn ?auth requests url] is like {!create_from_url} but

     

       74
       74
       +
           raises {!Jmap_client_error} on failure. *)

     

       75
       75
       +
       

     

       76
       76
       +
       (** {1 Session Access} *)

     

       77
       77
       +
       

     

       78
       78
       +
       val session : t -> Jmap_proto.Session.t

     

       79
       79
       +
       (** [session client] returns the current JMAP session. *)

     

       80
       80
       +
       

     

       81
       81
       +
       val refresh_session : t -> (unit, error) result

     

       82
       82
       +
       (** [refresh_session client] fetches a fresh session from the server and

     

       83
       83
       +
           updates the client's session state. *)

     

       84
       84
       +
       

     

       85
       85
       +
       val refresh_session_exn : t -> unit

     

       86
       86
       +
       (** [refresh_session_exn client] is like {!refresh_session} but raises on error. *)

     

       87
       87
       +
       

     

       88
       88
       +
       val api_url : t -> string

     

       89
       89
       +
       (** [api_url client] returns the JMAP API URL for this client. *)

     

       90
       90
       +
       

     

       91
       91
       +
       val upload_url : t -> string

     

       92
       92
       +
       (** [upload_url client] returns the blob upload URL template. *)

     

       93
       93
       +
       

     

       94
       94
       +
       val download_url : t -> string

     

       95
       95
       +
       (** [download_url client] returns the blob download URL template. *)

     

       96
       96
       +
       

     

       97
       97
       +
       (** {1 Request Execution} *)

     

       98
       98
       +
       

     

       99
       99
       +
       val request :

     

       100
       100
       +
         t ->

     

       101
       101
       +
         Jmap_proto.Request.t ->

     

       102
       102
       +
         (Jmap_proto.Response.t, error) result

     

       103
       103
       +
       (** [request client req] executes a JMAP request and returns the response. *)

     

       104
       104
       +
       

     

       105
       105
       +
       val request_exn :

     

       106
       106
       +
         t ->

     

       107
       107
       +
         Jmap_proto.Request.t ->

     

       108
       108
       +
         Jmap_proto.Response.t

     

       109
       109
       +
       (** [request_exn client req] is like {!request} but raises on error. *)

     

       110
       110
       +
       

     

       111
       111
       +
       (** {1 Blob Operations} *)

     

       112
       112
       +
       

     

       113
       113
       +
       val upload :

     

       114
       114
       +
         t ->

     

       115
       115
       +
         account_id:Jmap_proto.Id.t ->

     

       116
       116
       +
         content_type:string ->

     

       117
       117
       +
         data:string ->

     

       118
       118
       +
         (Jmap_proto.Blob.upload_response, error) result

     

       119
       119
       +
       (** [upload client ~account_id ~content_type ~data] uploads a blob.

     

       120
       120
       +
       

     

       121
       121
       +
           @param account_id The account to upload to.

     

       122
       122
       +
           @param content_type MIME type of the blob.

     

       123
       123
       +
           @param data The blob data as a string. *)

     

       124
       124
       +
       

     

       125
       125
       +
       val upload_exn :

     

       126
       126
       +
         t ->

     

       127
       127
       +
         account_id:Jmap_proto.Id.t ->

     

       128
       128
       +
         content_type:string ->

     

       129
       129
       +
         data:string ->

     

       130
       130
       +
         Jmap_proto.Blob.upload_response

     

       131
       131
       +
       (** [upload_exn client ~account_id ~content_type ~data] is like {!upload}

     

       132
       132
       +
           but raises on error. *)

     

       133
       133
       +
       

     

       134
       134
       +
       val download :

     

       135
       135
       +
         t ->

     

       136
       136
       +
         account_id:Jmap_proto.Id.t ->

     

       137
       137
       +
         blob_id:Jmap_proto.Id.t ->

     

       138
       138
       +
         ?name:string ->

     

       139
       139
       +
         ?accept:string ->

     

       140
       140
       +
         unit ->

     

       141
       141
       +
         (string, error) result

     

       142
       142
       +
       (** [download client ~account_id ~blob_id ?name ?accept ()] downloads a blob.

     

       143
       143
       +
       

     

       144
       144
       +
           @param account_id The account containing the blob.

     

       145
       145
       +
           @param blob_id The blob ID to download.

     

       146
       146
       +
           @param name Optional filename hint for Content-Disposition.

     

       147
       147
       +
           @param accept Optional Accept header value. *)

     

       148
       148
       +
       

     

       149
       149
       +
       val download_exn :

     

       150
       150
       +
         t ->

     

       151
       151
       +
         account_id:Jmap_proto.Id.t ->

     

       152
       152
       +
         blob_id:Jmap_proto.Id.t ->

     

       153
       153
       +
         ?name:string ->

     

       154
       154
       +
         ?accept:string ->

     

       155
       155
       +
         unit ->

     

       156
       156
       +
         string

     

       157
       157
       +
       (** [download_exn] is like {!download} but raises on error. *)

     

       158
       158
       +
       

     

       159
       159
       +
       (** {1 Convenience Builders}

     

       160
       160
       +
       

     

       161
       161
       +
           Helper functions for building common JMAP method invocations. *)

     

       162
       162
       +
       

     

       163
       163
       +
       module Build : sig

     

       164
       164
       +
         (** {2 Core Methods} *)

     

       165
       165
       +
       

     

       166
       166
       +
         val echo :

     

       167
       167
       +
           call_id:string ->

     

       168
       168
       +
           Jsont.json ->

     

       169
       169
       +
           Jmap_proto.Invocation.t

     

       170
       170
       +
         (** [echo ~call_id data] builds a Core/echo invocation. *)

     

       171
       171
       +
       

     

       172
       172
       +
         (** {2 Mailbox Methods} *)

     

       173
       173
       +
       

     

       174
       174
       +
         val mailbox_get :

     

       175
       175
       +
           call_id:string ->

     

       176
       176
       +
           account_id:Jmap_proto.Id.t ->

     

       177
       177
       +
           ?ids:Jmap_proto.Id.t list ->

     

       178
       178
       +
           ?properties:string list ->

     

       179
       179
       +
           unit ->

     

       180
       180
       +
           Jmap_proto.Invocation.t

     

       181
       181
       +
         (** [mailbox_get ~call_id ~account_id ?ids ?properties ()] builds a

     

       182
       182
       +
             Mailbox/get invocation. *)

     

       183
       183
       +
       

     

       184
       184
       +
         val mailbox_changes :

     

       185
       185
       +
           call_id:string ->

     

       186
       186
       +
           account_id:Jmap_proto.Id.t ->

     

       187
       187
       +
           since_state:string ->

     

       188
       188
       +
           ?max_changes:int64 ->

     

       189
       189
       +
           unit ->

     

       190
       190
       +
           Jmap_proto.Invocation.t

     

       191
       191
       +
         (** [mailbox_changes ~call_id ~account_id ~since_state ?max_changes ()]

     

       192
       192
       +
             builds a Mailbox/changes invocation. *)

     

       193
       193
       +
       

     

       194
       194
       +
         val mailbox_query :

     

       195
       195
       +
           call_id:string ->

     

       196
       196
       +
           account_id:Jmap_proto.Id.t ->

     

       197
       197
       +
           ?filter:Jmap_mail.Mail_filter.mailbox_filter ->

     

       198
       198
       +
           ?sort:Jmap_proto.Filter.comparator list ->

     

       199
       199
       +
           ?position:int64 ->

     

       200
       200
       +
           ?limit:int64 ->

     

       201
       201
       +
           unit ->

     

       202
       202
       +
           Jmap_proto.Invocation.t

     

       203
       203
       +
         (** [mailbox_query ~call_id ~account_id ?filter ?sort ?position ?limit ()]

     

       204
       204
       +
             builds a Mailbox/query invocation. *)

     

       205
       205
       +
       

     

       206
       206
       +
         (** {2 Email Methods} *)

     

       207
       207
       +
       

     

       208
       208
       +
         val email_get :

     

       209
       209
       +
           call_id:string ->

     

       210
       210
       +
           account_id:Jmap_proto.Id.t ->

     

       211
       211
       +
           ?ids:Jmap_proto.Id.t list ->

     

       212
       212
       +
           ?properties:string list ->

     

       213
       213
       +
           ?body_properties:string list ->

     

       214
       214
       +
           ?fetch_text_body_values:bool ->

     

       215
       215
       +
           ?fetch_html_body_values:bool ->

     

       216
       216
       +
           ?fetch_all_body_values:bool ->

     

       217
       217
       +
           ?max_body_value_bytes:int64 ->

     

       218
       218
       +
           unit ->

     

       219
       219
       +
           Jmap_proto.Invocation.t

     

       220
       220
       +
         (** [email_get ~call_id ~account_id ?ids ?properties ...] builds an

     

       221
       221
       +
             Email/get invocation. *)

     

       222
       222
       +
       

     

       223
       223
       +
         val email_changes :

     

       224
       224
       +
           call_id:string ->

     

       225
       225
       +
           account_id:Jmap_proto.Id.t ->

     

       226
       226
       +
           since_state:string ->

     

       227
       227
       +
           ?max_changes:int64 ->

     

       228
       228
       +
           unit ->

     

       229
       229
       +
           Jmap_proto.Invocation.t

     

       230
       230
       +
         (** [email_changes ~call_id ~account_id ~since_state ?max_changes ()]

     

       231
       231
       +
             builds an Email/changes invocation. *)

     

       232
       232
       +
       

     

       233
       233
       +
         val email_query :

     

       234
       234
       +
           call_id:string ->

     

       235
       235
       +
           account_id:Jmap_proto.Id.t ->

     

       236
       236
       +
           ?filter:Jmap_mail.Mail_filter.email_filter ->

     

       237
       237
       +
           ?sort:Jmap_proto.Filter.comparator list ->

     

       238
       238
       +
           ?position:int64 ->

     

       239
       239
       +
           ?limit:int64 ->

     

       240
       240
       +
           ?collapse_threads:bool ->

     

       241
       241
       +
           unit ->

     

       242
       242
       +
           Jmap_proto.Invocation.t

     

       243
       243
       +
         (** [email_query ~call_id ~account_id ?filter ?sort ?position ?limit

     

       244
       244
       +
             ?collapse_threads ()] builds an Email/query invocation. *)

     

       245
       245
       +
       

     

       246
       246
       +
         (** {2 Thread Methods} *)

     

       247
       247
       +
       

     

       248
       248
       +
         val thread_get :

     

       249
       249
       +
           call_id:string ->

     

       250
       250
       +
           account_id:Jmap_proto.Id.t ->

     

       251
       251
       +
           ?ids:Jmap_proto.Id.t list ->

     

       252
       252
       +
           unit ->

     

       253
       253
       +
           Jmap_proto.Invocation.t

     

       254
       254
       +
         (** [thread_get ~call_id ~account_id ?ids ()] builds a Thread/get invocation. *)

     

       255
       255
       +
       

     

       256
       256
       +
         val thread_changes :

     

       257
       257
       +
           call_id:string ->

     

       258
       258
       +
           account_id:Jmap_proto.Id.t ->

     

       259
       259
       +
           since_state:string ->

     

       260
       260
       +
           ?max_changes:int64 ->

     

       261
       261
       +
           unit ->

     

       262
       262
       +
           Jmap_proto.Invocation.t

     

       263
       263
       +
         (** [thread_changes ~call_id ~account_id ~since_state ?max_changes ()]

     

       264
       264
       +
             builds a Thread/changes invocation. *)

     

       265
       265
       +
       

     

       266
       266
       +
         (** {2 Identity Methods} *)

     

       267
       267
       +
       

     

       268
       268
       +
         val identity_get :

     

       269
       269
       +
           call_id:string ->

     

       270
       270
       +
           account_id:Jmap_proto.Id.t ->

     

       271
       271
       +
           ?ids:Jmap_proto.Id.t list ->

     

       272
       272
       +
           ?properties:string list ->

     

       273
       273
       +
           unit ->

     

       274
       274
       +
           Jmap_proto.Invocation.t

     

       275
       275
       +
         (** [identity_get ~call_id ~account_id ?ids ?properties ()] builds an

     

       276
       276
       +
             Identity/get invocation. *)

     

       277
       277
       +
       

     

       278
       278
       +
         (** {2 Submission Methods} *)

     

       279
       279
       +
       

     

       280
       280
       +
         val email_submission_get :

     

       281
       281
       +
           call_id:string ->

     

       282
       282
       +
           account_id:Jmap_proto.Id.t ->

     

       283
       283
       +
           ?ids:Jmap_proto.Id.t list ->

     

       284
       284
       +
           ?properties:string list ->

     

       285
       285
       +
           unit ->

     

       286
       286
       +
           Jmap_proto.Invocation.t

     

       287
       287
       +
         (** [email_submission_get ~call_id ~account_id ?ids ?properties ()]

     

       288
       288
       +
             builds an EmailSubmission/get invocation. *)

     

       289
       289
       +
       

     

       290
       290
       +
         val email_submission_query :

     

       291
       291
       +
           call_id:string ->

     

       292
       292
       +
           account_id:Jmap_proto.Id.t ->

     

       293
       293
       +
           ?filter:Jmap_mail.Mail_filter.submission_filter ->

     

       294
       294
       +
           ?sort:Jmap_proto.Filter.comparator list ->

     

       295
       295
       +
           ?position:int64 ->

     

       296
       296
       +
           ?limit:int64 ->

     

       297
       297
       +
           unit ->

     

       298
       298
       +
           Jmap_proto.Invocation.t

     

       299
       299
       +
         (** [email_submission_query ~call_id ~account_id ?filter ?sort ?position

     

       300
       300
       +
             ?limit ()] builds an EmailSubmission/query invocation. *)

     

       301
       301
       +
       

     

       302
       302
       +
         (** {2 Vacation Response Methods} *)

     

       303
       303
       +
       

     

       304
       304
       +
         val vacation_response_get :

     

       305
       305
       +
           call_id:string ->

     

       306
       306
       +
           account_id:Jmap_proto.Id.t ->

     

       307
       307
       +
           unit ->

     

       308
       308
       +
           Jmap_proto.Invocation.t

     

       309
       309
       +
         (** [vacation_response_get ~call_id ~account_id ()] builds a

     

       310
       310
       +
             VacationResponse/get invocation. The singleton ID is automatically used. *)

     

       311
       311
       +
       

     

       312
       312
       +
         (** {2 Request Building} *)

     

       313
       313
       +
       

     

       314
       314
       +
         val make_request :

     

       315
       315
       +
           ?created_ids:(Jmap_proto.Id.t * Jmap_proto.Id.t) list ->

     

       316
       316
       +
           capabilities:string list ->

     

       317
       317
       +
           Jmap_proto.Invocation.t list ->

     

       318
       318
       +
           Jmap_proto.Request.t

     

       319
       319
       +
         (** [make_request ?created_ids ~capabilities invocations] builds a JMAP request.

     

       320
       320
       +
       

     

       321
       321
       +
             @param created_ids Optional client-created ID mappings.

     

       322
       322
       +
             @param capabilities List of capability URIs to use.

     

       323
       323
       +
             @param invocations List of method invocations. *)

     

       324
       324
       +
       end

     

       325
       325
       +
       

     

       326
       326
       +
       (** {1 Response Parsing}

     

       327
       327
       +
       

     

       328
       328
       +
           Helper functions for parsing typed responses from JMAP invocations. *)

     

       329
       329
       +
       

     

       330
       330
       +
       module Parse : sig

     

       331
       331
       +
         val find_invocation :

     

       332
       332
       +
           call_id:string ->

     

       333
       333
       +
           Jmap_proto.Response.t ->

     

       334
       334
       +
           Jmap_proto.Invocation.t option

     

       335
       335
       +
         (** [find_invocation ~call_id response] finds an invocation by call ID. *)

     

       336
       336
       +
       

     

       337
       337
       +
         val get_invocation_exn :

     

       338
       338
       +
           call_id:string ->

     

       339
       339
       +
           Jmap_proto.Response.t ->

     

       340
       340
       +
           Jmap_proto.Invocation.t

     

       341
       341
       +
         (** [get_invocation_exn ~call_id response] finds an invocation by call ID.

     

       342
       342
       +
             @raise Failure if not found. *)

     

       343
       343
       +
       

     

       344
       344
       +
         val parse_invocation :

     

       345
       345
       +
           'a Jsont.t ->

     

       346
       346
       +
           Jmap_proto.Invocation.t ->

     

       347
       347
       +
           ('a, Jsont.Error.t) result

     

       348
       348
       +
         (** [parse_invocation jsont inv] decodes the invocation's arguments. *)

     

       349
       349
       +
       

     

       350
       350
       +
         val parse_response :

     

       351
       351
       +
           call_id:string ->

     

       352
       352
       +
           'a Jsont.t ->

     

       353
       353
       +
           Jmap_proto.Response.t ->

     

       354
       354
       +
           ('a, Jsont.Error.t) result

     

       355
       355
       +
         (** [parse_response ~call_id jsont response] finds and parses an invocation. *)

     

       356
       356
       +
       

     

       357
       357
       +
         (** {2 Typed Response Codecs} *)

     

       358
       358
       +
       

     

       359
       359
       +
         val get_response : 'a Jsont.t -> 'a Jmap_proto.Method.get_response Jsont.t

     

       360
       360
       +
         (** [get_response obj_jsont] creates a Foo/get response codec. *)

     

       361
       361
       +
       

     

       362
       362
       +
         val query_response : Jmap_proto.Method.query_response Jsont.t

     

       363
       363
       +
         (** Codec for Foo/query responses. *)

     

       364
       364
       +
       

     

       365
       365
       +
         val changes_response : Jmap_proto.Method.changes_response Jsont.t

     

       366
       366
       +
         (** Codec for Foo/changes responses. *)

     

       367
       367
       +
       

     

       368
       368
       +
         val set_response : 'a Jsont.t -> 'a Jmap_proto.Method.set_response Jsont.t

     

       369
       369
       +
         (** [set_response obj_jsont] creates a Foo/set response codec. *)

     

       370
       370
       +
       

     

       371
       371
       +
         (** {2 Mail-specific Codecs} *)

     

       372
       372
       +
       

     

       373
       373
       +
         val mailbox_get_response : Jmap_mail.Mailbox.t Jmap_proto.Method.get_response Jsont.t

     

       374
       374
       +
         val email_get_response : Jmap_mail.Email.t Jmap_proto.Method.get_response Jsont.t

     

       375
       375
       +
         val thread_get_response : Jmap_mail.Thread.t Jmap_proto.Method.get_response Jsont.t

     

       376
       376
       +
         val identity_get_response : Jmap_mail.Identity.t Jmap_proto.Method.get_response Jsont.t

     

       377
       377
       +
       

     

       378
       378
       +
         (** {2 Convenience Parsers} *)

     

       379
       379
       +
       

     

       380
       380
       +
         val parse_mailbox_get :

     

       381
       381
       +
           call_id:string ->

     

       382
       382
       +
           Jmap_proto.Response.t ->

     

       383
       383
       +
           (Jmap_mail.Mailbox.t Jmap_proto.Method.get_response, Jsont.Error.t) result

     

       384
       384
       +
       

     

       385
       385
       +
         val parse_email_get :

     

       386
       386
       +
           call_id:string ->

     

       387
       387
       +
           Jmap_proto.Response.t ->

     

       388
       388
       +
           (Jmap_mail.Email.t Jmap_proto.Method.get_response, Jsont.Error.t) result

     

       389
       389
       +
       

     

       390
       390
       +
         val parse_email_query :

     

       391
       391
       +
           call_id:string ->

     

       392
       392
       +
           Jmap_proto.Response.t ->

     

       393
       393
       +
           (Jmap_proto.Method.query_response, Jsont.Error.t) result

     

       394
       394
       +
       

     

       395
       395
       +
         val parse_thread_get :

     

       396
       396
       +
           call_id:string ->

     

       397
       397
       +
           Jmap_proto.Response.t ->

     

       398
       398
       +
           (Jmap_mail.Thread.t Jmap_proto.Method.get_response, Jsont.Error.t) result

     

       399
       399
       +
       

     

       400
       400
       +
         val parse_changes :

     

       401
       401
       +
           call_id:string ->

     

       402
       402
       +
           Jmap_proto.Response.t ->

     

       403
       403
       +
           (Jmap_proto.Method.changes_response, Jsont.Error.t) result

     

       404
       404
       +
       end

+42

eio/codec.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       let encode ?format jsont value =

     

       7
       7
       +
         Jsont_bytesrw.encode_string' ?format jsont value

     

       8
       8
       +
       

     

       9
       9
       +
       let decode ?locs jsont json =

     

       10
       10
       +
         Jsont_bytesrw.decode_string' ?locs jsont json

     

       11
       11
       +
       

     

       12
       12
       +
       let encode_request ?format request =

     

       13
       13
       +
         encode ?format Jmap_proto.Request.jsont request

     

       14
       14
       +
       

     

       15
       15
       +
       let encode_request_exn ?format request =

     

       16
       16
       +
         match encode_request ?format request with

     

       17
       17
       +
         | Ok s -> s

     

       18
       18
       +
         | Error e -> failwith (Jsont.Error.to_string e)

     

       19
       19
       +
       

     

       20
       20
       +
       let decode_response ?locs json =

     

       21
       21
       +
         decode ?locs Jmap_proto.Response.jsont json

     

       22
       22
       +
       

     

       23
       23
       +
       let decode_response_exn ?locs json =

     

       24
       24
       +
         match decode_response ?locs json with

     

       25
       25
       +
         | Ok r -> r

     

       26
       26
       +
         | Error e -> failwith (Jsont.Error.to_string e)

     

       27
       27
       +
       

     

       28
       28
       +
       let decode_session ?locs json =

     

       29
       29
       +
         decode ?locs Jmap_proto.Session.jsont json

     

       30
       30
       +
       

     

       31
       31
       +
       let decode_session_exn ?locs json =

     

       32
       32
       +
         match decode_session ?locs json with

     

       33
       33
       +
         | Ok s -> s

     

       34
       34
       +
         | Error e -> failwith (Jsont.Error.to_string e)

     

       35
       35
       +
       

     

       36
       36
       +
       let decode_upload_response ?locs json =

     

       37
       37
       +
         decode ?locs Jmap_proto.Blob.upload_response_jsont json

     

       38
       38
       +
       

     

       39
       39
       +
       let decode_upload_response_exn ?locs json =

     

       40
       40
       +
         match decode_upload_response ?locs json with

     

       41
       41
       +
         | Ok r -> r

     

       42
       42
       +
         | Error e -> failwith (Jsont.Error.to_string e)

+92

eio/codec.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP JSON codec for Eio

     

       7
       7
       +
       

     

       8
       8
       +
           Low-level encoding and decoding of JMAP messages using jsont and bytesrw. *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** {1 Request Encoding} *)

     

       11
       11
       +
       

     

       12
       12
       +
       val encode_request :

     

       13
       13
       +
         ?format:Jsont.format ->

     

       14
       14
       +
         Jmap_proto.Request.t ->

     

       15
       15
       +
         (string, Jsont.Error.t) result

     

       16
       16
       +
       (** [encode_request ?format request] encodes a JMAP request to a JSON string.

     

       17
       17
       +
       

     

       18
       18
       +
           @param format The JSON formatting style. Defaults to {!Jsont.Minify}. *)

     

       19
       19
       +
       

     

       20
       20
       +
       val encode_request_exn :

     

       21
       21
       +
         ?format:Jsont.format ->

     

       22
       22
       +
         Jmap_proto.Request.t ->

     

       23
       23
       +
         string

     

       24
       24
       +
       (** [encode_request_exn ?format request] is like {!encode_request} but raises

     

       25
       25
       +
           on encoding errors. *)

     

       26
       26
       +
       

     

       27
       27
       +
       (** {1 Response Decoding} *)

     

       28
       28
       +
       

     

       29
       29
       +
       val decode_response :

     

       30
       30
       +
         ?locs:bool ->

     

       31
       31
       +
         string ->

     

       32
       32
       +
         (Jmap_proto.Response.t, Jsont.Error.t) result

     

       33
       33
       +
       (** [decode_response ?locs json] decodes a JMAP response from a JSON string.

     

       34
       34
       +
       

     

       35
       35
       +
           @param locs If [true], location information is preserved for error messages.

     

       36
       36
       +
                       Defaults to [false]. *)

     

       37
       37
       +
       

     

       38
       38
       +
       val decode_response_exn :

     

       39
       39
       +
         ?locs:bool ->

     

       40
       40
       +
         string ->

     

       41
       41
       +
         Jmap_proto.Response.t

     

       42
       42
       +
       (** [decode_response_exn ?locs json] is like {!decode_response} but raises

     

       43
       43
       +
           on decoding errors. *)

     

       44
       44
       +
       

     

       45
       45
       +
       (** {1 Session Decoding} *)

     

       46
       46
       +
       

     

       47
       47
       +
       val decode_session :

     

       48
       48
       +
         ?locs:bool ->

     

       49
       49
       +
         string ->

     

       50
       50
       +
         (Jmap_proto.Session.t, Jsont.Error.t) result

     

       51
       51
       +
       (** [decode_session ?locs json] decodes a JMAP session from a JSON string.

     

       52
       52
       +
       

     

       53
       53
       +
           @param locs If [true], location information is preserved for error messages.

     

       54
       54
       +
                       Defaults to [false]. *)

     

       55
       55
       +
       

     

       56
       56
       +
       val decode_session_exn :

     

       57
       57
       +
         ?locs:bool ->

     

       58
       58
       +
         string ->

     

       59
       59
       +
         Jmap_proto.Session.t

     

       60
       60
       +
       (** [decode_session_exn ?locs json] is like {!decode_session} but raises

     

       61
       61
       +
           on decoding errors. *)

     

       62
       62
       +
       

     

       63
       63
       +
       (** {1 Blob Upload Response Decoding} *)

     

       64
       64
       +
       

     

       65
       65
       +
       val decode_upload_response :

     

       66
       66
       +
         ?locs:bool ->

     

       67
       67
       +
         string ->

     

       68
       68
       +
         (Jmap_proto.Blob.upload_response, Jsont.Error.t) result

     

       69
       69
       +
       (** [decode_upload_response ?locs json] decodes a blob upload response. *)

     

       70
       70
       +
       

     

       71
       71
       +
       val decode_upload_response_exn :

     

       72
       72
       +
         ?locs:bool ->

     

       73
       73
       +
         string ->

     

       74
       74
       +
         Jmap_proto.Blob.upload_response

     

       75
       75
       +
       (** [decode_upload_response_exn ?locs json] is like {!decode_upload_response}

     

       76
       76
       +
           but raises on decoding errors. *)

     

       77
       77
       +
       

     

       78
       78
       +
       (** {1 Generic Encoding/Decoding} *)

     

       79
       79
       +
       

     

       80
       80
       +
       val encode :

     

       81
       81
       +
         ?format:Jsont.format ->

     

       82
       82
       +
         'a Jsont.t ->

     

       83
       83
       +
         'a ->

     

       84
       84
       +
         (string, Jsont.Error.t) result

     

       85
       85
       +
       (** [encode ?format jsont value] encodes any value using its jsont codec. *)

     

       86
       86
       +
       

     

       87
       87
       +
       val decode :

     

       88
       88
       +
         ?locs:bool ->

     

       89
       89
       +
         'a Jsont.t ->

     

       90
       90
       +
         string ->

     

       91
       91
       +
         ('a, Jsont.Error.t) result

     

       92
       92
       +
       (** [decode ?locs jsont json] decodes any value using its jsont codec. *)

eio/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name jmap_eio)

     

       3
       3
       +
        (public_name jmap-eio)

     

       4
       4
       +
        (libraries jmap jmap.mail jsont jsont.bytesrw eio requests uri str)

     

       5
       5
       +
        (modules jmap_eio codec client))

eio/jmap_eio.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       module Codec = Codec

     

       7
       7
       +
       module Client = Client

+73

eio/jmap_eio.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP client library for Eio

     

       7
       7
       +
       

     

       8
       8
       +
           This library provides a complete JMAP (RFC 8620/8621) client implementation

     

       9
       9
       +
           for OCaml using Eio for effects-based concurrency and Requests for HTTP.

     

       10
       10
       +
       

     

       11
       11
       +
           {2 Overview}

     

       12
       12
       +
       

     

       13
       13
       +
           The library consists of two layers:

     

       14
       14
       +
       

     

       15
       15
       +
           - {!Codec}: Low-level JSON encoding/decoding for JMAP messages

     

       16
       16
       +
           - {!Client}: High-level JMAP client with session management

     

       17
       17
       +
       

     

       18
       18
       +
           {2 Quick Start}

     

       19
       19
       +
       

     

       20
       20
       +
           {[

     

       21
       21
       +
             open Eio_main

     

       22
       22
       +
       

     

       23
       23
       +
             let () = run @@ fun env ->

     

       24
       24
       +
               Eio.Switch.run @@ fun sw ->

     

       25
       25
       +
       

     

       26
       26
       +
               (* Create HTTP client *)

     

       27
       27
       +
               let requests = Requests.create ~sw env in

     

       28
       28
       +
       

     

       29
       29
       +
               (* Create JMAP client from well-known URL *)

     

       30
       30
       +
               let client = Jmap_eio.Client.create_from_url_exn

     

       31
       31
       +
                 ~auth:(Requests.Auth.bearer "your-token")

     

       32
       32
       +
                 requests

     

       33
       33
       +
                 "https://api.example.com/.well-known/jmap" in

     

       34
       34
       +
       

     

       35
       35
       +
               (* Get session info *)

     

       36
       36
       +
               let session = Jmap_eio.Client.session client in

     

       37
       37
       +
               Printf.printf "API URL: %s\n" (Jmap_proto.Session.api_url session);

     

       38
       38
       +
       

     

       39
       39
       +
               (* Build and execute a request *)

     

       40
       40
       +
               let account_id = (* get from session *) ... in

     

       41
       41
       +
               let req = Jmap_eio.Client.Build.(

     

       42
       42
       +
                 make_request

     

       43
       43
       +
                   ~capabilities:[Jmap_proto.Capability.core_uri;

     

       44
       44
       +
                                 Jmap_proto.Capability.mail_uri]

     

       45
       45
       +
                   [mailbox_get ~call_id:"0" ~account_id ()]

     

       46
       46
       +
               ) in

     

       47
       47
       +
               let response = Jmap_eio.Client.request_exn client req in

     

       48
       48
       +
       

     

       49
       49
       +
               (* Process response *)

     

       50
       50
       +
               List.iter (fun inv ->

     

       51
       51
       +
                 Printf.printf "Method: %s, CallId: %s\n"

     

       52
       52
       +
                   (Jmap_proto.Invocation.name inv)

     

       53
       53
       +
                   (Jmap_proto.Invocation.method_call_id inv)

     

       54
       54
       +
               ) (Jmap_proto.Response.method_responses response)

     

       55
       55
       +
           ]}

     

       56
       56
       +
       

     

       57
       57
       +
           {2 Capabilities}

     

       58
       58
       +
       

     

       59
       59
       +
           JMAP uses capability URIs to indicate supported features:

     

       60
       60
       +
       

     

       61
       61
       +
           - [urn:ietf:params:jmap:core] - Core JMAP

     

       62
       62
       +
           - [urn:ietf:params:jmap:mail] - Email, Mailbox, Thread

     

       63
       63
       +
           - [urn:ietf:params:jmap:submission] - EmailSubmission

     

       64
       64
       +
           - [urn:ietf:params:jmap:vacationresponse] - VacationResponse

     

       65
       65
       +
       

     

       66
       66
       +
           These are available as constants in {!Jmap_proto.Capability}.

     

       67
       67
       +
       *)

     

       68
       68
       +
       

     

       69
       69
       +
       (** Low-level JSON codec for JMAP messages. *)

     

       70
       70
       +
       module Codec = Codec

     

       71
       71
       +
       

     

       72
       72
       +
       (** High-level JMAP client with session management. *)

     

       73
       73
       +
       module Client = Client

+35

jmap-eio.opam

···

       1
       1
       +
       # This file is generated by dune, edit dune-project instead

     

       2
       2
       +
       opam-version: "2.0"

     

       3
       3
       +
       synopsis: "JMAP client for Eio"

     

       4
       4
       +
       description:

     

       5
       5
       +
         "High-level JMAP client using Eio for async I/O and the Requests HTTP library."

     

       6
       6
       +
       maintainer: ["Anil Madhavapeddy <anil@recoil.org>"]

     

       7
       7
       +
       authors: ["Anil Madhavapeddy <anil@recoil.org>"]

     

       8
       8
       +
       license: "ISC"

     

       9
       9
       +
       homepage: "https://github.com/avsm/ocaml-jmap"

     

       10
       10
       +
       doc: "https://avsm.github.io/ocaml-jmap"

     

       11
       11
       +
       bug-reports: "https://github.com/avsm/ocaml-jmap/issues"

     

       12
       12
       +
       depends: [

     

       13
       13
       +
         "dune" {>= "3.0"}

     

       14
       14
       +
         "ocaml" {>= "4.14.0"}

     

       15
       15
       +
         "jmap" {= version}

     

       16
       16
       +
         "jsont" {>= "0.2.0"}

     

       17
       17
       +
         "eio"

     

       18
       18
       +
         "requests"

     

       19
       19
       +
         "odoc" {with-doc}

     

       20
       20
       +
       ]

     

       21
       21
       +
       build: [

     

       22
       22
       +
         ["dune" "subst"] {dev}

     

       23
       23
       +
         [

     

       24
       24
       +
           "dune"

     

       25
       25
       +
           "build"

     

       26
       26
       +
           "-p"

     

       27
       27
       +
           name

     

       28
       28
       +
           "-j"

     

       29
       29
       +
           jobs

     

       30
       30
       +
           "@install"

     

       31
       31
       +
           "@runtest" {with-test}

     

       32
       32
       +
           "@doc" {with-doc}

     

       33
       33
       +
         ]

     

       34
       34
       +
       ]

     

       35
       35
       +
       dev-repo: "git+https://github.com/avsm/ocaml-jmap.git"

+13 -11

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"]

     

       3
       3
       +
       synopsis: "JMAP protocol implementation for OCaml"

     

       4
       4
       +
       description:

     

       5
       5
       +
         "A complete implementation of the JSON Meta Application Protocol (JMAP) as specified in RFC 8620 (core) and RFC 8621 (mail)."

     

       6
       6
       +
       maintainer: ["Anil Madhavapeddy <anil@recoil.org>"]

     

       7
       7
       +
       authors: ["Anil Madhavapeddy <anil@recoil.org>"]

     

       7
       8
        
       license: "ISC"

     

       8
       8
       -
       homepage: "https://github.com/avsm/jmap"

     

       9
       9
       -
       bug-reports: "https://github.com/avsm/jmap/issues"

     

       9
       9
       +
       homepage: "https://github.com/avsm/ocaml-jmap"

     

       10
       10
       +
       doc: "https://avsm.github.io/ocaml-jmap"

     

       11
       11
       +
       bug-reports: "https://github.com/avsm/ocaml-jmap/issues"

     

       10
       12
        
       depends: [

     

       11
       11
       -
         "dune" {>= "3.17"}

     

       12
       12
       -
         "ocaml" {>= "5.2.0"}

     

       13
       13
       -
         "ezjsonm"

     

       14
       14
       -
         "ptime"

     

       13
       13
       +
         "dune" {>= "3.0"}

     

       14
       14
       +
         "ocaml" {>= "4.14.0"}

     

       15
       15
       +
         "jsont" {>= "0.2.0"}

     

       16
       16
       +
         "ptime" {>= "1.0.0"}

     

       15
       17
        
         "odoc" {with-doc}

     

       16
       18
        
       ]

     

       17
       19
        
       build: [

     
···

       28
       30
        
           "@doc" {with-doc}

     

       29
       31
        
         ]

     

       30
       32
        
       ]

     

       31
       31
       -
       dev-repo: "git+https://github.com/avsm/jmap.git"

     

       33
       33
       +
       dev-repo: "git+https://github.com/avsm/ocaml-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.

+105

proto/blob.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type upload_response = {

     

       7
       7
       +
         account_id : Id.t;

     

       8
       8
       +
         blob_id : Id.t;

     

       9
       9
       +
         type_ : string;

     

       10
       10
       +
         size : int64;

     

       11
       11
       +
       }

     

       12
       12
       +
       

     

       13
       13
       +
       let upload_response_account_id t = t.account_id

     

       14
       14
       +
       let upload_response_blob_id t = t.blob_id

     

       15
       15
       +
       let upload_response_type t = t.type_

     

       16
       16
       +
       let upload_response_size t = t.size

     

       17
       17
       +
       

     

       18
       18
       +
       let upload_response_make account_id blob_id type_ size =

     

       19
       19
       +
         { account_id; blob_id; type_; size }

     

       20
       20
       +
       

     

       21
       21
       +
       let upload_response_jsont =

     

       22
       22
       +
         let kind = "Upload response" in

     

       23
       23
       +
         Jsont.Object.map ~kind upload_response_make

     

       24
       24
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:upload_response_account_id

     

       25
       25
       +
         |> Jsont.Object.mem "blobId" Id.jsont ~enc:upload_response_blob_id

     

       26
       26
       +
         |> Jsont.Object.mem "type" Jsont.string ~enc:upload_response_type

     

       27
       27
       +
         |> Jsont.Object.mem "size" Int53.Unsigned.jsont ~enc:upload_response_size

     

       28
       28
       +
         |> Jsont.Object.finish

     

       29
       29
       +
       

     

       30
       30
       +
       type download_vars = {

     

       31
       31
       +
         account_id : Id.t;

     

       32
       32
       +
         blob_id : Id.t;

     

       33
       33
       +
         type_ : string;

     

       34
       34
       +
         name : string;

     

       35
       35
       +
       }

     

       36
       36
       +
       

     

       37
       37
       +
       let expand_download_url ~template vars =

     

       38
       38
       +
         let url_encode s =

     

       39
       39
       +
           (* Simple URL encoding *)

     

       40
       40
       +
           let buf = Buffer.create (String.length s * 3) in

     

       41
       41
       +
           String.iter (fun c ->

     

       42
       42
       +
             match c with

     

       43
       43
       +
             | 'A'..'Z' | 'a'..'z' | '0'..'9' | '-' | '_' | '.' | '~' ->

     

       44
       44
       +
               Buffer.add_char buf c

     

       45
       45
       +
             | _ ->

     

       46
       46
       +
               Buffer.add_string buf (Printf.sprintf "%%%02X" (Char.code c))

     

       47
       47
       +
           ) s;

     

       48
       48
       +
           Buffer.contents buf

     

       49
       49
       +
         in

     

       50
       50
       +
         template

     

       51
       51
       +
         |> String.split_on_char '{'

     

       52
       52
       +
         |> List.mapi (fun i part ->

     

       53
       53
       +
           if i = 0 then part

     

       54
       54
       +
           else

     

       55
       55
       +
             match String.index_opt part '}' with

     

       56
       56
       +
             | None -> "{" ^ part

     

       57
       57
       +
             | Some j ->

     

       58
       58
       +
               let var = String.sub part 0 j in

     

       59
       59
       +
               let rest = String.sub part (j + 1) (String.length part - j - 1) in

     

       60
       60
       +
               let value = match var with

     

       61
       61
       +
                 | "accountId" -> url_encode (Id.to_string vars.account_id)

     

       62
       62
       +
                 | "blobId" -> url_encode (Id.to_string vars.blob_id)

     

       63
       63
       +
                 | "type" -> url_encode vars.type_

     

       64
       64
       +
                 | "name" -> url_encode vars.name

     

       65
       65
       +
                 | _ -> "{" ^ var ^ "}"

     

       66
       66
       +
               in

     

       67
       67
       +
               value ^ rest

     

       68
       68
       +
         )

     

       69
       69
       +
         |> String.concat ""

     

       70
       70
       +
       

     

       71
       71
       +
       type copy_args = {

     

       72
       72
       +
         from_account_id : Id.t;

     

       73
       73
       +
         account_id : Id.t;

     

       74
       74
       +
         blob_ids : Id.t list;

     

       75
       75
       +
       }

     

       76
       76
       +
       

     

       77
       77
       +
       let copy_args_make from_account_id account_id blob_ids =

     

       78
       78
       +
         { from_account_id; account_id; blob_ids }

     

       79
       79
       +
       

     

       80
       80
       +
       let copy_args_jsont =

     

       81
       81
       +
         let kind = "Blob/copy args" in

     

       82
       82
       +
         Jsont.Object.map ~kind copy_args_make

     

       83
       83
       +
         |> Jsont.Object.mem "fromAccountId" Id.jsont ~enc:(fun a -> a.from_account_id)

     

       84
       84
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun a -> a.account_id)

     

       85
       85
       +
         |> Jsont.Object.mem "blobIds" (Jsont.list Id.jsont) ~enc:(fun a -> a.blob_ids)

     

       86
       86
       +
         |> Jsont.Object.finish

     

       87
       87
       +
       

     

       88
       88
       +
       type copy_response = {

     

       89
       89
       +
         from_account_id : Id.t;

     

       90
       90
       +
         account_id : Id.t;

     

       91
       91
       +
         copied : (Id.t * Id.t) list option;

     

       92
       92
       +
         not_copied : (Id.t * Error.set_error) list option;

     

       93
       93
       +
       }

     

       94
       94
       +
       

     

       95
       95
       +
       let copy_response_make from_account_id account_id copied not_copied =

     

       96
       96
       +
         { from_account_id; account_id; copied; not_copied }

     

       97
       97
       +
       

     

       98
       98
       +
       let copy_response_jsont =

     

       99
       99
       +
         let kind = "Blob/copy response" in

     

       100
       100
       +
         Jsont.Object.map ~kind copy_response_make

     

       101
       101
       +
         |> Jsont.Object.mem "fromAccountId" Id.jsont ~enc:(fun r -> r.from_account_id)

     

       102
       102
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun r -> r.account_id)

     

       103
       103
       +
         |> Jsont.Object.opt_mem "copied" (Json_map.of_id Id.jsont) ~enc:(fun r -> r.copied)

     

       104
       104
       +
         |> Jsont.Object.opt_mem "notCopied" (Json_map.of_id Error.set_error_jsont) ~enc:(fun r -> r.not_copied)

     

       105
       105
       +
         |> Jsont.Object.finish

+65

proto/blob.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP blob upload/download types as defined in RFC 8620 Section 6 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Upload Response} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** Response from a blob upload. *)

     

       11
       11
       +
       type upload_response = {

     

       12
       12
       +
         account_id : Id.t;

     

       13
       13
       +
         (** The account the blob was uploaded to. *)

     

       14
       14
       +
         blob_id : Id.t;

     

       15
       15
       +
         (** The server-assigned blob id. *)

     

       16
       16
       +
         type_ : string;

     

       17
       17
       +
         (** The media type of the uploaded blob. *)

     

       18
       18
       +
         size : int64;

     

       19
       19
       +
         (** The size in octets. *)

     

       20
       20
       +
       }

     

       21
       21
       +
       

     

       22
       22
       +
       val upload_response_account_id : upload_response -> Id.t

     

       23
       23
       +
       val upload_response_blob_id : upload_response -> Id.t

     

       24
       24
       +
       val upload_response_type : upload_response -> string

     

       25
       25
       +
       val upload_response_size : upload_response -> int64

     

       26
       26
       +
       

     

       27
       27
       +
       val upload_response_jsont : upload_response Jsont.t

     

       28
       28
       +
       

     

       29
       29
       +
       (** {1 Download URL Template} *)

     

       30
       30
       +
       

     

       31
       31
       +
       (** Variables for the download URL template. *)

     

       32
       32
       +
       type download_vars = {

     

       33
       33
       +
         account_id : Id.t;

     

       34
       34
       +
         blob_id : Id.t;

     

       35
       35
       +
         type_ : string;

     

       36
       36
       +
         name : string;

     

       37
       37
       +
       }

     

       38
       38
       +
       

     

       39
       39
       +
       val expand_download_url : template:string -> download_vars -> string

     

       40
       40
       +
       (** [expand_download_url ~template vars] expands the download URL template

     

       41
       41
       +
           with the given variables. Template uses {accountId}, {blobId},

     

       42
       42
       +
           {type}, and {name} placeholders. *)

     

       43
       43
       +
       

     

       44
       44
       +
       (** {1 Blob/copy} *)

     

       45
       45
       +
       

     

       46
       46
       +
       (** Arguments for Blob/copy. *)

     

       47
       47
       +
       type copy_args = {

     

       48
       48
       +
         from_account_id : Id.t;

     

       49
       49
       +
         account_id : Id.t;

     

       50
       50
       +
         blob_ids : Id.t list;

     

       51
       51
       +
       }

     

       52
       52
       +
       

     

       53
       53
       +
       val copy_args_jsont : copy_args Jsont.t

     

       54
       54
       +
       

     

       55
       55
       +
       (** Response for Blob/copy. *)

     

       56
       56
       +
       type copy_response = {

     

       57
       57
       +
         from_account_id : Id.t;

     

       58
       58
       +
         account_id : Id.t;

     

       59
       59
       +
         copied : (Id.t * Id.t) list option;

     

       60
       60
       +
         (** Map of old blob id to new blob id. *)

     

       61
       61
       +
         not_copied : (Id.t * Error.set_error) list option;

     

       62
       62
       +
         (** Blobs that could not be copied. *)

     

       63
       63
       +
       }

     

       64
       64
       +
       

     

       65
       65
       +
       val copy_response_jsont : copy_response Jsont.t

+171

proto/capability.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       let core = "urn:ietf:params:jmap:core"

     

       7
       7
       +
       let mail = "urn:ietf:params:jmap:mail"

     

       8
       8
       +
       let submission = "urn:ietf:params:jmap:submission"

     

       9
       9
       +
       let vacation_response = "urn:ietf:params:jmap:vacationresponse"

     

       10
       10
       +
       

     

       11
       11
       +
       module Core = struct

     

       12
       12
       +
         type t = {

     

       13
       13
       +
           max_size_upload : int64;

     

       14
       14
       +
           max_concurrent_upload : int;

     

       15
       15
       +
           max_size_request : int64;

     

       16
       16
       +
           max_concurrent_requests : int;

     

       17
       17
       +
           max_calls_in_request : int;

     

       18
       18
       +
           max_objects_in_get : int;

     

       19
       19
       +
           max_objects_in_set : int;

     

       20
       20
       +
           collation_algorithms : string list;

     

       21
       21
       +
         }

     

       22
       22
       +
       

     

       23
       23
       +
         let create ~max_size_upload ~max_concurrent_upload ~max_size_request

     

       24
       24
       +
             ~max_concurrent_requests ~max_calls_in_request ~max_objects_in_get

     

       25
       25
       +
             ~max_objects_in_set ~collation_algorithms =

     

       26
       26
       +
           { max_size_upload; max_concurrent_upload; max_size_request;

     

       27
       27
       +
             max_concurrent_requests; max_calls_in_request; max_objects_in_get;

     

       28
       28
       +
             max_objects_in_set; collation_algorithms }

     

       29
       29
       +
       

     

       30
       30
       +
         let max_size_upload t = t.max_size_upload

     

       31
       31
       +
         let max_concurrent_upload t = t.max_concurrent_upload

     

       32
       32
       +
         let max_size_request t = t.max_size_request

     

       33
       33
       +
         let max_concurrent_requests t = t.max_concurrent_requests

     

       34
       34
       +
         let max_calls_in_request t = t.max_calls_in_request

     

       35
       35
       +
         let max_objects_in_get t = t.max_objects_in_get

     

       36
       36
       +
         let max_objects_in_set t = t.max_objects_in_set

     

       37
       37
       +
         let collation_algorithms t = t.collation_algorithms

     

       38
       38
       +
       

     

       39
       39
       +
         let make max_size_upload max_concurrent_upload max_size_request

     

       40
       40
       +
             max_concurrent_requests max_calls_in_request max_objects_in_get

     

       41
       41
       +
             max_objects_in_set collation_algorithms =

     

       42
       42
       +
           { max_size_upload; max_concurrent_upload; max_size_request;

     

       43
       43
       +
             max_concurrent_requests; max_calls_in_request; max_objects_in_get;

     

       44
       44
       +
             max_objects_in_set; collation_algorithms }

     

       45
       45
       +
       

     

       46
       46
       +
         let jsont =

     

       47
       47
       +
           let kind = "Core capability" in

     

       48
       48
       +
           Jsont.Object.map ~kind make

     

       49
       49
       +
           |> Jsont.Object.mem "maxSizeUpload" Int53.Unsigned.jsont ~enc:max_size_upload

     

       50
       50
       +
           |> Jsont.Object.mem "maxConcurrentUpload" Jsont.int ~enc:max_concurrent_upload

     

       51
       51
       +
           |> Jsont.Object.mem "maxSizeRequest" Int53.Unsigned.jsont ~enc:max_size_request

     

       52
       52
       +
           |> Jsont.Object.mem "maxConcurrentRequests" Jsont.int ~enc:max_concurrent_requests

     

       53
       53
       +
           |> Jsont.Object.mem "maxCallsInRequest" Jsont.int ~enc:max_calls_in_request

     

       54
       54
       +
           |> Jsont.Object.mem "maxObjectsInGet" Jsont.int ~enc:max_objects_in_get

     

       55
       55
       +
           |> Jsont.Object.mem "maxObjectsInSet" Jsont.int ~enc:max_objects_in_set

     

       56
       56
       +
           |> Jsont.Object.mem "collationAlgorithms" (Jsont.list Jsont.string) ~enc:collation_algorithms

     

       57
       57
       +
           |> Jsont.Object.finish

     

       58
       58
       +
       end

     

       59
       59
       +
       

     

       60
       60
       +
       module Mail = struct

     

       61
       61
       +
         type t = {

     

       62
       62
       +
           max_mailboxes_per_email : int64 option;

     

       63
       63
       +
           max_mailbox_depth : int64 option;

     

       64
       64
       +
           max_size_mailbox_name : int64;

     

       65
       65
       +
           max_size_attachments_per_email : int64;

     

       66
       66
       +
           email_query_sort_options : string list;

     

       67
       67
       +
           may_create_top_level_mailbox : bool;

     

       68
       68
       +
         }

     

       69
       69
       +
       

     

       70
       70
       +
         let create ?max_mailboxes_per_email ?max_mailbox_depth ~max_size_mailbox_name

     

       71
       71
       +
             ~max_size_attachments_per_email ~email_query_sort_options

     

       72
       72
       +
             ~may_create_top_level_mailbox () =

     

       73
       73
       +
           { max_mailboxes_per_email; max_mailbox_depth; max_size_mailbox_name;

     

       74
       74
       +
             max_size_attachments_per_email; email_query_sort_options;

     

       75
       75
       +
             may_create_top_level_mailbox }

     

       76
       76
       +
       

     

       77
       77
       +
         let max_mailboxes_per_email t = t.max_mailboxes_per_email

     

       78
       78
       +
         let max_mailbox_depth t = t.max_mailbox_depth

     

       79
       79
       +
         let max_size_mailbox_name t = t.max_size_mailbox_name

     

       80
       80
       +
         let max_size_attachments_per_email t = t.max_size_attachments_per_email

     

       81
       81
       +
         let email_query_sort_options t = t.email_query_sort_options

     

       82
       82
       +
         let may_create_top_level_mailbox t = t.may_create_top_level_mailbox

     

       83
       83
       +
       

     

       84
       84
       +
         let make max_mailboxes_per_email max_mailbox_depth max_size_mailbox_name

     

       85
       85
       +
             max_size_attachments_per_email email_query_sort_options

     

       86
       86
       +
             may_create_top_level_mailbox =

     

       87
       87
       +
           { max_mailboxes_per_email; max_mailbox_depth; max_size_mailbox_name;

     

       88
       88
       +
             max_size_attachments_per_email; email_query_sort_options;

     

       89
       89
       +
             may_create_top_level_mailbox }

     

       90
       90
       +
       

     

       91
       91
       +
         let jsont =

     

       92
       92
       +
           let kind = "Mail capability" in

     

       93
       93
       +
           Jsont.Object.map ~kind make

     

       94
       94
       +
           |> Jsont.Object.opt_mem "maxMailboxesPerEmail" Int53.Unsigned.jsont ~enc:max_mailboxes_per_email

     

       95
       95
       +
           |> Jsont.Object.opt_mem "maxMailboxDepth" Int53.Unsigned.jsont ~enc:max_mailbox_depth

     

       96
       96
       +
           |> Jsont.Object.mem "maxSizeMailboxName" Int53.Unsigned.jsont ~enc:max_size_mailbox_name

     

       97
       97
       +
           |> Jsont.Object.mem "maxSizeAttachmentsPerEmail" Int53.Unsigned.jsont ~enc:max_size_attachments_per_email

     

       98
       98
       +
           |> Jsont.Object.mem "emailQuerySortOptions" (Jsont.list Jsont.string) ~enc:email_query_sort_options

     

       99
       99
       +
           |> Jsont.Object.mem "mayCreateTopLevelMailbox" Jsont.bool ~enc:may_create_top_level_mailbox

     

       100
       100
       +
           |> Jsont.Object.finish

     

       101
       101
       +
       end

     

       102
       102
       +
       

     

       103
       103
       +
       module Submission = struct

     

       104
       104
       +
         type t = {

     

       105
       105
       +
           max_delayed_send : int64;

     

       106
       106
       +
           submission_extensions : (string * string list) list;

     

       107
       107
       +
         }

     

       108
       108
       +
       

     

       109
       109
       +
         let create ~max_delayed_send ~submission_extensions =

     

       110
       110
       +
           { max_delayed_send; submission_extensions }

     

       111
       111
       +
       

     

       112
       112
       +
         let max_delayed_send t = t.max_delayed_send

     

       113
       113
       +
         let submission_extensions t = t.submission_extensions

     

       114
       114
       +
       

     

       115
       115
       +
         let make max_delayed_send submission_extensions =

     

       116
       116
       +
           { max_delayed_send; submission_extensions }

     

       117
       117
       +
       

     

       118
       118
       +
         let submission_extensions_jsont =

     

       119
       119
       +
           Json_map.of_string (Jsont.list Jsont.string)

     

       120
       120
       +
       

     

       121
       121
       +
         let jsont =

     

       122
       122
       +
           let kind = "Submission capability" in

     

       123
       123
       +
           Jsont.Object.map ~kind make

     

       124
       124
       +
           |> Jsont.Object.mem "maxDelayedSend" Int53.Unsigned.jsont ~enc:max_delayed_send

     

       125
       125
       +
           |> Jsont.Object.mem "submissionExtensions" submission_extensions_jsont ~enc:submission_extensions

     

       126
       126
       +
           |> Jsont.Object.finish

     

       127
       127
       +
       end

     

       128
       128
       +
       

     

       129
       129
       +
       type capability =

     

       130
       130
       +
         | Core of Core.t

     

       131
       131
       +
         | Mail of Mail.t

     

       132
       132
       +
         | Submission of Submission.t

     

       133
       133
       +
         | Vacation_response

     

       134
       134
       +
         | Unknown of Jsont.json

     

       135
       135
       +
       

     

       136
       136
       +
       let capability_of_json uri json =

     

       137
       137
       +
         match uri with

     

       138
       138
       +
         | u when u = core ->

     

       139
       139
       +
           (match Jsont.Json.decode' Core.jsont json with

     

       140
       140
       +
            | Ok c -> Core c

     

       141
       141
       +
            | Error _ -> Unknown json)

     

       142
       142
       +
         | u when u = mail ->

     

       143
       143
       +
           (match Jsont.Json.decode' Mail.jsont json with

     

       144
       144
       +
            | Ok m -> Mail m

     

       145
       145
       +
            | Error _ -> Unknown json)

     

       146
       146
       +
         | u when u = submission ->

     

       147
       147
       +
           (match Jsont.Json.decode' Submission.jsont json with

     

       148
       148
       +
            | Ok s -> Submission s

     

       149
       149
       +
            | Error _ -> Unknown json)

     

       150
       150
       +
         | u when u = vacation_response ->

     

       151
       151
       +
           Vacation_response

     

       152
       152
       +
         | _ ->

     

       153
       153
       +
           Unknown json

     

       154
       154
       +
       

     

       155
       155
       +
       let capability_to_json (uri, cap) =

     

       156
       156
       +
         let encode jsont v =

     

       157
       157
       +
           match Jsont.Json.encode' jsont v with

     

       158
       158
       +
           | Ok json -> json

     

       159
       159
       +
           | Error _ -> Jsont.Object ([], Jsont.Meta.none)

     

       160
       160
       +
         in

     

       161
       161
       +
         match cap with

     

       162
       162
       +
         | Core c ->

     

       163
       163
       +
           (uri, encode Core.jsont c)

     

       164
       164
       +
         | Mail m ->

     

       165
       165
       +
           (uri, encode Mail.jsont m)

     

       166
       166
       +
         | Submission s ->

     

       167
       167
       +
           (uri, encode Submission.jsont s)

     

       168
       168
       +
         | Vacation_response ->

     

       169
       169
       +
           (uri, Jsont.Object ([], Jsont.Meta.none))

     

       170
       170
       +
         | Unknown json ->

     

       171
       171
       +
           (uri, json)

+143

proto/capability.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP capability types as defined in RFC 8620 Section 2 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Standard Capability URIs} *)

     

       9
       9
       +
       

     

       10
       10
       +
       val core : string

     

       11
       11
       +
       (** [urn:ietf:params:jmap:core] - Core JMAP capability (RFC 8620) *)

     

       12
       12
       +
       

     

       13
       13
       +
       val mail : string

     

       14
       14
       +
       (** [urn:ietf:params:jmap:mail] - Mail capability (RFC 8621) *)

     

       15
       15
       +
       

     

       16
       16
       +
       val submission : string

     

       17
       17
       +
       (** [urn:ietf:params:jmap:submission] - Email submission capability (RFC 8621) *)

     

       18
       18
       +
       

     

       19
       19
       +
       val vacation_response : string

     

       20
       20
       +
       (** [urn:ietf:params:jmap:vacationresponse] - Vacation response capability (RFC 8621) *)

     

       21
       21
       +
       

     

       22
       22
       +
       (** {1 Core Capability Object} *)

     

       23
       23
       +
       

     

       24
       24
       +
       (** Core capability limits and configuration per RFC 8620 Section 2. *)

     

       25
       25
       +
       module Core : sig

     

       26
       26
       +
         type t = {

     

       27
       27
       +
           max_size_upload : int64;

     

       28
       28
       +
           (** Maximum size in octets for a single blob upload. *)

     

       29
       29
       +
           max_concurrent_upload : int;

     

       30
       30
       +
           (** Maximum number of concurrent upload requests. *)

     

       31
       31
       +
           max_size_request : int64;

     

       32
       32
       +
           (** Maximum size in octets of a single request. *)

     

       33
       33
       +
           max_concurrent_requests : int;

     

       34
       34
       +
           (** Maximum number of concurrent requests. *)

     

       35
       35
       +
           max_calls_in_request : int;

     

       36
       36
       +
           (** Maximum number of method calls in a single request. *)

     

       37
       37
       +
           max_objects_in_get : int;

     

       38
       38
       +
           (** Maximum number of objects in a single /get request. *)

     

       39
       39
       +
           max_objects_in_set : int;

     

       40
       40
       +
           (** Maximum number of objects in a single /set request. *)

     

       41
       41
       +
           collation_algorithms : string list;

     

       42
       42
       +
           (** Supported collation algorithms for sorting. *)

     

       43
       43
       +
         }

     

       44
       44
       +
       

     

       45
       45
       +
         val create :

     

       46
       46
       +
           max_size_upload:int64 ->

     

       47
       47
       +
           max_concurrent_upload:int ->

     

       48
       48
       +
           max_size_request:int64 ->

     

       49
       49
       +
           max_concurrent_requests:int ->

     

       50
       50
       +
           max_calls_in_request:int ->

     

       51
       51
       +
           max_objects_in_get:int ->

     

       52
       52
       +
           max_objects_in_set:int ->

     

       53
       53
       +
           collation_algorithms:string list ->

     

       54
       54
       +
           t

     

       55
       55
       +
       

     

       56
       56
       +
         val max_size_upload : t -> int64

     

       57
       57
       +
         val max_concurrent_upload : t -> int

     

       58
       58
       +
         val max_size_request : t -> int64

     

       59
       59
       +
         val max_concurrent_requests : t -> int

     

       60
       60
       +
         val max_calls_in_request : t -> int

     

       61
       61
       +
         val max_objects_in_get : t -> int

     

       62
       62
       +
         val max_objects_in_set : t -> int

     

       63
       63
       +
         val collation_algorithms : t -> string list

     

       64
       64
       +
       

     

       65
       65
       +
         val jsont : t Jsont.t

     

       66
       66
       +
         (** JSON codec for core capability. *)

     

       67
       67
       +
       end

     

       68
       68
       +
       

     

       69
       69
       +
       (** {1 Mail Capability Object} *)

     

       70
       70
       +
       

     

       71
       71
       +
       (** Mail capability configuration per RFC 8621. *)

     

       72
       72
       +
       module Mail : sig

     

       73
       73
       +
         type t = {

     

       74
       74
       +
           max_mailboxes_per_email : int64 option;

     

       75
       75
       +
           (** Maximum number of mailboxes an email can belong to. *)

     

       76
       76
       +
           max_mailbox_depth : int64 option;

     

       77
       77
       +
           (** Maximum depth of mailbox hierarchy. *)

     

       78
       78
       +
           max_size_mailbox_name : int64;

     

       79
       79
       +
           (** Maximum size of a mailbox name in octets. *)

     

       80
       80
       +
           max_size_attachments_per_email : int64;

     

       81
       81
       +
           (** Maximum total size of attachments per email. *)

     

       82
       82
       +
           email_query_sort_options : string list;

     

       83
       83
       +
           (** Supported sort options for Email/query. *)

     

       84
       84
       +
           may_create_top_level_mailbox : bool;

     

       85
       85
       +
           (** Whether the user may create top-level mailboxes. *)

     

       86
       86
       +
         }

     

       87
       87
       +
       

     

       88
       88
       +
         val create :

     

       89
       89
       +
           ?max_mailboxes_per_email:int64 ->

     

       90
       90
       +
           ?max_mailbox_depth:int64 ->

     

       91
       91
       +
           max_size_mailbox_name:int64 ->

     

       92
       92
       +
           max_size_attachments_per_email:int64 ->

     

       93
       93
       +
           email_query_sort_options:string list ->

     

       94
       94
       +
           may_create_top_level_mailbox:bool ->

     

       95
       95
       +
           unit ->

     

       96
       96
       +
           t

     

       97
       97
       +
       

     

       98
       98
       +
         val max_mailboxes_per_email : t -> int64 option

     

       99
       99
       +
         val max_mailbox_depth : t -> int64 option

     

       100
       100
       +
         val max_size_mailbox_name : t -> int64

     

       101
       101
       +
         val max_size_attachments_per_email : t -> int64

     

       102
       102
       +
         val email_query_sort_options : t -> string list

     

       103
       103
       +
         val may_create_top_level_mailbox : t -> bool

     

       104
       104
       +
       

     

       105
       105
       +
         val jsont : t Jsont.t

     

       106
       106
       +
       end

     

       107
       107
       +
       

     

       108
       108
       +
       (** {1 Submission Capability Object} *)

     

       109
       109
       +
       

     

       110
       110
       +
       module Submission : sig

     

       111
       111
       +
         type t = {

     

       112
       112
       +
           max_delayed_send : int64;

     

       113
       113
       +
           (** Maximum delay in seconds for delayed sending (0 = not supported). *)

     

       114
       114
       +
           submission_extensions : (string * string list) list;

     

       115
       115
       +
           (** SMTP extensions supported. *)

     

       116
       116
       +
         }

     

       117
       117
       +
       

     

       118
       118
       +
         val create :

     

       119
       119
       +
           max_delayed_send:int64 ->

     

       120
       120
       +
           submission_extensions:(string * string list) list ->

     

       121
       121
       +
           t

     

       122
       122
       +
       

     

       123
       123
       +
         val max_delayed_send : t -> int64

     

       124
       124
       +
         val submission_extensions : t -> (string * string list) list

     

       125
       125
       +
       

     

       126
       126
       +
         val jsont : t Jsont.t

     

       127
       127
       +
       end

     

       128
       128
       +
       

     

       129
       129
       +
       (** {1 Generic Capability Handling} *)

     

       130
       130
       +
       

     

       131
       131
       +
       (** A capability value that can be either a known type or unknown JSON. *)

     

       132
       132
       +
       type capability =

     

       133
       133
       +
         | Core of Core.t

     

       134
       134
       +
         | Mail of Mail.t

     

       135
       135
       +
         | Submission of Submission.t

     

       136
       136
       +
         | Vacation_response  (* No configuration *)

     

       137
       137
       +
         | Unknown of Jsont.json

     

       138
       138
       +
       

     

       139
       139
       +
       val capability_of_json : string -> Jsont.json -> capability

     

       140
       140
       +
       (** [capability_of_json uri json] parses a capability from its URI and JSON value. *)

     

       141
       141
       +
       

     

       142
       142
       +
       val capability_to_json : string * capability -> string * Jsont.json

     

       143
       143
       +
       (** [capability_to_json (uri, cap)] encodes a capability to URI and JSON. *)

+64

proto/date.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Date and time types for JMAP.

     

       7
       7
       +
       

     

       8
       8
       +
           JMAP uses RFC 3339 formatted date-time strings. *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** RFC 3339 date-time with any timezone offset *)

     

       11
       11
       +
       module Rfc3339 = struct

     

       12
       12
       +
         type t = Ptime.t

     

       13
       13
       +
       

     

       14
       14
       +
         let of_string s =

     

       15
       15
       +
           match Ptime.of_rfc3339 s with

     

       16
       16
       +
           | Ok (t, _, _) -> Ok t

     

       17
       17
       +
           | Error _ -> Error (Printf.sprintf "Invalid RFC 3339 date: %s" s)

     

       18
       18
       +
       

     

       19
       19
       +
         let to_string t =

     

       20
       20
       +
           (* Format with 'T' separator and timezone offset *)

     

       21
       21
       +
           Ptime.to_rfc3339 ~tz_offset_s:0 t

     

       22
       22
       +
       

     

       23
       23
       +
         let jsont =

     

       24
       24
       +
           let kind = "Date" in

     

       25
       25
       +
           let dec s =

     

       26
       26
       +
             match of_string s with

     

       27
       27
       +
             | Ok t -> t

     

       28
       28
       +
             | Error msg -> Jsont.Error.msgf Jsont.Meta.none "%s: %s" kind msg

     

       29
       29
       +
           in

     

       30
       30
       +
           let enc = to_string in

     

       31
       31
       +
           Jsont.map ~kind ~dec ~enc Jsont.string

     

       32
       32
       +
       end

     

       33
       33
       +
       

     

       34
       34
       +
       (** UTC date-time (must use 'Z' timezone suffix) *)

     

       35
       35
       +
       module Utc = struct

     

       36
       36
       +
         type t = Ptime.t

     

       37
       37
       +
       

     

       38
       38
       +
         let of_string s =

     

       39
       39
       +
           (* Must end with 'Z' for UTC *)

     

       40
       40
       +
           let len = String.length s in

     

       41
       41
       +
           if len > 0 && s.[len - 1] <> 'Z' then

     

       42
       42
       +
             Error "UTCDate must use 'Z' timezone suffix"

     

       43
       43
       +
           else

     

       44
       44
       +
             match Ptime.of_rfc3339 s with

     

       45
       45
       +
             | Ok (t, _, _) -> Ok t

     

       46
       46
       +
             | Error _ -> Error (Printf.sprintf "Invalid RFC 3339 UTC date: %s" s)

     

       47
       47
       +
       

     

       48
       48
       +
         let to_string t =

     

       49
       49
       +
           (* Always format with 'Z' suffix *)

     

       50
       50
       +
           Ptime.to_rfc3339 ~tz_offset_s:0 t

     

       51
       51
       +
       

     

       52
       52
       +
         let of_ptime t = t

     

       53
       53
       +
         let to_ptime t = t

     

       54
       54
       +
       

     

       55
       55
       +
         let jsont =

     

       56
       56
       +
           let kind = "UTCDate" in

     

       57
       57
       +
           let dec s =

     

       58
       58
       +
             match of_string s with

     

       59
       59
       +
             | Ok t -> t

     

       60
       60
       +
             | Error msg -> Jsont.Error.msgf Jsont.Meta.none "%s: %s" kind msg

     

       61
       61
       +
           in

     

       62
       62
       +
           let enc = to_string in

     

       63
       63
       +
           Jsont.map ~kind ~dec ~enc Jsont.string

     

       64
       64
       +
       end

+51

proto/date.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Date and time types for JMAP.

     

       7
       7
       +
       

     

       8
       8
       +
           JMAP uses RFC 3339 formatted date-time strings.

     

       9
       9
       +
       

     

       10
       10
       +
           See {{:https://datatracker.ietf.org/doc/html/rfc8620#section-1.4} RFC 8620 Section 1.4}. *)

     

       11
       11
       +
       

     

       12
       12
       +
       (** RFC 3339 date-time.

     

       13
       13
       +
       

     

       14
       14
       +
           A date-time string with uppercase 'T' separator. May have any timezone. *)

     

       15
       15
       +
       module Rfc3339 : sig

     

       16
       16
       +
         type t = Ptime.t

     

       17
       17
       +
         (** The type of dates. *)

     

       18
       18
       +
       

     

       19
       19
       +
         val of_string : string -> (t, string) result

     

       20
       20
       +
         (** [of_string s] parses an RFC 3339 date-time string. *)

     

       21
       21
       +
       

     

       22
       22
       +
         val to_string : t -> string

     

       23
       23
       +
         (** [to_string d] formats [d] as an RFC 3339 string. *)

     

       24
       24
       +
       

     

       25
       25
       +
         val jsont : t Jsont.t

     

       26
       26
       +
         (** JSON codec for RFC 3339 dates. *)

     

       27
       27
       +
       end

     

       28
       28
       +
       

     

       29
       29
       +
       (** UTC date-time.

     

       30
       30
       +
       

     

       31
       31
       +
           A date-time string that MUST have 'Z' as the timezone (UTC only). *)

     

       32
       32
       +
       module Utc : sig

     

       33
       33
       +
         type t = Ptime.t

     

       34
       34
       +
         (** The type of UTC dates. *)

     

       35
       35
       +
       

     

       36
       36
       +
         val of_string : string -> (t, string) result

     

       37
       37
       +
         (** [of_string s] parses an RFC 3339 UTC date-time string.

     

       38
       38
       +
             Returns error if timezone is not 'Z'. *)

     

       39
       39
       +
       

     

       40
       40
       +
         val to_string : t -> string

     

       41
       41
       +
         (** [to_string d] formats [d] as an RFC 3339 UTC string with 'Z'. *)

     

       42
       42
       +
       

     

       43
       43
       +
         val of_ptime : Ptime.t -> t

     

       44
       44
       +
         (** [of_ptime p] creates a UTC date from a Ptime value. *)

     

       45
       45
       +
       

     

       46
       46
       +
         val to_ptime : t -> Ptime.t

     

       47
       47
       +
         (** [to_ptime d] returns the underlying Ptime value. *)

     

       48
       48
       +
       

     

       49
       49
       +
         val jsont : t Jsont.t

     

       50
       50
       +
         (** JSON codec for UTC dates. *)

     

       51
       51
       +
       end

+21

proto/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name jmap_proto)

     

       3
       3
       +
        (public_name jmap)

     

       4
       4
       +
        (libraries jsont ptime)

     

       5
       5
       +
        (modules

     

       6
       6
       +
         jmap_proto

     

       7
       7
       +
         id

     

       8
       8
       +
         int53

     

       9
       9
       +
         date

     

       10
       10
       +
         json_map

     

       11
       11
       +
         unknown

     

       12
       12
       +
         error

     

       13
       13
       +
         capability

     

       14
       14
       +
         filter

     

       15
       15
       +
         method_

     

       16
       16
       +
         invocation

     

       17
       17
       +
         request

     

       18
       18
       +
         response

     

       19
       19
       +
         session

     

       20
       20
       +
         push

     

       21
       21
       +
         blob))

+190

proto/error.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       module Request_error = struct

     

       7
       7
       +
         type urn =

     

       8
       8
       +
           | Unknown_capability

     

       9
       9
       +
           | Not_json

     

       10
       10
       +
           | Not_request

     

       11
       11
       +
           | Limit

     

       12
       12
       +
           | Other of string

     

       13
       13
       +
       

     

       14
       14
       +
         let urn_to_string = function

     

       15
       15
       +
           | Unknown_capability -> "urn:ietf:params:jmap:error:unknownCapability"

     

       16
       16
       +
           | Not_json -> "urn:ietf:params:jmap:error:notJSON"

     

       17
       17
       +
           | Not_request -> "urn:ietf:params:jmap:error:notRequest"

     

       18
       18
       +
           | Limit -> "urn:ietf:params:jmap:error:limit"

     

       19
       19
       +
           | Other s -> s

     

       20
       20
       +
       

     

       21
       21
       +
         let urn_of_string = function

     

       22
       22
       +
           | "urn:ietf:params:jmap:error:unknownCapability" -> Unknown_capability

     

       23
       23
       +
           | "urn:ietf:params:jmap:error:notJSON" -> Not_json

     

       24
       24
       +
           | "urn:ietf:params:jmap:error:notRequest" -> Not_request

     

       25
       25
       +
           | "urn:ietf:params:jmap:error:limit" -> Limit

     

       26
       26
       +
           | s -> Other s

     

       27
       27
       +
       

     

       28
       28
       +
         let urn_jsont =

     

       29
       29
       +
           let kind = "Request error URN" in

     

       30
       30
       +
           Jsont.map ~kind

     

       31
       31
       +
             ~dec:(fun s -> urn_of_string s)

     

       32
       32
       +
             ~enc:urn_to_string

     

       33
       33
       +
             Jsont.string

     

       34
       34
       +
       

     

       35
       35
       +
         type t = {

     

       36
       36
       +
           type_ : urn;

     

       37
       37
       +
           status : int;

     

       38
       38
       +
           title : string option;

     

       39
       39
       +
           detail : string option;

     

       40
       40
       +
           limit : string option;

     

       41
       41
       +
         }

     

       42
       42
       +
       

     

       43
       43
       +
         let make type_ status title detail limit =

     

       44
       44
       +
           { type_; status; title; detail; limit }

     

       45
       45
       +
       

     

       46
       46
       +
         let type_ t = t.type_

     

       47
       47
       +
         let status t = t.status

     

       48
       48
       +
         let title t = t.title

     

       49
       49
       +
         let detail t = t.detail

     

       50
       50
       +
         let limit t = t.limit

     

       51
       51
       +
       

     

       52
       52
       +
         let jsont =

     

       53
       53
       +
           let kind = "Request error" in

     

       54
       54
       +
           Jsont.Object.map ~kind make

     

       55
       55
       +
           |> Jsont.Object.mem "type" urn_jsont ~enc:type_

     

       56
       56
       +
           |> Jsont.Object.mem "status" Jsont.int ~enc:status

     

       57
       57
       +
           |> Jsont.Object.opt_mem "title" Jsont.string ~enc:title

     

       58
       58
       +
           |> Jsont.Object.opt_mem "detail" Jsont.string ~enc:detail

     

       59
       59
       +
           |> Jsont.Object.opt_mem "limit" Jsont.string ~enc:limit

     

       60
       60
       +
           |> Jsont.Object.finish

     

       61
       61
       +
       end

     

       62
       62
       +
       

     

       63
       63
       +
       type method_error_type =

     

       64
       64
       +
         | Server_unavailable

     

       65
       65
       +
         | Server_fail

     

       66
       66
       +
         | Server_partial_fail

     

       67
       67
       +
         | Unknown_method

     

       68
       68
       +
         | Invalid_arguments

     

       69
       69
       +
         | Invalid_result_reference

     

       70
       70
       +
         | Forbidden

     

       71
       71
       +
         | Account_not_found

     

       72
       72
       +
         | Account_not_supported_by_method

     

       73
       73
       +
         | Account_read_only

     

       74
       74
       +
         | Other of string

     

       75
       75
       +
       

     

       76
       76
       +
       let method_error_type_to_string = function

     

       77
       77
       +
         | Server_unavailable -> "serverUnavailable"

     

       78
       78
       +
         | Server_fail -> "serverFail"

     

       79
       79
       +
         | Server_partial_fail -> "serverPartialFail"

     

       80
       80
       +
         | Unknown_method -> "unknownMethod"

     

       81
       81
       +
         | Invalid_arguments -> "invalidArguments"

     

       82
       82
       +
         | Invalid_result_reference -> "invalidResultReference"

     

       83
       83
       +
         | Forbidden -> "forbidden"

     

       84
       84
       +
         | Account_not_found -> "accountNotFound"

     

       85
       85
       +
         | Account_not_supported_by_method -> "accountNotSupportedByMethod"

     

       86
       86
       +
         | Account_read_only -> "accountReadOnly"

     

       87
       87
       +
         | Other s -> s

     

       88
       88
       +
       

     

       89
       89
       +
       let method_error_type_of_string = function

     

       90
       90
       +
         | "serverUnavailable" -> Server_unavailable

     

       91
       91
       +
         | "serverFail" -> Server_fail

     

       92
       92
       +
         | "serverPartialFail" -> Server_partial_fail

     

       93
       93
       +
         | "unknownMethod" -> Unknown_method

     

       94
       94
       +
         | "invalidArguments" -> Invalid_arguments

     

       95
       95
       +
         | "invalidResultReference" -> Invalid_result_reference

     

       96
       96
       +
         | "forbidden" -> Forbidden

     

       97
       97
       +
         | "accountNotFound" -> Account_not_found

     

       98
       98
       +
         | "accountNotSupportedByMethod" -> Account_not_supported_by_method

     

       99
       99
       +
         | "accountReadOnly" -> Account_read_only

     

       100
       100
       +
         | s -> Other s

     

       101
       101
       +
       

     

       102
       102
       +
       let method_error_type_jsont =

     

       103
       103
       +
         let kind = "Method error type" in

     

       104
       104
       +
         Jsont.map ~kind

     

       105
       105
       +
           ~dec:(fun s -> method_error_type_of_string s)

     

       106
       106
       +
           ~enc:method_error_type_to_string

     

       107
       107
       +
           Jsont.string

     

       108
       108
       +
       

     

       109
       109
       +
       type method_error = {

     

       110
       110
       +
         type_ : method_error_type;

     

       111
       111
       +
         description : string option;

     

       112
       112
       +
       }

     

       113
       113
       +
       

     

       114
       114
       +
       let method_error_make type_ description = { type_; description }

     

       115
       115
       +
       let method_error_type_ t = t.type_

     

       116
       116
       +
       let method_error_description t = t.description

     

       117
       117
       +
       

     

       118
       118
       +
       let method_error_jsont =

     

       119
       119
       +
         let kind = "Method error" in

     

       120
       120
       +
         Jsont.Object.map ~kind method_error_make

     

       121
       121
       +
         |> Jsont.Object.mem "type" method_error_type_jsont ~enc:method_error_type_

     

       122
       122
       +
         |> Jsont.Object.opt_mem "description" Jsont.string ~enc:method_error_description

     

       123
       123
       +
         |> Jsont.Object.finish

     

       124
       124
       +
       

     

       125
       125
       +
       type set_error_type =

     

       126
       126
       +
         | Forbidden

     

       127
       127
       +
         | Over_quota

     

       128
       128
       +
         | Too_large

     

       129
       129
       +
         | Rate_limit

     

       130
       130
       +
         | Not_found

     

       131
       131
       +
         | Invalid_patch

     

       132
       132
       +
         | Will_destroy

     

       133
       133
       +
         | Invalid_properties

     

       134
       134
       +
         | Singleton

     

       135
       135
       +
         | Other of string

     

       136
       136
       +
       

     

       137
       137
       +
       let set_error_type_to_string = function

     

       138
       138
       +
         | Forbidden -> "forbidden"

     

       139
       139
       +
         | Over_quota -> "overQuota"

     

       140
       140
       +
         | Too_large -> "tooLarge"

     

       141
       141
       +
         | Rate_limit -> "rateLimit"

     

       142
       142
       +
         | Not_found -> "notFound"

     

       143
       143
       +
         | Invalid_patch -> "invalidPatch"

     

       144
       144
       +
         | Will_destroy -> "willDestroy"

     

       145
       145
       +
         | Invalid_properties -> "invalidProperties"

     

       146
       146
       +
         | Singleton -> "singleton"

     

       147
       147
       +
         | Other s -> s

     

       148
       148
       +
       

     

       149
       149
       +
       let set_error_type_of_string = function

     

       150
       150
       +
         | "forbidden" -> Forbidden

     

       151
       151
       +
         | "overQuota" -> Over_quota

     

       152
       152
       +
         | "tooLarge" -> Too_large

     

       153
       153
       +
         | "rateLimit" -> Rate_limit

     

       154
       154
       +
         | "notFound" -> Not_found

     

       155
       155
       +
         | "invalidPatch" -> Invalid_patch

     

       156
       156
       +
         | "willDestroy" -> Will_destroy

     

       157
       157
       +
         | "invalidProperties" -> Invalid_properties

     

       158
       158
       +
         | "singleton" -> Singleton

     

       159
       159
       +
         | s -> Other s

     

       160
       160
       +
       

     

       161
       161
       +
       let set_error_type_jsont =

     

       162
       162
       +
         let kind = "SetError type" in

     

       163
       163
       +
         Jsont.map ~kind

     

       164
       164
       +
           ~dec:(fun s -> set_error_type_of_string s)

     

       165
       165
       +
           ~enc:set_error_type_to_string

     

       166
       166
       +
           Jsont.string

     

       167
       167
       +
       

     

       168
       168
       +
       type set_error = {

     

       169
       169
       +
         type_ : set_error_type;

     

       170
       170
       +
         description : string option;

     

       171
       171
       +
         properties : string list option;

     

       172
       172
       +
       }

     

       173
       173
       +
       

     

       174
       174
       +
       let set_error ?description ?properties type_ =

     

       175
       175
       +
         { type_; description; properties }

     

       176
       176
       +
       

     

       177
       177
       +
       let set_error_make type_ description properties =

     

       178
       178
       +
         { type_; description; properties }

     

       179
       179
       +
       

     

       180
       180
       +
       let set_error_type_ t = t.type_

     

       181
       181
       +
       let set_error_description t = t.description

     

       182
       182
       +
       let set_error_properties t = t.properties

     

       183
       183
       +
       

     

       184
       184
       +
       let set_error_jsont =

     

       185
       185
       +
         let kind = "SetError" in

     

       186
       186
       +
         Jsont.Object.map ~kind set_error_make

     

       187
       187
       +
         |> Jsont.Object.mem "type" set_error_type_jsont ~enc:set_error_type_

     

       188
       188
       +
         |> Jsont.Object.opt_mem "description" Jsont.string ~enc:set_error_description

     

       189
       189
       +
         |> Jsont.Object.opt_mem "properties" (Jsont.list Jsont.string) ~enc:set_error_properties

     

       190
       190
       +
         |> Jsont.Object.finish

+146

proto/error.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP error types as defined in RFC 8620 Section 3.6.1-3.6.2 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Request-Level Errors}

     

       9
       9
       +
       

     

       10
       10
       +
           These errors are returned with an HTTP error status code and a JSON

     

       11
       11
       +
           Problem Details body (RFC 7807). *)

     

       12
       12
       +
       

     

       13
       13
       +
       (** Request-level error URNs *)

     

       14
       14
       +
       module Request_error : sig

     

       15
       15
       +
         type urn =

     

       16
       16
       +
           | Unknown_capability

     

       17
       17
       +
           (** urn:ietf:params:jmap:error:unknownCapability

     

       18
       18
       +
               The client included a capability in "using" that the server does not support. *)

     

       19
       19
       +
           | Not_json

     

       20
       20
       +
           (** urn:ietf:params:jmap:error:notJSON

     

       21
       21
       +
               The content type was not application/json or the request was not valid JSON. *)

     

       22
       22
       +
           | Not_request

     

       23
       23
       +
           (** urn:ietf:params:jmap:error:notRequest

     

       24
       24
       +
               The request was valid JSON but not a valid JMAP Request object. *)

     

       25
       25
       +
           | Limit

     

       26
       26
       +
           (** urn:ietf:params:jmap:error:limit

     

       27
       27
       +
               A server-defined limit was reached. *)

     

       28
       28
       +
           | Other of string

     

       29
       29
       +
           (** Other URN not in the standard set. *)

     

       30
       30
       +
       

     

       31
       31
       +
         val urn_to_string : urn -> string

     

       32
       32
       +
         (** [urn_to_string urn] returns the URN string. *)

     

       33
       33
       +
       

     

       34
       34
       +
         val urn_of_string : string -> urn

     

       35
       35
       +
         (** [urn_of_string s] parses a URN string. *)

     

       36
       36
       +
       

     

       37
       37
       +
         type t = {

     

       38
       38
       +
           type_ : urn;

     

       39
       39
       +
           (** The error type URN. *)

     

       40
       40
       +
           status : int;

     

       41
       41
       +
           (** HTTP status code. *)

     

       42
       42
       +
           title : string option;

     

       43
       43
       +
           (** Short human-readable summary. *)

     

       44
       44
       +
           detail : string option;

     

       45
       45
       +
           (** Longer human-readable explanation. *)

     

       46
       46
       +
           limit : string option;

     

       47
       47
       +
           (** For "limit" errors, the name of the limit that was exceeded. *)

     

       48
       48
       +
         }

     

       49
       49
       +
         (** A request-level error per RFC 7807 Problem Details. *)

     

       50
       50
       +
       

     

       51
       51
       +
         val jsont : t Jsont.t

     

       52
       52
       +
         (** JSON codec for request-level errors. *)

     

       53
       53
       +
       end

     

       54
       54
       +
       

     

       55
       55
       +
       (** {1 Method-Level Errors}

     

       56
       56
       +
       

     

       57
       57
       +
           These are returned as the second element of an Invocation tuple

     

       58
       58
       +
           when a method call fails. *)

     

       59
       59
       +
       

     

       60
       60
       +
       (** Standard method error types per RFC 8620 Section 3.6.2 *)

     

       61
       61
       +
       type method_error_type =

     

       62
       62
       +
         | Server_unavailable

     

       63
       63
       +
         (** The server is temporarily unavailable. *)

     

       64
       64
       +
         | Server_fail

     

       65
       65
       +
         (** An unexpected error occurred. *)

     

       66
       66
       +
         | Server_partial_fail

     

       67
       67
       +
         (** Some, but not all, changes were successfully made. *)

     

       68
       68
       +
         | Unknown_method

     

       69
       69
       +
         (** The method name is not recognized. *)

     

       70
       70
       +
         | Invalid_arguments

     

       71
       71
       +
         (** One or more arguments are invalid. *)

     

       72
       72
       +
         | Invalid_result_reference

     

       73
       73
       +
         (** A result reference could not be resolved. *)

     

       74
       74
       +
         | Forbidden

     

       75
       75
       +
         (** The method/arguments are valid but forbidden. *)

     

       76
       76
       +
         | Account_not_found

     

       77
       77
       +
         (** The accountId does not correspond to a valid account. *)

     

       78
       78
       +
         | Account_not_supported_by_method

     

       79
       79
       +
         (** The account does not support this method. *)

     

       80
       80
       +
         | Account_read_only

     

       81
       81
       +
         (** The account is read-only. *)

     

       82
       82
       +
         | Other of string

     

       83
       83
       +
         (** Other error type not in the standard set. *)

     

       84
       84
       +
       

     

       85
       85
       +
       val method_error_type_to_string : method_error_type -> string

     

       86
       86
       +
       (** [method_error_type_to_string t] returns the type string. *)

     

       87
       87
       +
       

     

       88
       88
       +
       val method_error_type_of_string : string -> method_error_type

     

       89
       89
       +
       (** [method_error_type_of_string s] parses a type string. *)

     

       90
       90
       +
       

     

       91
       91
       +
       (** A method-level error response. *)

     

       92
       92
       +
       type method_error = {

     

       93
       93
       +
         type_ : method_error_type;

     

       94
       94
       +
         (** The error type. *)

     

       95
       95
       +
         description : string option;

     

       96
       96
       +
         (** Human-readable description of the error. *)

     

       97
       97
       +
       }

     

       98
       98
       +
       

     

       99
       99
       +
       val method_error_jsont : method_error Jsont.t

     

       100
       100
       +
       (** JSON codec for method errors. *)

     

       101
       101
       +
       

     

       102
       102
       +
       (** {1 SetError}

     

       103
       103
       +
       

     

       104
       104
       +
           Errors returned in notCreated/notUpdated/notDestroyed responses. *)

     

       105
       105
       +
       

     

       106
       106
       +
       (** Standard SetError types per RFC 8620 Section 5.3 *)

     

       107
       107
       +
       type set_error_type =

     

       108
       108
       +
         | Forbidden

     

       109
       109
       +
         (** The operation is not permitted. *)

     

       110
       110
       +
         | Over_quota

     

       111
       111
       +
         (** The maximum server quota has been reached. *)

     

       112
       112
       +
         | Too_large

     

       113
       113
       +
         (** The object is too large. *)

     

       114
       114
       +
         | Rate_limit

     

       115
       115
       +
         (** Too many objects of this type have been created recently. *)

     

       116
       116
       +
         | Not_found

     

       117
       117
       +
         (** The id does not exist (for update/destroy). *)

     

       118
       118
       +
         | Invalid_patch

     

       119
       119
       +
         (** The PatchObject is invalid. *)

     

       120
       120
       +
         | Will_destroy

     

       121
       121
       +
         (** The object will be destroyed by another operation in the request. *)

     

       122
       122
       +
         | Invalid_properties

     

       123
       123
       +
         (** Some properties were invalid. *)

     

       124
       124
       +
         | Singleton

     

       125
       125
       +
         (** Only one object of this type can exist (for create). *)

     

       126
       126
       +
         | Other of string

     

       127
       127
       +
         (** Other error type. *)

     

       128
       128
       +
       

     

       129
       129
       +
       val set_error_type_to_string : set_error_type -> string

     

       130
       130
       +
       val set_error_type_of_string : string -> set_error_type

     

       131
       131
       +
       

     

       132
       132
       +
       (** A SetError object. *)

     

       133
       133
       +
       type set_error = {

     

       134
       134
       +
         type_ : set_error_type;

     

       135
       135
       +
         (** The error type. *)

     

       136
       136
       +
         description : string option;

     

       137
       137
       +
         (** Human-readable description. *)

     

       138
       138
       +
         properties : string list option;

     

       139
       139
       +
         (** For invalidProperties errors, the list of invalid property names. *)

     

       140
       140
       +
       }

     

       141
       141
       +
       

     

       142
       142
       +
       val set_error : ?description:string -> ?properties:string list -> set_error_type -> set_error

     

       143
       143
       +
       (** [set_error ?description ?properties type_] creates a SetError. *)

     

       144
       144
       +
       

     

       145
       145
       +
       val set_error_jsont : set_error Jsont.t

     

       146
       146
       +
       (** JSON codec for SetError. *)

+123

proto/filter.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type operator = And | Or | Not

     

       7
       7
       +
       

     

       8
       8
       +
       let operator_to_string = function

     

       9
       9
       +
         | And -> "AND"

     

       10
       10
       +
         | Or -> "OR"

     

       11
       11
       +
         | Not -> "NOT"

     

       12
       12
       +
       

     

       13
       13
       +
       let operator_of_string = function

     

       14
       14
       +
         | "AND" -> And

     

       15
       15
       +
         | "OR" -> Or

     

       16
       16
       +
         | "NOT" -> Not

     

       17
       17
       +
         | s -> Jsont.Error.msgf Jsont.Meta.none "Unknown filter operator: %s" s

     

       18
       18
       +
       

     

       19
       19
       +
       let operator_jsont =

     

       20
       20
       +
         let kind = "Filter operator" in

     

       21
       21
       +
         Jsont.map ~kind

     

       22
       22
       +
           ~dec:(fun s -> operator_of_string s)

     

       23
       23
       +
           ~enc:operator_to_string

     

       24
       24
       +
           Jsont.string

     

       25
       25
       +
       

     

       26
       26
       +
       type 'condition filter_operator = {

     

       27
       27
       +
         operator : operator;

     

       28
       28
       +
         conditions : 'condition filter list;

     

       29
       29
       +
       }

     

       30
       30
       +
       

     

       31
       31
       +
       and 'condition filter =

     

       32
       32
       +
         | Operator of 'condition filter_operator

     

       33
       33
       +
         | Condition of 'condition

     

       34
       34
       +
       

     

       35
       35
       +
       let filter_jsont (type c) (condition_jsont : c Jsont.t) : c filter Jsont.t =

     

       36
       36
       +
         let kind = "Filter" in

     

       37
       37
       +
         (* Create a recursive codec using Jsont.rec' *)

     

       38
       38
       +
         let rec make_filter_jsont () =

     

       39
       39
       +
           let lazy_self = lazy (make_filter_jsont ()) in

     

       40
       40
       +
           (* Filter operator codec *)

     

       41
       41
       +
           let filter_operator_jsont =

     

       42
       42
       +
             let make operator conditions = { operator; conditions } in

     

       43
       43
       +
             Jsont.Object.map ~kind:"FilterOperator" make

     

       44
       44
       +
             |> Jsont.Object.mem "operator" operator_jsont ~enc:(fun o -> o.operator)

     

       45
       45
       +
             |> Jsont.Object.mem "conditions"

     

       46
       46
       +
                  (Jsont.list (Jsont.rec' lazy_self))

     

       47
       47
       +
                  ~enc:(fun o -> o.conditions)

     

       48
       48
       +
             |> Jsont.Object.finish

     

       49
       49
       +
           in

     

       50
       50
       +
           (* Decode function: check for "operator" field to determine type *)

     

       51
       51
       +
           let dec json =

     

       52
       52
       +
             match json with

     

       53
       53
       +
             | Jsont.Object (members, _) ->

     

       54
       54
       +
               (* members has type (name * json) list where name = string * Meta.t *)

     

       55
       55
       +
               if List.exists (fun ((k, _), _) -> k = "operator") members then begin

     

       56
       56
       +
                 (* It's an operator *)

     

       57
       57
       +
                 match Jsont.Json.decode' filter_operator_jsont json with

     

       58
       58
       +
                 | Ok op -> Operator op

     

       59
       59
       +
                 | Error e -> raise (Jsont.Error e)

     

       60
       60
       +
               end else begin

     

       61
       61
       +
                 (* It's a condition *)

     

       62
       62
       +
                 match Jsont.Json.decode' condition_jsont json with

     

       63
       63
       +
                 | Ok c -> Condition c

     

       64
       64
       +
                 | Error e -> raise (Jsont.Error e)

     

       65
       65
       +
               end

     

       66
       66
       +
             | Jsont.Null _ | Jsont.Bool _ | Jsont.Number _ | Jsont.String _ | Jsont.Array _ ->

     

       67
       67
       +
               Jsont.Error.msg Jsont.Meta.none "Filter must be an object"

     

       68
       68
       +
           in

     

       69
       69
       +
           (* Encode function *)

     

       70
       70
       +
           let enc = function

     

       71
       71
       +
             | Operator op ->

     

       72
       72
       +
               (match Jsont.Json.encode' filter_operator_jsont op with

     

       73
       73
       +
                | Ok j -> j

     

       74
       74
       +
                | Error e -> raise (Jsont.Error e))

     

       75
       75
       +
             | Condition c ->

     

       76
       76
       +
               (match Jsont.Json.encode' condition_jsont c with

     

       77
       77
       +
                | Ok j -> j

     

       78
       78
       +
                | Error e -> raise (Jsont.Error e))

     

       79
       79
       +
           in

     

       80
       80
       +
           Jsont.map ~kind ~dec ~enc Jsont.json

     

       81
       81
       +
         in

     

       82
       82
       +
         make_filter_jsont ()

     

       83
       83
       +
       

     

       84
       84
       +
       type comparator = {

     

       85
       85
       +
         property : string;

     

       86
       86
       +
         is_ascending : bool;

     

       87
       87
       +
         collation : string option;

     

       88
       88
       +
       }

     

       89
       89
       +
       

     

       90
       90
       +
       let comparator ?(is_ascending = true) ?collation property =

     

       91
       91
       +
         { property; is_ascending; collation }

     

       92
       92
       +
       

     

       93
       93
       +
       let comparator_property c = c.property

     

       94
       94
       +
       let comparator_is_ascending c = c.is_ascending

     

       95
       95
       +
       let comparator_collation c = c.collation

     

       96
       96
       +
       

     

       97
       97
       +
       let comparator_make property is_ascending collation =

     

       98
       98
       +
         { property; is_ascending; collation }

     

       99
       99
       +
       

     

       100
       100
       +
       let comparator_jsont =

     

       101
       101
       +
         let kind = "Comparator" in

     

       102
       102
       +
         Jsont.Object.map ~kind comparator_make

     

       103
       103
       +
         |> Jsont.Object.mem "property" Jsont.string ~enc:comparator_property

     

       104
       104
       +
         |> Jsont.Object.mem "isAscending" Jsont.bool ~dec_absent:true ~enc:comparator_is_ascending

     

       105
       105
       +
              ~enc_omit:(fun b -> b = true)

     

       106
       106
       +
         |> Jsont.Object.opt_mem "collation" Jsont.string ~enc:comparator_collation

     

       107
       107
       +
         |> Jsont.Object.finish

     

       108
       108
       +
       

     

       109
       109
       +
       type added_item = {

     

       110
       110
       +
         id : Id.t;

     

       111
       111
       +
         index : int64;

     

       112
       112
       +
       }

     

       113
       113
       +
       

     

       114
       114
       +
       let added_item_make id index = { id; index }

     

       115
       115
       +
       let added_item_id a = a.id

     

       116
       116
       +
       let added_item_index a = a.index

     

       117
       117
       +
       

     

       118
       118
       +
       let added_item_jsont =

     

       119
       119
       +
         let kind = "AddedItem" in

     

       120
       120
       +
         Jsont.Object.map ~kind added_item_make

     

       121
       121
       +
         |> Jsont.Object.mem "id" Id.jsont ~enc:added_item_id

     

       122
       122
       +
         |> Jsont.Object.mem "index" Int53.Unsigned.jsont ~enc:added_item_index

     

       123
       123
       +
         |> Jsont.Object.finish

+73

proto/filter.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP filter and sort types as defined in RFC 8620 Section 5.5 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Filter Operators} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** Filter operator types. *)

     

       11
       11
       +
       type operator =

     

       12
       12
       +
         | And  (** All conditions must match *)

     

       13
       13
       +
         | Or   (** At least one condition must match *)

     

       14
       14
       +
         | Not  (** Inverts a single condition *)

     

       15
       15
       +
       

     

       16
       16
       +
       val operator_jsont : operator Jsont.t

     

       17
       17
       +
       (** JSON codec for filter operators. *)

     

       18
       18
       +
       

     

       19
       19
       +
       (** A filter operator that combines conditions.

     

       20
       20
       +
       

     

       21
       21
       +
           When decoding, the filter determines whether a JSON object is an

     

       22
       22
       +
           operator (has "operator" field) or a condition. *)

     

       23
       23
       +
       type 'condition filter_operator = {

     

       24
       24
       +
         operator : operator;

     

       25
       25
       +
         conditions : 'condition filter list;

     

       26
       26
       +
       }

     

       27
       27
       +
       

     

       28
       28
       +
       (** A filter is either an operator combining filters, or a leaf condition. *)

     

       29
       29
       +
       and 'condition filter =

     

       30
       30
       +
         | Operator of 'condition filter_operator

     

       31
       31
       +
         | Condition of 'condition

     

       32
       32
       +
       

     

       33
       33
       +
       val filter_jsont : 'c Jsont.t -> 'c filter Jsont.t

     

       34
       34
       +
       (** [filter_jsont condition_jsont] creates a codec for filters with the

     

       35
       35
       +
           given condition type. The codec automatically distinguishes operators

     

       36
       36
       +
           from conditions by the presence of the "operator" field. *)

     

       37
       37
       +
       

     

       38
       38
       +
       (** {1 Comparators} *)

     

       39
       39
       +
       

     

       40
       40
       +
       (** A comparator for sorting query results. *)

     

       41
       41
       +
       type comparator = {

     

       42
       42
       +
         property : string;

     

       43
       43
       +
         (** The property to sort by. *)

     

       44
       44
       +
         is_ascending : bool;

     

       45
       45
       +
         (** [true] for ascending order (default), [false] for descending. *)

     

       46
       46
       +
         collation : string option;

     

       47
       47
       +
         (** Optional collation algorithm for string comparison. *)

     

       48
       48
       +
       }

     

       49
       49
       +
       

     

       50
       50
       +
       val comparator :

     

       51
       51
       +
         ?is_ascending:bool ->

     

       52
       52
       +
         ?collation:string ->

     

       53
       53
       +
         string ->

     

       54
       54
       +
         comparator

     

       55
       55
       +
       (** [comparator ?is_ascending ?collation property] creates a comparator.

     

       56
       56
       +
           [is_ascending] defaults to [true]. *)

     

       57
       57
       +
       

     

       58
       58
       +
       val comparator_property : comparator -> string

     

       59
       59
       +
       val comparator_is_ascending : comparator -> bool

     

       60
       60
       +
       val comparator_collation : comparator -> string option

     

       61
       61
       +
       

     

       62
       62
       +
       val comparator_jsont : comparator Jsont.t

     

       63
       63
       +
       (** JSON codec for comparators. *)

     

       64
       64
       +
       

     

       65
       65
       +
       (** {1 Position Information} *)

     

       66
       66
       +
       

     

       67
       67
       +
       (** Added entry position in query change results. *)

     

       68
       68
       +
       type added_item = {

     

       69
       69
       +
         id : Id.t;

     

       70
       70
       +
         index : int64;

     

       71
       71
       +
       }

     

       72
       72
       +
       

     

       73
       73
       +
       val added_item_jsont : added_item Jsont.t

+51

proto/id.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP identifier type as defined in RFC 8620 Section 1.2.

     

       7
       7
       +
       

     

       8
       8
       +
           An Id is a string of 1-255 octets from the URL-safe base64 alphabet. *)

     

       9
       9
       +
       

     

       10
       10
       +
       type t = string

     

       11
       11
       +
       

     

       12
       12
       +
       (* Valid characters: A-Za-z0-9_- (URL-safe base64 alphabet) *)

     

       13
       13
       +
       let is_valid_char c =

     

       14
       14
       +
         (c >= 'A' && c <= 'Z') ||

     

       15
       15
       +
         (c >= 'a' && c <= 'z') ||

     

       16
       16
       +
         (c >= '0' && c <= '9') ||

     

       17
       17
       +
         c = '_' || c = '-'

     

       18
       18
       +
       

     

       19
       19
       +
       let validate s =

     

       20
       20
       +
         let len = String.length s in

     

       21
       21
       +
         if len = 0 then Error "Id cannot be empty"

     

       22
       22
       +
         else if len > 255 then Error "Id cannot exceed 255 characters"

     

       23
       23
       +
         else

     

       24
       24
       +
           let rec check i =

     

       25
       25
       +
             if i >= len then Ok s

     

       26
       26
       +
             else if is_valid_char s.[i] then check (i + 1)

     

       27
       27
       +
             else Error (Printf.sprintf "Invalid character '%c' in Id at position %d" s.[i] i)

     

       28
       28
       +
           in

     

       29
       29
       +
           check 0

     

       30
       30
       +
       

     

       31
       31
       +
       let of_string = validate

     

       32
       32
       +
       

     

       33
       33
       +
       let of_string_exn s =

     

       34
       34
       +
         match validate s with

     

       35
       35
       +
         | Ok id -> id

     

       36
       36
       +
         | Error msg -> invalid_arg msg

     

       37
       37
       +
       

     

       38
       38
       +
       let to_string t = t

     

       39
       39
       +
       let equal = String.equal

     

       40
       40
       +
       let compare = String.compare

     

       41
       41
       +
       let pp ppf t = Format.pp_print_string ppf t

     

       42
       42
       +
       

     

       43
       43
       +
       let jsont =

     

       44
       44
       +
         let kind = "Id" in

     

       45
       45
       +
         let dec s =

     

       46
       46
       +
           match validate s with

     

       47
       47
       +
           | Ok id -> id

     

       48
       48
       +
           | Error msg -> Jsont.Error.msgf Jsont.Meta.none "%s: %s" kind msg

     

       49
       49
       +
         in

     

       50
       50
       +
         let enc t = t in

     

       51
       51
       +
         Jsont.map ~kind ~dec ~enc Jsont.string

+38

proto/id.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP identifier type.

     

       7
       7
       +
       

     

       8
       8
       +
           An Id is a string of 1-255 octets from the URL-safe base64 alphabet

     

       9
       9
       +
           (A-Za-z0-9_-), plus the ASCII alphanumeric characters.

     

       10
       10
       +
       

     

       11
       11
       +
           See {{:https://datatracker.ietf.org/doc/html/rfc8620#section-1.2} RFC 8620 Section 1.2}. *)

     

       12
       12
       +
       

     

       13
       13
       +
       type t

     

       14
       14
       +
       (** The type of JMAP identifiers. *)

     

       15
       15
       +
       

     

       16
       16
       +
       val of_string : string -> (t, string) result

     

       17
       17
       +
       (** [of_string s] creates an Id from string [s].

     

       18
       18
       +
           Returns [Error msg] if [s] is empty, longer than 255 characters,

     

       19
       19
       +
           or contains invalid characters. *)

     

       20
       20
       +
       

     

       21
       21
       +
       val of_string_exn : string -> t

     

       22
       22
       +
       (** [of_string_exn s] creates an Id from string [s].

     

       23
       23
       +
           @raise Invalid_argument if the string is invalid. *)

     

       24
       24
       +
       

     

       25
       25
       +
       val to_string : t -> string

     

       26
       26
       +
       (** [to_string id] returns the string representation of [id]. *)

     

       27
       27
       +
       

     

       28
       28
       +
       val equal : t -> t -> bool

     

       29
       29
       +
       (** [equal a b] tests equality of identifiers. *)

     

       30
       30
       +
       

     

       31
       31
       +
       val compare : t -> t -> int

     

       32
       32
       +
       (** [compare a b] compares two identifiers. *)

     

       33
       33
       +
       

     

       34
       34
       +
       val pp : Format.formatter -> t -> unit

     

       35
       35
       +
       (** [pp ppf id] pretty-prints [id] to [ppf]. *)

     

       36
       36
       +
       

     

       37
       37
       +
       val jsont : t Jsont.t

     

       38
       38
       +
       (** JSON codec for JMAP identifiers. *)

+67

proto/int53.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JavaScript-safe integer types for JSON.

     

       7
       7
       +
       

     

       8
       8
       +
           These types represent integers that can be safely represented in JavaScript's

     

       9
       9
       +
           IEEE 754 double-precision floating point format without loss of precision. *)

     

       10
       10
       +
       

     

       11
       11
       +
       (** 53-bit signed integer with range -2^53+1 to 2^53-1 *)

     

       12
       12
       +
       module Signed = struct

     

       13
       13
       +
         type t = int64

     

       14
       14
       +
       

     

       15
       15
       +
         (* 2^53 - 1 *)

     

       16
       16
       +
         let max_value = 9007199254740991L

     

       17
       17
       +
         (* -(2^53 - 1) *)

     

       18
       18
       +
         let min_value = -9007199254740991L

     

       19
       19
       +
       

     

       20
       20
       +
         let of_int n = Int64.of_int n

     

       21
       21
       +
       

     

       22
       22
       +
         let to_int n =

     

       23
       23
       +
           if n >= Int64.of_int min_int && n <= Int64.of_int max_int then

     

       24
       24
       +
             Some (Int64.to_int n)

     

       25
       25
       +
           else

     

       26
       26
       +
             None

     

       27
       27
       +
       

     

       28
       28
       +
         let of_int64 n =

     

       29
       29
       +
           if n >= min_value && n <= max_value then Ok n

     

       30
       30
       +
           else Error (Printf.sprintf "Int53 out of range: %Ld" n)

     

       31
       31
       +
       

     

       32
       32
       +
         let jsont =

     

       33
       33
       +
           let kind = "Int53" in

     

       34
       34
       +
           let dec f =

     

       35
       35
       +
             let n = Int64.of_float f in

     

       36
       36
       +
             if n >= min_value && n <= max_value then n

     

       37
       37
       +
             else Jsont.Error.msgf Jsont.Meta.none "%s: value %Ld out of safe integer range" kind n

     

       38
       38
       +
           in

     

       39
       39
       +
           let enc n = Int64.to_float n in

     

       40
       40
       +
           Jsont.map ~kind ~dec ~enc Jsont.number

     

       41
       41
       +
       end

     

       42
       42
       +
       

     

       43
       43
       +
       (** 53-bit unsigned integer with range 0 to 2^53-1 *)

     

       44
       44
       +
       module Unsigned = struct

     

       45
       45
       +
         type t = int64

     

       46
       46
       +
       

     

       47
       47
       +
         let min_value = 0L

     

       48
       48
       +
         let max_value = 9007199254740991L

     

       49
       49
       +
       

     

       50
       50
       +
         let of_int n =

     

       51
       51
       +
           if n >= 0 then Ok (Int64.of_int n)

     

       52
       52
       +
           else Error "UnsignedInt53 cannot be negative"

     

       53
       53
       +
       

     

       54
       54
       +
         let of_int64 n =

     

       55
       55
       +
           if n >= min_value && n <= max_value then Ok n

     

       56
       56
       +
           else Error (Printf.sprintf "UnsignedInt53 out of range: %Ld" n)

     

       57
       57
       +
       

     

       58
       58
       +
         let jsont =

     

       59
       59
       +
           let kind = "UnsignedInt53" in

     

       60
       60
       +
           let dec f =

     

       61
       61
       +
             let n = Int64.of_float f in

     

       62
       62
       +
             if n >= min_value && n <= max_value then n

     

       63
       63
       +
             else Jsont.Error.msgf Jsont.Meta.none "%s: value %Ld out of range [0, 2^53-1]" kind n

     

       64
       64
       +
           in

     

       65
       65
       +
           let enc n = Int64.to_float n in

     

       66
       66
       +
           Jsont.map ~kind ~dec ~enc Jsont.number

     

       67
       67
       +
       end

+62

proto/int53.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JavaScript-safe integer types for JSON.

     

       7
       7
       +
       

     

       8
       8
       +
           These types represent integers that can be safely represented in JavaScript's

     

       9
       9
       +
           IEEE 754 double-precision floating point format without loss of precision.

     

       10
       10
       +
           The safe range is -2^53+1 to 2^53-1.

     

       11
       11
       +
       

     

       12
       12
       +
           See {{:https://datatracker.ietf.org/doc/html/rfc8620#section-1.3} RFC 8620 Section 1.3}. *)

     

       13
       13
       +
       

     

       14
       14
       +
       (** 53-bit signed integer.

     

       15
       15
       +
       

     

       16
       16
       +
           The range is -2^53+1 to 2^53-1, which is the safe integer range

     

       17
       17
       +
           for JavaScript/JSON numbers. *)

     

       18
       18
       +
       module Signed : sig

     

       19
       19
       +
         type t = int64

     

       20
       20
       +
         (** The type of 53-bit signed integers. *)

     

       21
       21
       +
       

     

       22
       22
       +
         val min_value : t

     

       23
       23
       +
         (** Minimum value: -9007199254740991 (-2^53+1) *)

     

       24
       24
       +
       

     

       25
       25
       +
         val max_value : t

     

       26
       26
       +
         (** Maximum value: 9007199254740991 (2^53-1) *)

     

       27
       27
       +
       

     

       28
       28
       +
         val of_int : int -> t

     

       29
       29
       +
         (** [of_int n] converts an OCaml int to Int53. *)

     

       30
       30
       +
       

     

       31
       31
       +
         val to_int : t -> int option

     

       32
       32
       +
         (** [to_int n] converts to OCaml int if it fits. *)

     

       33
       33
       +
       

     

       34
       34
       +
         val of_int64 : int64 -> (t, string) result

     

       35
       35
       +
         (** [of_int64 n] validates that [n] is in the safe range. *)

     

       36
       36
       +
       

     

       37
       37
       +
         val jsont : t Jsont.t

     

       38
       38
       +
         (** JSON codec for 53-bit integers. Encoded as JSON number. *)

     

       39
       39
       +
       end

     

       40
       40
       +
       

     

       41
       41
       +
       (** 53-bit unsigned integer.

     

       42
       42
       +
       

     

       43
       43
       +
           The range is 0 to 2^53-1. *)

     

       44
       44
       +
       module Unsigned : sig

     

       45
       45
       +
         type t = int64

     

       46
       46
       +
         (** The type of 53-bit unsigned integers. *)

     

       47
       47
       +
       

     

       48
       48
       +
         val min_value : t

     

       49
       49
       +
         (** Minimum value: 0 *)

     

       50
       50
       +
       

     

       51
       51
       +
         val max_value : t

     

       52
       52
       +
         (** Maximum value: 9007199254740991 (2^53-1) *)

     

       53
       53
       +
       

     

       54
       54
       +
         val of_int : int -> (t, string) result

     

       55
       55
       +
         (** [of_int n] converts an OCaml int to UnsignedInt53. *)

     

       56
       56
       +
       

     

       57
       57
       +
         val of_int64 : int64 -> (t, string) result

     

       58
       58
       +
         (** [of_int64 n] validates that [n] is in the valid range. *)

     

       59
       59
       +
       

     

       60
       60
       +
         val jsont : t Jsont.t

     

       61
       61
       +
         (** JSON codec for 53-bit unsigned integers. *)

     

       62
       62
       +
       end

+86

proto/invocation.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type result_reference = {

     

       7
       7
       +
         result_of : string;

     

       8
       8
       +
         name : string;

     

       9
       9
       +
         path : string;

     

       10
       10
       +
       }

     

       11
       11
       +
       

     

       12
       12
       +
       let result_reference ~result_of ~name ~path =

     

       13
       13
       +
         { result_of; name; path }

     

       14
       14
       +
       

     

       15
       15
       +
       let result_reference_make result_of name path =

     

       16
       16
       +
         { result_of; name; path }

     

       17
       17
       +
       

     

       18
       18
       +
       let result_reference_jsont =

     

       19
       19
       +
         let kind = "ResultReference" in

     

       20
       20
       +
         Jsont.Object.map ~kind result_reference_make

     

       21
       21
       +
         |> Jsont.Object.mem "resultOf" Jsont.string ~enc:(fun r -> r.result_of)

     

       22
       22
       +
         |> Jsont.Object.mem "name" Jsont.string ~enc:(fun r -> r.name)

     

       23
       23
       +
         |> Jsont.Object.mem "path" Jsont.string ~enc:(fun r -> r.path)

     

       24
       24
       +
         |> Jsont.Object.finish

     

       25
       25
       +
       

     

       26
       26
       +
       type t = {

     

       27
       27
       +
         name : string;

     

       28
       28
       +
         arguments : Jsont.json;

     

       29
       29
       +
         method_call_id : string;

     

       30
       30
       +
       }

     

       31
       31
       +
       

     

       32
       32
       +
       let create ~name ~arguments ~method_call_id =

     

       33
       33
       +
         { name; arguments; method_call_id }

     

       34
       34
       +
       

     

       35
       35
       +
       let name t = t.name

     

       36
       36
       +
       let arguments t = t.arguments

     

       37
       37
       +
       let method_call_id t = t.method_call_id

     

       38
       38
       +
       

     

       39
       39
       +
       (* Helper to encode a typed value back to Jsont.json *)

     

       40
       40
       +
       let encode_json_value jsont value =

     

       41
       41
       +
         match Jsont.Json.encode' jsont value with

     

       42
       42
       +
         | Ok json -> json

     

       43
       43
       +
         | Error _ -> Jsont.Object ([], Jsont.Meta.none)

     

       44
       44
       +
       

     

       45
       45
       +
       let jsont =

     

       46
       46
       +
         let kind = "Invocation" in

     

       47
       47
       +
         (* Invocation is [name, args, callId] - a 3-element heterogeneous array *)

     

       48
       48
       +
         (* We need to handle this as a json array since elements have different types *)

     

       49
       49
       +
         let dec json =

     

       50
       50
       +
           match json with

     

       51
       51
       +
           | Jsont.Array ([name_json; arguments; call_id_json], _) ->

     

       52
       52
       +
             let name = match name_json with

     

       53
       53
       +
               | Jsont.String (s, _) -> s

     

       54
       54
       +
               | _ -> Jsont.Error.msg Jsont.Meta.none "Invocation[0] must be a string"

     

       55
       55
       +
             in

     

       56
       56
       +
             let method_call_id = match call_id_json with

     

       57
       57
       +
               | Jsont.String (s, _) -> s

     

       58
       58
       +
               | _ -> Jsont.Error.msg Jsont.Meta.none "Invocation[2] must be a string"

     

       59
       59
       +
             in

     

       60
       60
       +
             { name; arguments; method_call_id }

     

       61
       61
       +
           | Jsont.Array _ ->

     

       62
       62
       +
             Jsont.Error.msg Jsont.Meta.none "Invocation must be a 3-element array"

     

       63
       63
       +
           | _ ->

     

       64
       64
       +
             Jsont.Error.msg Jsont.Meta.none "Invocation must be an array"

     

       65
       65
       +
         in

     

       66
       66
       +
         let enc t =

     

       67
       67
       +
           Jsont.Array ([

     

       68
       68
       +
             Jsont.String (t.name, Jsont.Meta.none);

     

       69
       69
       +
             t.arguments;

     

       70
       70
       +
             Jsont.String (t.method_call_id, Jsont.Meta.none);

     

       71
       71
       +
           ], Jsont.Meta.none)

     

       72
       72
       +
         in

     

       73
       73
       +
         Jsont.map ~kind ~dec ~enc Jsont.json

     

       74
       74
       +
       

     

       75
       75
       +
       let make_get ~method_call_id ~method_name args =

     

       76
       76
       +
         let arguments = encode_json_value Method_.get_args_jsont args in

     

       77
       77
       +
         { name = method_name; arguments; method_call_id }

     

       78
       78
       +
       

     

       79
       79
       +
       let make_changes ~method_call_id ~method_name args =

     

       80
       80
       +
         let arguments = encode_json_value Method_.changes_args_jsont args in

     

       81
       81
       +
         { name = method_name; arguments; method_call_id }

     

       82
       82
       +
       

     

       83
       83
       +
       let make_query (type f) ~method_call_id ~method_name

     

       84
       84
       +
           ~(filter_cond_jsont : f Jsont.t) (args : f Method_.query_args) =

     

       85
       85
       +
         let arguments = encode_json_value (Method_.query_args_jsont filter_cond_jsont) args in

     

       86
       86
       +
         { name = method_name; arguments; method_call_id }

+81

proto/invocation.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP method invocation as defined in RFC 8620 Section 3.2 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Result References} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** A reference to a result from a previous method call.

     

       11
       11
       +
       

     

       12
       12
       +
           Used for back-referencing values within a single request. *)

     

       13
       13
       +
       type result_reference = {

     

       14
       14
       +
         result_of : string;

     

       15
       15
       +
         (** The method call id to reference. *)

     

       16
       16
       +
         name : string;

     

       17
       17
       +
         (** The method name that was called. *)

     

       18
       18
       +
         path : string;

     

       19
       19
       +
         (** A JSON Pointer to the value within the result. *)

     

       20
       20
       +
       }

     

       21
       21
       +
       

     

       22
       22
       +
       val result_reference :

     

       23
       23
       +
         result_of:string ->

     

       24
       24
       +
         name:string ->

     

       25
       25
       +
         path:string ->

     

       26
       26
       +
         result_reference

     

       27
       27
       +
       

     

       28
       28
       +
       val result_reference_jsont : result_reference Jsont.t

     

       29
       29
       +
       

     

       30
       30
       +
       (** {1 Invocations} *)

     

       31
       31
       +
       

     

       32
       32
       +
       (** A method invocation.

     

       33
       33
       +
       

     

       34
       34
       +
           In JSON, this is represented as a 3-element array:

     

       35
       35
       +
           ["methodName", {args}, "methodCallId"] *)

     

       36
       36
       +
       type t = {

     

       37
       37
       +
         name : string;

     

       38
       38
       +
         (** The method name, e.g., "Email/get". *)

     

       39
       39
       +
         arguments : Jsont.json;

     

       40
       40
       +
         (** The method arguments as a JSON object. *)

     

       41
       41
       +
         method_call_id : string;

     

       42
       42
       +
         (** Client-specified identifier for this call. *)

     

       43
       43
       +
       }

     

       44
       44
       +
       

     

       45
       45
       +
       val create :

     

       46
       46
       +
         name:string ->

     

       47
       47
       +
         arguments:Jsont.json ->

     

       48
       48
       +
         method_call_id:string ->

     

       49
       49
       +
         t

     

       50
       50
       +
       (** [create ~name ~arguments ~method_call_id] creates an invocation. *)

     

       51
       51
       +
       

     

       52
       52
       +
       val name : t -> string

     

       53
       53
       +
       val arguments : t -> Jsont.json

     

       54
       54
       +
       val method_call_id : t -> string

     

       55
       55
       +
       

     

       56
       56
       +
       val jsont : t Jsont.t

     

       57
       57
       +
       (** JSON codec for invocations (as 3-element array). *)

     

       58
       58
       +
       

     

       59
       59
       +
       (** {1 Typed Invocation Helpers} *)

     

       60
       60
       +
       

     

       61
       61
       +
       val make_get :

     

       62
       62
       +
         method_call_id:string ->

     

       63
       63
       +
         method_name:string ->

     

       64
       64
       +
         Method_.get_args ->

     

       65
       65
       +
         t

     

       66
       66
       +
       (** [make_get ~method_call_id ~method_name args] creates a /get invocation. *)

     

       67
       67
       +
       

     

       68
       68
       +
       val make_changes :

     

       69
       69
       +
         method_call_id:string ->

     

       70
       70
       +
         method_name:string ->

     

       71
       71
       +
         Method_.changes_args ->

     

       72
       72
       +
         t

     

       73
       73
       +
       (** [make_changes ~method_call_id ~method_name args] creates a /changes invocation. *)

     

       74
       74
       +
       

     

       75
       75
       +
       val make_query :

     

       76
       76
       +
         method_call_id:string ->

     

       77
       77
       +
         method_name:string ->

     

       78
       78
       +
         filter_cond_jsont:'f Jsont.t ->

     

       79
       79
       +
         'f Method_.query_args ->

     

       80
       80
       +
         t

     

       81
       81
       +
       (** [make_query ~method_call_id ~method_name ~filter_cond_jsont args] creates a /query invocation. *)

+24

proto/jmap_proto.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP Protocol Types (RFC 8620)

     

       7
       7
       +
       

     

       8
       8
       +
           This module re-exports all JMAP core protocol types. *)

     

       9
       9
       +
       

     

       10
       10
       +
       module Id = Id

     

       11
       11
       +
       module Int53 = Int53

     

       12
       12
       +
       module Date = Date

     

       13
       13
       +
       module Json_map = Json_map

     

       14
       14
       +
       module Unknown = Unknown

     

       15
       15
       +
       module Error = Error

     

       16
       16
       +
       module Capability = Capability

     

       17
       17
       +
       module Filter = Filter

     

       18
       18
       +
       module Method = Method_

     

       19
       19
       +
       module Invocation = Invocation

     

       20
       20
       +
       module Request = Request

     

       21
       21
       +
       module Response = Response

     

       22
       22
       +
       module Session = Session

     

       23
       23
       +
       module Push = Push

     

       24
       24
       +
       module Blob = Blob

+40

proto/json_map.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JSON object-as-map codec utilities.

     

       7
       7
       +
       

     

       8
       8
       +
           JMAP frequently uses JSON objects as maps with string or Id keys.

     

       9
       9
       +
           These codecs convert between JSON objects and OCaml association lists. *)

     

       10
       10
       +
       

     

       11
       11
       +
       module String_map = Map.Make(String)

     

       12
       12
       +
       

     

       13
       13
       +
       let of_string value_jsont =

     

       14
       14
       +
         let kind = "String map" in

     

       15
       15
       +
         Jsont.Object.map ~kind Fun.id

     

       16
       16
       +
         |> Jsont.Object.keep_unknown (Jsont.Object.Mems.string_map value_jsont) ~enc:Fun.id

     

       17
       17
       +
         |> Jsont.Object.finish

     

       18
       18
       +
         |> Jsont.map

     

       19
       19
       +
           ~dec:(fun m -> List.of_seq (String_map.to_seq m))

     

       20
       20
       +
           ~enc:(fun l -> String_map.of_list l)

     

       21
       21
       +
       

     

       22
       22
       +
       let of_id value_jsont =

     

       23
       23
       +
         let kind = "Id map" in

     

       24
       24
       +
         (* Use string map internally, then convert keys to Ids *)

     

       25
       25
       +
         let string_codec = of_string value_jsont in

     

       26
       26
       +
         let dec pairs =

     

       27
       27
       +
           List.map (fun (k, v) ->

     

       28
       28
       +
             match Id.of_string k with

     

       29
       29
       +
             | Ok id -> (id, v)

     

       30
       30
       +
             | Error msg -> Jsont.Error.msgf Jsont.Meta.none "%s: invalid key %s - %s" kind k msg

     

       31
       31
       +
           ) pairs

     

       32
       32
       +
         in

     

       33
       33
       +
         let enc pairs =

     

       34
       34
       +
           List.map (fun (id, v) -> (Id.to_string id, v)) pairs

     

       35
       35
       +
         in

     

       36
       36
       +
         Jsont.map ~kind ~dec ~enc string_codec

     

       37
       37
       +
       

     

       38
       38
       +
       let id_to_bool = of_id Jsont.bool

     

       39
       39
       +
       

     

       40
       40
       +
       let string_to_bool = of_string Jsont.bool

+23

proto/json_map.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JSON object-as-map codec utilities.

     

       7
       7
       +
       

     

       8
       8
       +
           JMAP frequently uses JSON objects as maps with string or Id keys.

     

       9
       9
       +
           These codecs convert between JSON objects and OCaml association lists. *)

     

       10
       10
       +
       

     

       11
       11
       +
       val of_string : 'a Jsont.t -> (string * 'a) list Jsont.t

     

       12
       12
       +
       (** [of_string value_jsont] creates a codec for JSON objects

     

       13
       13
       +
           used as string-keyed maps. Returns an association list. *)

     

       14
       14
       +
       

     

       15
       15
       +
       val of_id : 'a Jsont.t -> (Id.t * 'a) list Jsont.t

     

       16
       16
       +
       (** [of_id value_jsont] creates a codec for JSON objects

     

       17
       17
       +
           keyed by JMAP identifiers. *)

     

       18
       18
       +
       

     

       19
       19
       +
       val id_to_bool : (Id.t * bool) list Jsont.t

     

       20
       20
       +
       (** Codec for Id[Boolean] maps, common in JMAP (e.g., mailboxIds, keywords). *)

     

       21
       21
       +
       

     

       22
       22
       +
       val string_to_bool : (string * bool) list Jsont.t

     

       23
       23
       +
       (** Codec for String[Boolean] maps. *)

+17

proto/mail/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name jmap_mail)

     

       3
       3
       +
        (public_name jmap.mail)

     

       4
       4
       +
        (libraries jmap jsont ptime)

     

       5
       5
       +
        (modules

     

       6
       6
       +
         jmap_mail

     

       7
       7
       +
         email_address

     

       8
       8
       +
         email_header

     

       9
       9
       +
         email_body

     

       10
       10
       +
         mailbox

     

       11
       11
       +
         thread

     

       12
       12
       +
         email

     

       13
       13
       +
         search_snippet

     

       14
       14
       +
         identity

     

       15
       15
       +
         submission

     

       16
       16
       +
         vacation

     

       17
       17
       +
         mail_filter))

+216

proto/mail/email.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       module Keyword = struct

     

       7
       7
       +
         let draft = "$draft"

     

       8
       8
       +
         let seen = "$seen"

     

       9
       9
       +
         let flagged = "$flagged"

     

       10
       10
       +
         let answered = "$answered"

     

       11
       11
       +
         let forwarded = "$forwarded"

     

       12
       12
       +
         let phishing = "$phishing"

     

       13
       13
       +
         let junk = "$junk"

     

       14
       14
       +
         let not_junk = "$notjunk"

     

       15
       15
       +
       end

     

       16
       16
       +
       

     

       17
       17
       +
       type t = {

     

       18
       18
       +
         id : Jmap_proto.Id.t;

     

       19
       19
       +
         blob_id : Jmap_proto.Id.t;

     

       20
       20
       +
         thread_id : Jmap_proto.Id.t;

     

       21
       21
       +
         size : int64;

     

       22
       22
       +
         received_at : Ptime.t;

     

       23
       23
       +
         mailbox_ids : (Jmap_proto.Id.t * bool) list;

     

       24
       24
       +
         keywords : (string * bool) list;

     

       25
       25
       +
         message_id : string list option;

     

       26
       26
       +
         in_reply_to : string list option;

     

       27
       27
       +
         references : string list option;

     

       28
       28
       +
         sender : Email_address.t list option;

     

       29
       29
       +
         from : Email_address.t list option;

     

       30
       30
       +
         to_ : Email_address.t list option;

     

       31
       31
       +
         cc : Email_address.t list option;

     

       32
       32
       +
         bcc : Email_address.t list option;

     

       33
       33
       +
         reply_to : Email_address.t list option;

     

       34
       34
       +
         subject : string option;

     

       35
       35
       +
         sent_at : Ptime.t option;

     

       36
       36
       +
         headers : Email_header.t list option;

     

       37
       37
       +
         body_structure : Email_body.Part.t option;

     

       38
       38
       +
         body_values : (string * Email_body.Value.t) list option;

     

       39
       39
       +
         text_body : Email_body.Part.t list option;

     

       40
       40
       +
         html_body : Email_body.Part.t list option;

     

       41
       41
       +
         attachments : Email_body.Part.t list option;

     

       42
       42
       +
         has_attachment : bool;

     

       43
       43
       +
         preview : string;

     

       44
       44
       +
       }

     

       45
       45
       +
       

     

       46
       46
       +
       let id t = t.id

     

       47
       47
       +
       let blob_id t = t.blob_id

     

       48
       48
       +
       let thread_id t = t.thread_id

     

       49
       49
       +
       let size t = t.size

     

       50
       50
       +
       let received_at t = t.received_at

     

       51
       51
       +
       let mailbox_ids t = t.mailbox_ids

     

       52
       52
       +
       let keywords t = t.keywords

     

       53
       53
       +
       let message_id t = t.message_id

     

       54
       54
       +
       let in_reply_to t = t.in_reply_to

     

       55
       55
       +
       let references t = t.references

     

       56
       56
       +
       let sender t = t.sender

     

       57
       57
       +
       let from t = t.from

     

       58
       58
       +
       let to_ t = t.to_

     

       59
       59
       +
       let cc t = t.cc

     

       60
       60
       +
       let bcc t = t.bcc

     

       61
       61
       +
       let reply_to t = t.reply_to

     

       62
       62
       +
       let subject t = t.subject

     

       63
       63
       +
       let sent_at t = t.sent_at

     

       64
       64
       +
       let headers t = t.headers

     

       65
       65
       +
       let body_structure t = t.body_structure

     

       66
       66
       +
       let body_values t = t.body_values

     

       67
       67
       +
       let text_body t = t.text_body

     

       68
       68
       +
       let html_body t = t.html_body

     

       69
       69
       +
       let attachments t = t.attachments

     

       70
       70
       +
       let has_attachment t = t.has_attachment

     

       71
       71
       +
       let preview t = t.preview

     

       72
       72
       +
       

     

       73
       73
       +
       let make id blob_id thread_id size received_at mailbox_ids keywords

     

       74
       74
       +
           message_id in_reply_to references sender from to_ cc bcc reply_to

     

       75
       75
       +
           subject sent_at headers body_structure body_values text_body html_body

     

       76
       76
       +
           attachments has_attachment preview =

     

       77
       77
       +
         { id; blob_id; thread_id; size; received_at; mailbox_ids; keywords;

     

       78
       78
       +
           message_id; in_reply_to; references; sender; from; to_; cc; bcc;

     

       79
       79
       +
           reply_to; subject; sent_at; headers; body_structure; body_values;

     

       80
       80
       +
           text_body; html_body; attachments; has_attachment; preview }

     

       81
       81
       +
       

     

       82
       82
       +
       let jsont =

     

       83
       83
       +
         let kind = "Email" in

     

       84
       84
       +
         let body_values_jsont = Jmap_proto.Json_map.of_string Email_body.Value.jsont in

     

       85
       85
       +
         Jsont.Object.map ~kind make

     

       86
       86
       +
         |> Jsont.Object.mem "id" Jmap_proto.Id.jsont ~enc:id

     

       87
       87
       +
         |> Jsont.Object.mem "blobId" Jmap_proto.Id.jsont ~enc:blob_id

     

       88
       88
       +
         |> Jsont.Object.mem "threadId" Jmap_proto.Id.jsont ~enc:thread_id

     

       89
       89
       +
         |> Jsont.Object.mem "size" Jmap_proto.Int53.Unsigned.jsont ~enc:size

     

       90
       90
       +
         |> Jsont.Object.mem "receivedAt" Jmap_proto.Date.Utc.jsont ~enc:received_at

     

       91
       91
       +
         |> Jsont.Object.mem "mailboxIds" Jmap_proto.Json_map.id_to_bool ~enc:mailbox_ids

     

       92
       92
       +
         |> Jsont.Object.mem "keywords" Jmap_proto.Json_map.string_to_bool ~dec_absent:[] ~enc:keywords

     

       93
       93
       +
         |> Jsont.Object.opt_mem "messageId" (Jsont.list Jsont.string) ~enc:message_id

     

       94
       94
       +
         |> Jsont.Object.opt_mem "inReplyTo" (Jsont.list Jsont.string) ~enc:in_reply_to

     

       95
       95
       +
         |> Jsont.Object.opt_mem "references" (Jsont.list Jsont.string) ~enc:references

     

       96
       96
       +
         |> Jsont.Object.opt_mem "sender" (Jsont.list Email_address.jsont) ~enc:sender

     

       97
       97
       +
         |> Jsont.Object.opt_mem "from" (Jsont.list Email_address.jsont) ~enc:from

     

       98
       98
       +
         |> Jsont.Object.opt_mem "to" (Jsont.list Email_address.jsont) ~enc:to_

     

       99
       99
       +
         |> Jsont.Object.opt_mem "cc" (Jsont.list Email_address.jsont) ~enc:cc

     

       100
       100
       +
         |> Jsont.Object.opt_mem "bcc" (Jsont.list Email_address.jsont) ~enc:bcc

     

       101
       101
       +
         |> Jsont.Object.opt_mem "replyTo" (Jsont.list Email_address.jsont) ~enc:reply_to

     

       102
       102
       +
         |> Jsont.Object.opt_mem "subject" Jsont.string ~enc:subject

     

       103
       103
       +
         |> Jsont.Object.opt_mem "sentAt" Jmap_proto.Date.Rfc3339.jsont ~enc:sent_at

     

       104
       104
       +
         |> Jsont.Object.opt_mem "headers" (Jsont.list Email_header.jsont) ~enc:headers

     

       105
       105
       +
         |> Jsont.Object.opt_mem "bodyStructure" Email_body.Part.jsont ~enc:body_structure

     

       106
       106
       +
         |> Jsont.Object.opt_mem "bodyValues" body_values_jsont ~enc:body_values

     

       107
       107
       +
         |> Jsont.Object.opt_mem "textBody" (Jsont.list Email_body.Part.jsont) ~enc:text_body

     

       108
       108
       +
         |> Jsont.Object.opt_mem "htmlBody" (Jsont.list Email_body.Part.jsont) ~enc:html_body

     

       109
       109
       +
         |> Jsont.Object.opt_mem "attachments" (Jsont.list Email_body.Part.jsont) ~enc:attachments

     

       110
       110
       +
         |> Jsont.Object.mem "hasAttachment" Jsont.bool ~dec_absent:false ~enc:has_attachment

     

       111
       111
       +
         |> Jsont.Object.mem "preview" Jsont.string ~dec_absent:"" ~enc:preview

     

       112
       112
       +
         |> Jsont.Object.finish

     

       113
       113
       +
       

     

       114
       114
       +
       module Filter_condition = struct

     

       115
       115
       +
         type t = {

     

       116
       116
       +
           in_mailbox : Jmap_proto.Id.t option;

     

       117
       117
       +
           in_mailbox_other_than : Jmap_proto.Id.t list option;

     

       118
       118
       +
           before : Ptime.t option;

     

       119
       119
       +
           after : Ptime.t option;

     

       120
       120
       +
           min_size : int64 option;

     

       121
       121
       +
           max_size : int64 option;

     

       122
       122
       +
           all_in_thread_have_keyword : string option;

     

       123
       123
       +
           some_in_thread_have_keyword : string option;

     

       124
       124
       +
           none_in_thread_have_keyword : string option;

     

       125
       125
       +
           has_keyword : string option;

     

       126
       126
       +
           not_keyword : string option;

     

       127
       127
       +
           has_attachment : bool option;

     

       128
       128
       +
           text : string option;

     

       129
       129
       +
           from : string option;

     

       130
       130
       +
           to_ : string option;

     

       131
       131
       +
           cc : string option;

     

       132
       132
       +
           bcc : string option;

     

       133
       133
       +
           subject : string option;

     

       134
       134
       +
           body : string option;

     

       135
       135
       +
           header : (string * string option) option;

     

       136
       136
       +
         }

     

       137
       137
       +
       

     

       138
       138
       +
         let make in_mailbox in_mailbox_other_than before after min_size max_size

     

       139
       139
       +
             all_in_thread_have_keyword some_in_thread_have_keyword

     

       140
       140
       +
             none_in_thread_have_keyword has_keyword not_keyword has_attachment

     

       141
       141
       +
             text from to_ cc bcc subject body header =

     

       142
       142
       +
           { in_mailbox; in_mailbox_other_than; before; after; min_size; max_size;

     

       143
       143
       +
             all_in_thread_have_keyword; some_in_thread_have_keyword;

     

       144
       144
       +
             none_in_thread_have_keyword; has_keyword; not_keyword; has_attachment;

     

       145
       145
       +
             text; from; to_; cc; bcc; subject; body; header }

     

       146
       146
       +
       

     

       147
       147
       +
         (* Header filter is encoded as [name] or [name, value] array *)

     

       148
       148
       +
         let header_jsont =

     

       149
       149
       +
           let kind = "HeaderFilter" in

     

       150
       150
       +
           let dec json =

     

       151
       151
       +
             match json with

     

       152
       152
       +
             | Jsont.Array ([Jsont.String (name, _)], _) ->

     

       153
       153
       +
               (name, None)

     

       154
       154
       +
             | Jsont.Array ([Jsont.String (name, _); Jsont.String (value, _)], _) ->

     

       155
       155
       +
               (name, Some value)

     

       156
       156
       +
             | _ ->

     

       157
       157
       +
               Jsont.Error.msgf Jsont.Meta.none "%s: expected [name] or [name, value]" kind

     

       158
       158
       +
           in

     

       159
       159
       +
           let enc (name, value) =

     

       160
       160
       +
             match value with

     

       161
       161
       +
             | None -> Jsont.Array ([Jsont.String (name, Jsont.Meta.none)], Jsont.Meta.none)

     

       162
       162
       +
             | Some v -> Jsont.Array ([Jsont.String (name, Jsont.Meta.none); Jsont.String (v, Jsont.Meta.none)], Jsont.Meta.none)

     

       163
       163
       +
           in

     

       164
       164
       +
           Jsont.map ~kind ~dec ~enc Jsont.json

     

       165
       165
       +
       

     

       166
       166
       +
         let jsont =

     

       167
       167
       +
           let kind = "EmailFilterCondition" in

     

       168
       168
       +
           Jsont.Object.map ~kind make

     

       169
       169
       +
           |> Jsont.Object.opt_mem "inMailbox" Jmap_proto.Id.jsont ~enc:(fun f -> f.in_mailbox)

     

       170
       170
       +
           |> Jsont.Object.opt_mem "inMailboxOtherThan" (Jsont.list Jmap_proto.Id.jsont) ~enc:(fun f -> f.in_mailbox_other_than)

     

       171
       171
       +
           |> Jsont.Object.opt_mem "before" Jmap_proto.Date.Utc.jsont ~enc:(fun f -> f.before)

     

       172
       172
       +
           |> Jsont.Object.opt_mem "after" Jmap_proto.Date.Utc.jsont ~enc:(fun f -> f.after)

     

       173
       173
       +
           |> Jsont.Object.opt_mem "minSize" Jmap_proto.Int53.Unsigned.jsont ~enc:(fun f -> f.min_size)

     

       174
       174
       +
           |> Jsont.Object.opt_mem "maxSize" Jmap_proto.Int53.Unsigned.jsont ~enc:(fun f -> f.max_size)

     

       175
       175
       +
           |> Jsont.Object.opt_mem "allInThreadHaveKeyword" Jsont.string ~enc:(fun f -> f.all_in_thread_have_keyword)

     

       176
       176
       +
           |> Jsont.Object.opt_mem "someInThreadHaveKeyword" Jsont.string ~enc:(fun f -> f.some_in_thread_have_keyword)

     

       177
       177
       +
           |> Jsont.Object.opt_mem "noneInThreadHaveKeyword" Jsont.string ~enc:(fun f -> f.none_in_thread_have_keyword)

     

       178
       178
       +
           |> Jsont.Object.opt_mem "hasKeyword" Jsont.string ~enc:(fun f -> f.has_keyword)

     

       179
       179
       +
           |> Jsont.Object.opt_mem "notKeyword" Jsont.string ~enc:(fun f -> f.not_keyword)

     

       180
       180
       +
           |> Jsont.Object.opt_mem "hasAttachment" Jsont.bool ~enc:(fun f -> f.has_attachment)

     

       181
       181
       +
           |> Jsont.Object.opt_mem "text" Jsont.string ~enc:(fun f -> f.text)

     

       182
       182
       +
           |> Jsont.Object.opt_mem "from" Jsont.string ~enc:(fun f -> f.from)

     

       183
       183
       +
           |> Jsont.Object.opt_mem "to" Jsont.string ~enc:(fun f -> f.to_)

     

       184
       184
       +
           |> Jsont.Object.opt_mem "cc" Jsont.string ~enc:(fun f -> f.cc)

     

       185
       185
       +
           |> Jsont.Object.opt_mem "bcc" Jsont.string ~enc:(fun f -> f.bcc)

     

       186
       186
       +
           |> Jsont.Object.opt_mem "subject" Jsont.string ~enc:(fun f -> f.subject)

     

       187
       187
       +
           |> Jsont.Object.opt_mem "body" Jsont.string ~enc:(fun f -> f.body)

     

       188
       188
       +
           |> Jsont.Object.opt_mem "header" header_jsont ~enc:(fun f -> f.header)

     

       189
       189
       +
           |> Jsont.Object.finish

     

       190
       190
       +
       end

     

       191
       191
       +
       

     

       192
       192
       +
       type get_args_extra = {

     

       193
       193
       +
         body_properties : string list option;

     

       194
       194
       +
         fetch_text_body_values : bool;

     

       195
       195
       +
         fetch_html_body_values : bool;

     

       196
       196
       +
         fetch_all_body_values : bool;

     

       197
       197
       +
         max_body_value_bytes : int64 option;

     

       198
       198
       +
       }

     

       199
       199
       +
       

     

       200
       200
       +
       let get_args_extra_make body_properties fetch_text_body_values

     

       201
       201
       +
           fetch_html_body_values fetch_all_body_values max_body_value_bytes =

     

       202
       202
       +
         { body_properties; fetch_text_body_values; fetch_html_body_values;

     

       203
       203
       +
           fetch_all_body_values; max_body_value_bytes }

     

       204
       204
       +
       

     

       205
       205
       +
       let get_args_extra_jsont =

     

       206
       206
       +
         let kind = "Email/get extra args" in

     

       207
       207
       +
         Jsont.Object.map ~kind get_args_extra_make

     

       208
       208
       +
         |> Jsont.Object.opt_mem "bodyProperties" (Jsont.list Jsont.string) ~enc:(fun a -> a.body_properties)

     

       209
       209
       +
         |> Jsont.Object.mem "fetchTextBodyValues" Jsont.bool ~dec_absent:false

     

       210
       210
       +
              ~enc:(fun a -> a.fetch_text_body_values) ~enc_omit:(fun b -> not b)

     

       211
       211
       +
         |> Jsont.Object.mem "fetchHTMLBodyValues" Jsont.bool ~dec_absent:false

     

       212
       212
       +
              ~enc:(fun a -> a.fetch_html_body_values) ~enc_omit:(fun b -> not b)

     

       213
       213
       +
         |> Jsont.Object.mem "fetchAllBodyValues" Jsont.bool ~dec_absent:false

     

       214
       214
       +
              ~enc:(fun a -> a.fetch_all_body_values) ~enc_omit:(fun b -> not b)

     

       215
       215
       +
         |> Jsont.Object.opt_mem "maxBodyValueBytes" Jmap_proto.Int53.Unsigned.jsont ~enc:(fun a -> a.max_body_value_bytes)

     

       216
       216
       +
         |> Jsont.Object.finish

+146

proto/mail/email.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Email type as defined in RFC 8621 Section 4 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Standard Keywords} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** Standard email keywords per RFC 8621. *)

     

       11
       11
       +
       module Keyword : sig

     

       12
       12
       +
         val draft : string

     

       13
       13
       +
         (** ["$draft"] *)

     

       14
       14
       +
       

     

       15
       15
       +
         val seen : string

     

       16
       16
       +
         (** ["$seen"] *)

     

       17
       17
       +
       

     

       18
       18
       +
         val flagged : string

     

       19
       19
       +
         (** ["$flagged"] *)

     

       20
       20
       +
       

     

       21
       21
       +
         val answered : string

     

       22
       22
       +
         (** ["$answered"] *)

     

       23
       23
       +
       

     

       24
       24
       +
         val forwarded : string

     

       25
       25
       +
         (** ["$forwarded"] *)

     

       26
       26
       +
       

     

       27
       27
       +
         val phishing : string

     

       28
       28
       +
         (** ["$phishing"] *)

     

       29
       29
       +
       

     

       30
       30
       +
         val junk : string

     

       31
       31
       +
         (** ["$junk"] *)

     

       32
       32
       +
       

     

       33
       33
       +
         val not_junk : string

     

       34
       34
       +
         (** ["$notjunk"] *)

     

       35
       35
       +
       end

     

       36
       36
       +
       

     

       37
       37
       +
       (** {1 Email Object} *)

     

       38
       38
       +
       

     

       39
       39
       +
       type t = {

     

       40
       40
       +
         (* Metadata - server-set, immutable *)

     

       41
       41
       +
         id : Jmap_proto.Id.t;

     

       42
       42
       +
         blob_id : Jmap_proto.Id.t;

     

       43
       43
       +
         thread_id : Jmap_proto.Id.t;

     

       44
       44
       +
         size : int64;

     

       45
       45
       +
         received_at : Ptime.t;

     

       46
       46
       +
       

     

       47
       47
       +
         (* Metadata - mutable *)

     

       48
       48
       +
         mailbox_ids : (Jmap_proto.Id.t * bool) list;

     

       49
       49
       +
         keywords : (string * bool) list;

     

       50
       50
       +
       

     

       51
       51
       +
         (* Parsed headers *)

     

       52
       52
       +
         message_id : string list option;

     

       53
       53
       +
         in_reply_to : string list option;

     

       54
       54
       +
         references : string list option;

     

       55
       55
       +
         sender : Email_address.t list option;

     

       56
       56
       +
         from : Email_address.t list option;

     

       57
       57
       +
         to_ : Email_address.t list option;

     

       58
       58
       +
         cc : Email_address.t list option;

     

       59
       59
       +
         bcc : Email_address.t list option;

     

       60
       60
       +
         reply_to : Email_address.t list option;

     

       61
       61
       +
         subject : string option;

     

       62
       62
       +
         sent_at : Ptime.t option;

     

       63
       63
       +
       

     

       64
       64
       +
         (* Raw headers *)

     

       65
       65
       +
         headers : Email_header.t list option;

     

       66
       66
       +
       

     

       67
       67
       +
         (* Body structure *)

     

       68
       68
       +
         body_structure : Email_body.Part.t option;

     

       69
       69
       +
         body_values : (string * Email_body.Value.t) list option;

     

       70
       70
       +
         text_body : Email_body.Part.t list option;

     

       71
       71
       +
         html_body : Email_body.Part.t list option;

     

       72
       72
       +
         attachments : Email_body.Part.t list option;

     

       73
       73
       +
         has_attachment : bool;

     

       74
       74
       +
         preview : string;

     

       75
       75
       +
       }

     

       76
       76
       +
       

     

       77
       77
       +
       val id : t -> Jmap_proto.Id.t

     

       78
       78
       +
       val blob_id : t -> Jmap_proto.Id.t

     

       79
       79
       +
       val thread_id : t -> Jmap_proto.Id.t

     

       80
       80
       +
       val size : t -> int64

     

       81
       81
       +
       val received_at : t -> Ptime.t

     

       82
       82
       +
       val mailbox_ids : t -> (Jmap_proto.Id.t * bool) list

     

       83
       83
       +
       val keywords : t -> (string * bool) list

     

       84
       84
       +
       val message_id : t -> string list option

     

       85
       85
       +
       val in_reply_to : t -> string list option

     

       86
       86
       +
       val references : t -> string list option

     

       87
       87
       +
       val sender : t -> Email_address.t list option

     

       88
       88
       +
       val from : t -> Email_address.t list option

     

       89
       89
       +
       val to_ : t -> Email_address.t list option

     

       90
       90
       +
       val cc : t -> Email_address.t list option

     

       91
       91
       +
       val bcc : t -> Email_address.t list option

     

       92
       92
       +
       val reply_to : t -> Email_address.t list option

     

       93
       93
       +
       val subject : t -> string option

     

       94
       94
       +
       val sent_at : t -> Ptime.t option

     

       95
       95
       +
       val headers : t -> Email_header.t list option

     

       96
       96
       +
       val body_structure : t -> Email_body.Part.t option

     

       97
       97
       +
       val body_values : t -> (string * Email_body.Value.t) list option

     

       98
       98
       +
       val text_body : t -> Email_body.Part.t list option

     

       99
       99
       +
       val html_body : t -> Email_body.Part.t list option

     

       100
       100
       +
       val attachments : t -> Email_body.Part.t list option

     

       101
       101
       +
       val has_attachment : t -> bool

     

       102
       102
       +
       val preview : t -> string

     

       103
       103
       +
       

     

       104
       104
       +
       val jsont : t Jsont.t

     

       105
       105
       +
       

     

       106
       106
       +
       (** {1 Email Filter Conditions} *)

     

       107
       107
       +
       

     

       108
       108
       +
       module Filter_condition : sig

     

       109
       109
       +
         type t = {

     

       110
       110
       +
           in_mailbox : Jmap_proto.Id.t option;

     

       111
       111
       +
           in_mailbox_other_than : Jmap_proto.Id.t list option;

     

       112
       112
       +
           before : Ptime.t option;

     

       113
       113
       +
           after : Ptime.t option;

     

       114
       114
       +
           min_size : int64 option;

     

       115
       115
       +
           max_size : int64 option;

     

       116
       116
       +
           all_in_thread_have_keyword : string option;

     

       117
       117
       +
           some_in_thread_have_keyword : string option;

     

       118
       118
       +
           none_in_thread_have_keyword : string option;

     

       119
       119
       +
           has_keyword : string option;

     

       120
       120
       +
           not_keyword : string option;

     

       121
       121
       +
           has_attachment : bool option;

     

       122
       122
       +
           text : string option;

     

       123
       123
       +
           from : string option;

     

       124
       124
       +
           to_ : string option;

     

       125
       125
       +
           cc : string option;

     

       126
       126
       +
           bcc : string option;

     

       127
       127
       +
           subject : string option;

     

       128
       128
       +
           body : string option;

     

       129
       129
       +
           header : (string * string option) option;

     

       130
       130
       +
         }

     

       131
       131
       +
       

     

       132
       132
       +
         val jsont : t Jsont.t

     

       133
       133
       +
       end

     

       134
       134
       +
       

     

       135
       135
       +
       (** {1 Email/get Arguments} *)

     

       136
       136
       +
       

     

       137
       137
       +
       (** Extra arguments for Email/get beyond standard /get. *)

     

       138
       138
       +
       type get_args_extra = {

     

       139
       139
       +
         body_properties : string list option;

     

       140
       140
       +
         fetch_text_body_values : bool;

     

       141
       141
       +
         fetch_html_body_values : bool;

     

       142
       142
       +
         fetch_all_body_values : bool;

     

       143
       143
       +
         max_body_value_bytes : int64 option;

     

       144
       144
       +
       }

     

       145
       145
       +
       

     

       146
       146
       +
       val get_args_extra_jsont : get_args_extra Jsont.t

+53

proto/mail/email_address.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = {

     

       7
       7
       +
         name : string option;

     

       8
       8
       +
         email : string;

     

       9
       9
       +
       }

     

       10
       10
       +
       

     

       11
       11
       +
       let create ?name email = { name; email }

     

       12
       12
       +
       

     

       13
       13
       +
       let name t = t.name

     

       14
       14
       +
       let email t = t.email

     

       15
       15
       +
       

     

       16
       16
       +
       let equal a b = a.email = b.email

     

       17
       17
       +
       

     

       18
       18
       +
       let pp ppf t =

     

       19
       19
       +
         match t.name with

     

       20
       20
       +
         | Some name -> Format.fprintf ppf "%s <%s>" name t.email

     

       21
       21
       +
         | None -> Format.pp_print_string ppf t.email

     

       22
       22
       +
       

     

       23
       23
       +
       let make name email = { name; email }

     

       24
       24
       +
       

     

       25
       25
       +
       let jsont =

     

       26
       26
       +
         let kind = "EmailAddress" in

     

       27
       27
       +
         Jsont.Object.map ~kind make

     

       28
       28
       +
         |> Jsont.Object.opt_mem "name" Jsont.string ~enc:name

     

       29
       29
       +
         |> Jsont.Object.mem "email" Jsont.string ~enc:email

     

       30
       30
       +
         |> Jsont.Object.finish

     

       31
       31
       +
       

     

       32
       32
       +
       module Group = struct

     

       33
       33
       +
         type address = t

     

       34
       34
       +
       

     

       35
       35
       +
         type t = {

     

       36
       36
       +
           name : string option;

     

       37
       37
       +
           addresses : address list;

     

       38
       38
       +
         }

     

       39
       39
       +
       

     

       40
       40
       +
         let create ?name addresses = { name; addresses }

     

       41
       41
       +
       

     

       42
       42
       +
         let name t = t.name

     

       43
       43
       +
         let addresses t = t.addresses

     

       44
       44
       +
       

     

       45
       45
       +
         let make name addresses = { name; addresses }

     

       46
       46
       +
       

     

       47
       47
       +
         let jsont =

     

       48
       48
       +
           let kind = "EmailAddressGroup" in

     

       49
       49
       +
           Jsont.Object.map ~kind make

     

       50
       50
       +
           |> Jsont.Object.opt_mem "name" Jsont.string ~enc:name

     

       51
       51
       +
           |> Jsont.Object.mem "addresses" (Jsont.list jsont) ~enc:addresses

     

       52
       52
       +
           |> Jsont.Object.finish

     

       53
       53
       +
       end

+49

proto/mail/email_address.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Email address types as defined in RFC 8621 Section 4.1.2.3 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Email Address} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** An email address with optional display name. *)

     

       11
       11
       +
       type t = {

     

       12
       12
       +
         name : string option;

     

       13
       13
       +
         (** The display name (from the phrase in RFC 5322). *)

     

       14
       14
       +
         email : string;

     

       15
       15
       +
         (** The email address (addr-spec in RFC 5322). *)

     

       16
       16
       +
       }

     

       17
       17
       +
       

     

       18
       18
       +
       val create : ?name:string -> string -> t

     

       19
       19
       +
       (** [create ?name email] creates an email address. *)

     

       20
       20
       +
       

     

       21
       21
       +
       val name : t -> string option

     

       22
       22
       +
       val email : t -> string

     

       23
       23
       +
       

     

       24
       24
       +
       val equal : t -> t -> bool

     

       25
       25
       +
       val pp : Format.formatter -> t -> unit

     

       26
       26
       +
       

     

       27
       27
       +
       val jsont : t Jsont.t

     

       28
       28
       +
       (** JSON codec for email addresses. *)

     

       29
       29
       +
       

     

       30
       30
       +
       (** {1 Address Groups} *)

     

       31
       31
       +
       

     

       32
       32
       +
       (** A group of email addresses with an optional group name. *)

     

       33
       33
       +
       module Group : sig

     

       34
       34
       +
         type address = t

     

       35
       35
       +
       

     

       36
       36
       +
         type t = {

     

       37
       37
       +
           name : string option;

     

       38
       38
       +
           (** The group name, or [None] for ungrouped addresses. *)

     

       39
       39
       +
           addresses : address list;

     

       40
       40
       +
           (** The addresses in this group. *)

     

       41
       41
       +
         }

     

       42
       42
       +
       

     

       43
       43
       +
         val create : ?name:string -> address list -> t

     

       44
       44
       +
       

     

       45
       45
       +
         val name : t -> string option

     

       46
       46
       +
         val addresses : t -> address list

     

       47
       47
       +
       

     

       48
       48
       +
         val jsont : t Jsont.t

     

       49
       49
       +
       end

+85

proto/mail/email_body.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       module Value = struct

     

       7
       7
       +
         type t = {

     

       8
       8
       +
           value : string;

     

       9
       9
       +
           is_encoding_problem : bool;

     

       10
       10
       +
           is_truncated : bool;

     

       11
       11
       +
         }

     

       12
       12
       +
       

     

       13
       13
       +
         let value t = t.value

     

       14
       14
       +
         let is_encoding_problem t = t.is_encoding_problem

     

       15
       15
       +
         let is_truncated t = t.is_truncated

     

       16
       16
       +
       

     

       17
       17
       +
         let make value is_encoding_problem is_truncated =

     

       18
       18
       +
           { value; is_encoding_problem; is_truncated }

     

       19
       19
       +
       

     

       20
       20
       +
         let jsont =

     

       21
       21
       +
           let kind = "EmailBodyValue" in

     

       22
       22
       +
           Jsont.Object.map ~kind make

     

       23
       23
       +
           |> Jsont.Object.mem "value" Jsont.string ~enc:value

     

       24
       24
       +
           |> Jsont.Object.mem "isEncodingProblem" Jsont.bool ~dec_absent:false

     

       25
       25
       +
                ~enc:is_encoding_problem ~enc_omit:(fun b -> not b)

     

       26
       26
       +
           |> Jsont.Object.mem "isTruncated" Jsont.bool ~dec_absent:false

     

       27
       27
       +
                ~enc:is_truncated ~enc_omit:(fun b -> not b)

     

       28
       28
       +
           |> Jsont.Object.finish

     

       29
       29
       +
       end

     

       30
       30
       +
       

     

       31
       31
       +
       module Part = struct

     

       32
       32
       +
         type t = {

     

       33
       33
       +
           part_id : string option;

     

       34
       34
       +
           blob_id : Jmap_proto.Id.t option;

     

       35
       35
       +
           size : int64 option;

     

       36
       36
       +
           headers : Email_header.t list option;

     

       37
       37
       +
           name : string option;

     

       38
       38
       +
           type_ : string;

     

       39
       39
       +
           charset : string option;

     

       40
       40
       +
           disposition : string option;

     

       41
       41
       +
           cid : string option;

     

       42
       42
       +
           language : string list option;

     

       43
       43
       +
           location : string option;

     

       44
       44
       +
           sub_parts : t list option;

     

       45
       45
       +
         }

     

       46
       46
       +
       

     

       47
       47
       +
         let part_id t = t.part_id

     

       48
       48
       +
         let blob_id t = t.blob_id

     

       49
       49
       +
         let size t = t.size

     

       50
       50
       +
         let headers t = t.headers

     

       51
       51
       +
         let name t = t.name

     

       52
       52
       +
         let type_ t = t.type_

     

       53
       53
       +
         let charset t = t.charset

     

       54
       54
       +
         let disposition t = t.disposition

     

       55
       55
       +
         let cid t = t.cid

     

       56
       56
       +
         let language t = t.language

     

       57
       57
       +
         let location t = t.location

     

       58
       58
       +
         let sub_parts t = t.sub_parts

     

       59
       59
       +
       

     

       60
       60
       +
         let rec jsont =

     

       61
       61
       +
           let kind = "EmailBodyPart" in

     

       62
       62
       +
           let make part_id blob_id size headers name type_ charset disposition

     

       63
       63
       +
               cid language location sub_parts =

     

       64
       64
       +
             { part_id; blob_id; size; headers; name; type_; charset; disposition;

     

       65
       65
       +
               cid; language; location; sub_parts }

     

       66
       66
       +
           in

     

       67
       67
       +
           lazy (

     

       68
       68
       +
             Jsont.Object.map ~kind make

     

       69
       69
       +
             |> Jsont.Object.opt_mem "partId" Jsont.string ~enc:part_id

     

       70
       70
       +
             |> Jsont.Object.opt_mem "blobId" Jmap_proto.Id.jsont ~enc:blob_id

     

       71
       71
       +
             |> Jsont.Object.opt_mem "size" Jmap_proto.Int53.Unsigned.jsont ~enc:size

     

       72
       72
       +
             |> Jsont.Object.opt_mem "headers" (Jsont.list Email_header.jsont) ~enc:headers

     

       73
       73
       +
             |> Jsont.Object.opt_mem "name" Jsont.string ~enc:name

     

       74
       74
       +
             |> Jsont.Object.mem "type" Jsont.string ~enc:type_

     

       75
       75
       +
             |> Jsont.Object.opt_mem "charset" Jsont.string ~enc:charset

     

       76
       76
       +
             |> Jsont.Object.opt_mem "disposition" Jsont.string ~enc:disposition

     

       77
       77
       +
             |> Jsont.Object.opt_mem "cid" Jsont.string ~enc:cid

     

       78
       78
       +
             |> Jsont.Object.opt_mem "language" (Jsont.list Jsont.string) ~enc:language

     

       79
       79
       +
             |> Jsont.Object.opt_mem "location" Jsont.string ~enc:location

     

       80
       80
       +
             |> Jsont.Object.opt_mem "subParts" (Jsont.list (Jsont.rec' jsont)) ~enc:sub_parts

     

       81
       81
       +
             |> Jsont.Object.finish

     

       82
       82
       +
           )

     

       83
       83
       +
       

     

       84
       84
       +
         let jsont = Lazy.force jsont

     

       85
       85
       +
       end

+73

proto/mail/email_body.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Email body types as defined in RFC 8621 Section 4.1.4 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Body Value} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** Fetched body part content. *)

     

       11
       11
       +
       module Value : sig

     

       12
       12
       +
         type t = {

     

       13
       13
       +
           value : string;

     

       14
       14
       +
           (** The body part content. *)

     

       15
       15
       +
           is_encoding_problem : bool;

     

       16
       16
       +
           (** True if there was a problem decoding the content transfer encoding. *)

     

       17
       17
       +
           is_truncated : bool;

     

       18
       18
       +
           (** True if the value was truncated. *)

     

       19
       19
       +
         }

     

       20
       20
       +
       

     

       21
       21
       +
         val value : t -> string

     

       22
       22
       +
         val is_encoding_problem : t -> bool

     

       23
       23
       +
         val is_truncated : t -> bool

     

       24
       24
       +
       

     

       25
       25
       +
         val jsont : t Jsont.t

     

       26
       26
       +
       end

     

       27
       27
       +
       

     

       28
       28
       +
       (** {1 Body Part} *)

     

       29
       29
       +
       

     

       30
       30
       +
       (** An email body part structure. *)

     

       31
       31
       +
       module Part : sig

     

       32
       32
       +
         type t = {

     

       33
       33
       +
           part_id : string option;

     

       34
       34
       +
           (** Identifier for this part, used to fetch content. *)

     

       35
       35
       +
           blob_id : Jmap_proto.Id.t option;

     

       36
       36
       +
           (** Blob id if the part can be fetched as a blob. *)

     

       37
       37
       +
           size : int64 option;

     

       38
       38
       +
           (** Size in octets. *)

     

       39
       39
       +
           headers : Email_header.t list option;

     

       40
       40
       +
           (** Headers specific to this part. *)

     

       41
       41
       +
           name : string option;

     

       42
       42
       +
           (** Suggested filename from Content-Disposition. *)

     

       43
       43
       +
           type_ : string;

     

       44
       44
       +
           (** MIME type (e.g., "text/plain"). *)

     

       45
       45
       +
           charset : string option;

     

       46
       46
       +
           (** Character set parameter. *)

     

       47
       47
       +
           disposition : string option;

     

       48
       48
       +
           (** Content-Disposition value. *)

     

       49
       49
       +
           cid : string option;

     

       50
       50
       +
           (** Content-ID value. *)

     

       51
       51
       +
           language : string list option;

     

       52
       52
       +
           (** Content-Language values. *)

     

       53
       53
       +
           location : string option;

     

       54
       54
       +
           (** Content-Location value. *)

     

       55
       55
       +
           sub_parts : t list option;

     

       56
       56
       +
           (** Nested parts for multipart types. *)

     

       57
       57
       +
         }

     

       58
       58
       +
       

     

       59
       59
       +
         val part_id : t -> string option

     

       60
       60
       +
         val blob_id : t -> Jmap_proto.Id.t option

     

       61
       61
       +
         val size : t -> int64 option

     

       62
       62
       +
         val headers : t -> Email_header.t list option

     

       63
       63
       +
         val name : t -> string option

     

       64
       64
       +
         val type_ : t -> string

     

       65
       65
       +
         val charset : t -> string option

     

       66
       66
       +
         val disposition : t -> string option

     

       67
       67
       +
         val cid : t -> string option

     

       68
       68
       +
         val language : t -> string list option

     

       69
       69
       +
         val location : t -> string option

     

       70
       70
       +
         val sub_parts : t -> t list option

     

       71
       71
       +
       

     

       72
       72
       +
         val jsont : t Jsont.t

     

       73
       73
       +
       end

+39

proto/mail/email_header.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = {

     

       7
       7
       +
         name : string;

     

       8
       8
       +
         value : string;

     

       9
       9
       +
       }

     

       10
       10
       +
       

     

       11
       11
       +
       let create ~name ~value = { name; value }

     

       12
       12
       +
       

     

       13
       13
       +
       let name t = t.name

     

       14
       14
       +
       let value t = t.value

     

       15
       15
       +
       

     

       16
       16
       +
       let make name value = { name; value }

     

       17
       17
       +
       

     

       18
       18
       +
       let jsont =

     

       19
       19
       +
         let kind = "EmailHeader" in

     

       20
       20
       +
         Jsont.Object.map ~kind make

     

       21
       21
       +
         |> Jsont.Object.mem "name" Jsont.string ~enc:name

     

       22
       22
       +
         |> Jsont.Object.mem "value" Jsont.string ~enc:value

     

       23
       23
       +
         |> Jsont.Object.finish

     

       24
       24
       +
       

     

       25
       25
       +
       (* Header parsed forms - these are used with header:Name:form properties *)

     

       26
       26
       +
       

     

       27
       27
       +
       let raw_jsont = Jsont.string

     

       28
       28
       +
       

     

       29
       29
       +
       let text_jsont = Jsont.string

     

       30
       30
       +
       

     

       31
       31
       +
       let addresses_jsont = Jsont.list Email_address.jsont

     

       32
       32
       +
       

     

       33
       33
       +
       let grouped_addresses_jsont = Jsont.list Email_address.Group.jsont

     

       34
       34
       +
       

     

       35
       35
       +
       let message_ids_jsont = Jsont.list Jsont.string

     

       36
       36
       +
       

     

       37
       37
       +
       let date_jsont = Jmap_proto.Date.Rfc3339.jsont

     

       38
       38
       +
       

     

       39
       39
       +
       let urls_jsont = Jsont.list Jsont.string

+49

proto/mail/email_header.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Email header types as defined in RFC 8621 Section 4.1.2 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Raw Headers} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** A raw email header name-value pair. *)

     

       11
       11
       +
       type t = {

     

       12
       12
       +
         name : string;

     

       13
       13
       +
         (** The header field name. *)

     

       14
       14
       +
         value : string;

     

       15
       15
       +
         (** The raw header field value. *)

     

       16
       16
       +
       }

     

       17
       17
       +
       

     

       18
       18
       +
       val create : name:string -> value:string -> t

     

       19
       19
       +
       

     

       20
       20
       +
       val name : t -> string

     

       21
       21
       +
       val value : t -> string

     

       22
       22
       +
       

     

       23
       23
       +
       val jsont : t Jsont.t

     

       24
       24
       +
       

     

       25
       25
       +
       (** {1 Header Parsed Forms}

     

       26
       26
       +
       

     

       27
       27
       +
           RFC 8621 defines several parsed forms for headers.

     

       28
       28
       +
           These can be requested via the header:Name:form properties. *)

     

       29
       29
       +
       

     

       30
       30
       +
       (** The raw form - header value as-is. *)

     

       31
       31
       +
       val raw_jsont : string Jsont.t

     

       32
       32
       +
       

     

       33
       33
       +
       (** The text form - decoded and unfolded value. *)

     

       34
       34
       +
       val text_jsont : string Jsont.t

     

       35
       35
       +
       

     

       36
       36
       +
       (** The addresses form - list of email addresses. *)

     

       37
       37
       +
       val addresses_jsont : Email_address.t list Jsont.t

     

       38
       38
       +
       

     

       39
       39
       +
       (** The grouped addresses form - addresses with group info. *)

     

       40
       40
       +
       val grouped_addresses_jsont : Email_address.Group.t list Jsont.t

     

       41
       41
       +
       

     

       42
       42
       +
       (** The message IDs form - list of message-id strings. *)

     

       43
       43
       +
       val message_ids_jsont : string list Jsont.t

     

       44
       44
       +
       

     

       45
       45
       +
       (** The date form - parsed RFC 3339 date. *)

     

       46
       46
       +
       val date_jsont : Ptime.t Jsont.t

     

       47
       47
       +
       

     

       48
       48
       +
       (** The URLs form - list of URL strings. *)

     

       49
       49
       +
       val urls_jsont : string list Jsont.t

+40

proto/mail/identity.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = {

     

       7
       7
       +
         id : Jmap_proto.Id.t;

     

       8
       8
       +
         name : string;

     

       9
       9
       +
         email : string;

     

       10
       10
       +
         reply_to : Email_address.t list option;

     

       11
       11
       +
         bcc : Email_address.t list option;

     

       12
       12
       +
         text_signature : string;

     

       13
       13
       +
         html_signature : string;

     

       14
       14
       +
         may_delete : bool;

     

       15
       15
       +
       }

     

       16
       16
       +
       

     

       17
       17
       +
       let id t = t.id

     

       18
       18
       +
       let name t = t.name

     

       19
       19
       +
       let email t = t.email

     

       20
       20
       +
       let reply_to t = t.reply_to

     

       21
       21
       +
       let bcc t = t.bcc

     

       22
       22
       +
       let text_signature t = t.text_signature

     

       23
       23
       +
       let html_signature t = t.html_signature

     

       24
       24
       +
       let may_delete t = t.may_delete

     

       25
       25
       +
       

     

       26
       26
       +
       let make id name email reply_to bcc text_signature html_signature may_delete =

     

       27
       27
       +
         { id; name; email; reply_to; bcc; text_signature; html_signature; may_delete }

     

       28
       28
       +
       

     

       29
       29
       +
       let jsont =

     

       30
       30
       +
         let kind = "Identity" in

     

       31
       31
       +
         Jsont.Object.map ~kind make

     

       32
       32
       +
         |> Jsont.Object.mem "id" Jmap_proto.Id.jsont ~enc:id

     

       33
       33
       +
         |> Jsont.Object.mem "name" Jsont.string ~dec_absent:"" ~enc:name

     

       34
       34
       +
         |> Jsont.Object.mem "email" Jsont.string ~enc:email

     

       35
       35
       +
         |> Jsont.Object.opt_mem "replyTo" (Jsont.list Email_address.jsont) ~enc:reply_to

     

       36
       36
       +
         |> Jsont.Object.opt_mem "bcc" (Jsont.list Email_address.jsont) ~enc:bcc

     

       37
       37
       +
         |> Jsont.Object.mem "textSignature" Jsont.string ~dec_absent:"" ~enc:text_signature

     

       38
       38
       +
         |> Jsont.Object.mem "htmlSignature" Jsont.string ~dec_absent:"" ~enc:html_signature

     

       39
       39
       +
         |> Jsont.Object.mem "mayDelete" Jsont.bool ~enc:may_delete

     

       40
       40
       +
         |> Jsont.Object.finish

+36

proto/mail/identity.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Identity type as defined in RFC 8621 Section 6 *)

     

       7
       7
       +
       

     

       8
       8
       +
       type t = {

     

       9
       9
       +
         id : Jmap_proto.Id.t;

     

       10
       10
       +
         (** Server-assigned identity id. *)

     

       11
       11
       +
         name : string;

     

       12
       12
       +
         (** Display name for sent emails. *)

     

       13
       13
       +
         email : string;

     

       14
       14
       +
         (** The email address to use. *)

     

       15
       15
       +
         reply_to : Email_address.t list option;

     

       16
       16
       +
         (** Default Reply-To addresses. *)

     

       17
       17
       +
         bcc : Email_address.t list option;

     

       18
       18
       +
         (** Default BCC addresses. *)

     

       19
       19
       +
         text_signature : string;

     

       20
       20
       +
         (** Plain text signature. *)

     

       21
       21
       +
         html_signature : string;

     

       22
       22
       +
         (** HTML signature. *)

     

       23
       23
       +
         may_delete : bool;

     

       24
       24
       +
         (** Whether the user may delete this identity. *)

     

       25
       25
       +
       }

     

       26
       26
       +
       

     

       27
       27
       +
       val id : t -> Jmap_proto.Id.t

     

       28
       28
       +
       val name : t -> string

     

       29
       29
       +
       val email : t -> string

     

       30
       30
       +
       val reply_to : t -> Email_address.t list option

     

       31
       31
       +
       val bcc : t -> Email_address.t list option

     

       32
       32
       +
       val text_signature : t -> string

     

       33
       33
       +
       val html_signature : t -> string

     

       34
       34
       +
       val may_delete : t -> bool

     

       35
       35
       +
       

     

       36
       36
       +
       val jsont : t Jsont.t

+20

proto/mail/jmap_mail.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP Mail Types (RFC 8621)

     

       7
       7
       +
       

     

       8
       8
       +
           This module re-exports all JMAP mail protocol types. *)

     

       9
       9
       +
       

     

       10
       10
       +
       module Email_address = Email_address

     

       11
       11
       +
       module Email_header = Email_header

     

       12
       12
       +
       module Email_body = Email_body

     

       13
       13
       +
       module Mailbox = Mailbox

     

       14
       14
       +
       module Thread = Thread

     

       15
       15
       +
       module Email = Email

     

       16
       16
       +
       module Search_snippet = Search_snippet

     

       17
       17
       +
       module Identity = Identity

     

       18
       18
       +
       module Submission = Submission

     

       19
       19
       +
       module Vacation = Vacation

     

       20
       20
       +
       module Mail_filter = Mail_filter

+16

proto/mail/mail_filter.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type email_filter = Email.Filter_condition.t Jmap_proto.Filter.filter

     

       7
       7
       +
       

     

       8
       8
       +
       let email_filter_jsont = Jmap_proto.Filter.filter_jsont Email.Filter_condition.jsont

     

       9
       9
       +
       

     

       10
       10
       +
       type mailbox_filter = Mailbox.Filter_condition.t Jmap_proto.Filter.filter

     

       11
       11
       +
       

     

       12
       12
       +
       let mailbox_filter_jsont = Jmap_proto.Filter.filter_jsont Mailbox.Filter_condition.jsont

     

       13
       13
       +
       

     

       14
       14
       +
       type submission_filter = Submission.Filter_condition.t Jmap_proto.Filter.filter

     

       15
       15
       +
       

     

       16
       16
       +
       let submission_filter_jsont = Jmap_proto.Filter.filter_jsont Submission.Filter_condition.jsont

+21

proto/mail/mail_filter.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Mail-specific filter types *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** Email filter with Email-specific conditions. *)

     

       9
       9
       +
       type email_filter = Email.Filter_condition.t Jmap_proto.Filter.filter

     

       10
       10
       +
       

     

       11
       11
       +
       val email_filter_jsont : email_filter Jsont.t

     

       12
       12
       +
       

     

       13
       13
       +
       (** Mailbox filter with Mailbox-specific conditions. *)

     

       14
       14
       +
       type mailbox_filter = Mailbox.Filter_condition.t Jmap_proto.Filter.filter

     

       15
       15
       +
       

     

       16
       16
       +
       val mailbox_filter_jsont : mailbox_filter Jsont.t

     

       17
       17
       +
       

     

       18
       18
       +
       (** EmailSubmission filter with Submission-specific conditions. *)

     

       19
       19
       +
       type submission_filter = Submission.Filter_condition.t Jmap_proto.Filter.filter

     

       20
       20
       +
       

     

       21
       21
       +
       val submission_filter_jsont : submission_filter Jsont.t

+165

proto/mail/mailbox.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       module Rights = struct

     

       7
       7
       +
         type t = {

     

       8
       8
       +
           may_read_items : bool;

     

       9
       9
       +
           may_add_items : bool;

     

       10
       10
       +
           may_remove_items : bool;

     

       11
       11
       +
           may_set_seen : bool;

     

       12
       12
       +
           may_set_keywords : bool;

     

       13
       13
       +
           may_create_child : bool;

     

       14
       14
       +
           may_rename : bool;

     

       15
       15
       +
           may_delete : bool;

     

       16
       16
       +
           may_submit : bool;

     

       17
       17
       +
         }

     

       18
       18
       +
       

     

       19
       19
       +
         let may_read_items t = t.may_read_items

     

       20
       20
       +
         let may_add_items t = t.may_add_items

     

       21
       21
       +
         let may_remove_items t = t.may_remove_items

     

       22
       22
       +
         let may_set_seen t = t.may_set_seen

     

       23
       23
       +
         let may_set_keywords t = t.may_set_keywords

     

       24
       24
       +
         let may_create_child t = t.may_create_child

     

       25
       25
       +
         let may_rename t = t.may_rename

     

       26
       26
       +
         let may_delete t = t.may_delete

     

       27
       27
       +
         let may_submit t = t.may_submit

     

       28
       28
       +
       

     

       29
       29
       +
         let make may_read_items may_add_items may_remove_items may_set_seen

     

       30
       30
       +
             may_set_keywords may_create_child may_rename may_delete may_submit =

     

       31
       31
       +
           { may_read_items; may_add_items; may_remove_items; may_set_seen;

     

       32
       32
       +
             may_set_keywords; may_create_child; may_rename; may_delete; may_submit }

     

       33
       33
       +
       

     

       34
       34
       +
         let jsont =

     

       35
       35
       +
           let kind = "MailboxRights" in

     

       36
       36
       +
           Jsont.Object.map ~kind make

     

       37
       37
       +
           |> Jsont.Object.mem "mayReadItems" Jsont.bool ~enc:may_read_items

     

       38
       38
       +
           |> Jsont.Object.mem "mayAddItems" Jsont.bool ~enc:may_add_items

     

       39
       39
       +
           |> Jsont.Object.mem "mayRemoveItems" Jsont.bool ~enc:may_remove_items

     

       40
       40
       +
           |> Jsont.Object.mem "maySetSeen" Jsont.bool ~enc:may_set_seen

     

       41
       41
       +
           |> Jsont.Object.mem "maySetKeywords" Jsont.bool ~enc:may_set_keywords

     

       42
       42
       +
           |> Jsont.Object.mem "mayCreateChild" Jsont.bool ~enc:may_create_child

     

       43
       43
       +
           |> Jsont.Object.mem "mayRename" Jsont.bool ~enc:may_rename

     

       44
       44
       +
           |> Jsont.Object.mem "mayDelete" Jsont.bool ~enc:may_delete

     

       45
       45
       +
           |> Jsont.Object.mem "maySubmit" Jsont.bool ~enc:may_submit

     

       46
       46
       +
           |> Jsont.Object.finish

     

       47
       47
       +
       end

     

       48
       48
       +
       

     

       49
       49
       +
       type role =

     

       50
       50
       +
         | All

     

       51
       51
       +
         | Archive

     

       52
       52
       +
         | Drafts

     

       53
       53
       +
         | Flagged

     

       54
       54
       +
         | Important

     

       55
       55
       +
         | Inbox

     

       56
       56
       +
         | Junk

     

       57
       57
       +
         | Sent

     

       58
       58
       +
         | Subscribed

     

       59
       59
       +
         | Trash

     

       60
       60
       +
         | Other of string

     

       61
       61
       +
       

     

       62
       62
       +
       let role_to_string = function

     

       63
       63
       +
         | All -> "all"

     

       64
       64
       +
         | Archive -> "archive"

     

       65
       65
       +
         | Drafts -> "drafts"

     

       66
       66
       +
         | Flagged -> "flagged"

     

       67
       67
       +
         | Important -> "important"

     

       68
       68
       +
         | Inbox -> "inbox"

     

       69
       69
       +
         | Junk -> "junk"

     

       70
       70
       +
         | Sent -> "sent"

     

       71
       71
       +
         | Subscribed -> "subscribed"

     

       72
       72
       +
         | Trash -> "trash"

     

       73
       73
       +
         | Other s -> s

     

       74
       74
       +
       

     

       75
       75
       +
       let role_of_string = function

     

       76
       76
       +
         | "all" -> All

     

       77
       77
       +
         | "archive" -> Archive

     

       78
       78
       +
         | "drafts" -> Drafts

     

       79
       79
       +
         | "flagged" -> Flagged

     

       80
       80
       +
         | "important" -> Important

     

       81
       81
       +
         | "inbox" -> Inbox

     

       82
       82
       +
         | "junk" -> Junk

     

       83
       83
       +
         | "sent" -> Sent

     

       84
       84
       +
         | "subscribed" -> Subscribed

     

       85
       85
       +
         | "trash" -> Trash

     

       86
       86
       +
         | s -> Other s

     

       87
       87
       +
       

     

       88
       88
       +
       let role_jsont =

     

       89
       89
       +
         Jsont.map ~kind:"MailboxRole"

     

       90
       90
       +
           ~dec:(fun s -> role_of_string s)

     

       91
       91
       +
           ~enc:role_to_string

     

       92
       92
       +
           Jsont.string

     

       93
       93
       +
       

     

       94
       94
       +
       type t = {

     

       95
       95
       +
         id : Jmap_proto.Id.t;

     

       96
       96
       +
         name : string;

     

       97
       97
       +
         parent_id : Jmap_proto.Id.t option;

     

       98
       98
       +
         role : role option;

     

       99
       99
       +
         sort_order : int64;

     

       100
       100
       +
         total_emails : int64;

     

       101
       101
       +
         unread_emails : int64;

     

       102
       102
       +
         total_threads : int64;

     

       103
       103
       +
         unread_threads : int64;

     

       104
       104
       +
         my_rights : Rights.t;

     

       105
       105
       +
         is_subscribed : bool;

     

       106
       106
       +
       }

     

       107
       107
       +
       

     

       108
       108
       +
       let id t = t.id

     

       109
       109
       +
       let name t = t.name

     

       110
       110
       +
       let parent_id t = t.parent_id

     

       111
       111
       +
       let role t = t.role

     

       112
       112
       +
       let sort_order t = t.sort_order

     

       113
       113
       +
       let total_emails t = t.total_emails

     

       114
       114
       +
       let unread_emails t = t.unread_emails

     

       115
       115
       +
       let total_threads t = t.total_threads

     

       116
       116
       +
       let unread_threads t = t.unread_threads

     

       117
       117
       +
       let my_rights t = t.my_rights

     

       118
       118
       +
       let is_subscribed t = t.is_subscribed

     

       119
       119
       +
       

     

       120
       120
       +
       let make id name parent_id role sort_order total_emails unread_emails

     

       121
       121
       +
           total_threads unread_threads my_rights is_subscribed =

     

       122
       122
       +
         { id; name; parent_id; role; sort_order; total_emails; unread_emails;

     

       123
       123
       +
           total_threads; unread_threads; my_rights; is_subscribed }

     

       124
       124
       +
       

     

       125
       125
       +
       let jsont =

     

       126
       126
       +
         let kind = "Mailbox" in

     

       127
       127
       +
         Jsont.Object.map ~kind make

     

       128
       128
       +
         |> Jsont.Object.mem "id" Jmap_proto.Id.jsont ~enc:id

     

       129
       129
       +
         |> Jsont.Object.mem "name" Jsont.string ~enc:name

     

       130
       130
       +
         |> Jsont.Object.opt_mem "parentId" Jmap_proto.Id.jsont ~enc:parent_id

     

       131
       131
       +
         |> Jsont.Object.opt_mem "role" role_jsont ~enc:role

     

       132
       132
       +
         |> Jsont.Object.mem "sortOrder" Jmap_proto.Int53.Unsigned.jsont ~dec_absent:0L ~enc:sort_order

     

       133
       133
       +
         |> Jsont.Object.mem "totalEmails" Jmap_proto.Int53.Unsigned.jsont ~enc:total_emails

     

       134
       134
       +
         |> Jsont.Object.mem "unreadEmails" Jmap_proto.Int53.Unsigned.jsont ~enc:unread_emails

     

       135
       135
       +
         |> Jsont.Object.mem "totalThreads" Jmap_proto.Int53.Unsigned.jsont ~enc:total_threads

     

       136
       136
       +
         |> Jsont.Object.mem "unreadThreads" Jmap_proto.Int53.Unsigned.jsont ~enc:unread_threads

     

       137
       137
       +
         |> Jsont.Object.mem "myRights" Rights.jsont ~enc:my_rights

     

       138
       138
       +
         |> Jsont.Object.mem "isSubscribed" Jsont.bool ~enc:is_subscribed

     

       139
       139
       +
         |> Jsont.Object.finish

     

       140
       140
       +
       

     

       141
       141
       +
       module Filter_condition = struct

     

       142
       142
       +
         type t = {

     

       143
       143
       +
           parent_id : Jmap_proto.Id.t option option;

     

       144
       144
       +
           name : string option;

     

       145
       145
       +
           role : role option option;

     

       146
       146
       +
           has_any_role : bool option;

     

       147
       147
       +
           is_subscribed : bool option;

     

       148
       148
       +
         }

     

       149
       149
       +
       

     

       150
       150
       +
         let make parent_id name role has_any_role is_subscribed =

     

       151
       151
       +
           { parent_id; name; role; has_any_role; is_subscribed }

     

       152
       152
       +
       

     

       153
       153
       +
         let jsont =

     

       154
       154
       +
           let kind = "MailboxFilterCondition" in

     

       155
       155
       +
           (* parentId can be null (meaning top-level) or an id *)

     

       156
       156
       +
           let nullable_id = Jsont.(some Jmap_proto.Id.jsont) in

     

       157
       157
       +
           let nullable_role = Jsont.(some role_jsont) in

     

       158
       158
       +
           Jsont.Object.map ~kind make

     

       159
       159
       +
           |> Jsont.Object.opt_mem "parentId" nullable_id ~enc:(fun f -> f.parent_id)

     

       160
       160
       +
           |> Jsont.Object.opt_mem "name" Jsont.string ~enc:(fun f -> f.name)

     

       161
       161
       +
           |> Jsont.Object.opt_mem "role" nullable_role ~enc:(fun f -> f.role)

     

       162
       162
       +
           |> Jsont.Object.opt_mem "hasAnyRole" Jsont.bool ~enc:(fun f -> f.has_any_role)

     

       163
       163
       +
           |> Jsont.Object.opt_mem "isSubscribed" Jsont.bool ~enc:(fun f -> f.is_subscribed)

     

       164
       164
       +
           |> Jsont.Object.finish

     

       165
       165
       +
       end

+116

proto/mail/mailbox.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Mailbox type as defined in RFC 8621 Section 2 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Mailbox Rights} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** Rights the user has on a mailbox. *)

     

       11
       11
       +
       module Rights : sig

     

       12
       12
       +
         type t = {

     

       13
       13
       +
           may_read_items : bool;

     

       14
       14
       +
           may_add_items : bool;

     

       15
       15
       +
           may_remove_items : bool;

     

       16
       16
       +
           may_set_seen : bool;

     

       17
       17
       +
           may_set_keywords : bool;

     

       18
       18
       +
           may_create_child : bool;

     

       19
       19
       +
           may_rename : bool;

     

       20
       20
       +
           may_delete : bool;

     

       21
       21
       +
           may_submit : bool;

     

       22
       22
       +
         }

     

       23
       23
       +
       

     

       24
       24
       +
         val may_read_items : t -> bool

     

       25
       25
       +
         val may_add_items : t -> bool

     

       26
       26
       +
         val may_remove_items : t -> bool

     

       27
       27
       +
         val may_set_seen : t -> bool

     

       28
       28
       +
         val may_set_keywords : t -> bool

     

       29
       29
       +
         val may_create_child : t -> bool

     

       30
       30
       +
         val may_rename : t -> bool

     

       31
       31
       +
         val may_delete : t -> bool

     

       32
       32
       +
         val may_submit : t -> bool

     

       33
       33
       +
       

     

       34
       34
       +
         val jsont : t Jsont.t

     

       35
       35
       +
       end

     

       36
       36
       +
       

     

       37
       37
       +
       (** {1 Standard Roles} *)

     

       38
       38
       +
       

     

       39
       39
       +
       (** Standard mailbox roles per RFC 8621 Section 2. *)

     

       40
       40
       +
       type role =

     

       41
       41
       +
         | All

     

       42
       42
       +
         | Archive

     

       43
       43
       +
         | Drafts

     

       44
       44
       +
         | Flagged

     

       45
       45
       +
         | Important

     

       46
       46
       +
         | Inbox

     

       47
       47
       +
         | Junk

     

       48
       48
       +
         | Sent

     

       49
       49
       +
         | Subscribed

     

       50
       50
       +
         | Trash

     

       51
       51
       +
         | Other of string

     

       52
       52
       +
       

     

       53
       53
       +
       val role_to_string : role -> string

     

       54
       54
       +
       val role_of_string : string -> role

     

       55
       55
       +
       val role_jsont : role Jsont.t

     

       56
       56
       +
       

     

       57
       57
       +
       (** {1 Mailbox} *)

     

       58
       58
       +
       

     

       59
       59
       +
       type t = {

     

       60
       60
       +
         id : Jmap_proto.Id.t;

     

       61
       61
       +
         (** Server-assigned mailbox id. *)

     

       62
       62
       +
         name : string;

     

       63
       63
       +
         (** User-visible name (UTF-8). *)

     

       64
       64
       +
         parent_id : Jmap_proto.Id.t option;

     

       65
       65
       +
         (** Id of parent mailbox, or [None] for root. *)

     

       66
       66
       +
         role : role option;

     

       67
       67
       +
         (** Standard role, if any. *)

     

       68
       68
       +
         sort_order : int64;

     

       69
       69
       +
         (** Sort order hint (lower = displayed first). *)

     

       70
       70
       +
         total_emails : int64;

     

       71
       71
       +
         (** Total number of emails in mailbox. *)

     

       72
       72
       +
         unread_emails : int64;

     

       73
       73
       +
         (** Number of unread emails. *)

     

       74
       74
       +
         total_threads : int64;

     

       75
       75
       +
         (** Total number of threads. *)

     

       76
       76
       +
         unread_threads : int64;

     

       77
       77
       +
         (** Number of threads with unread emails. *)

     

       78
       78
       +
         my_rights : Rights.t;

     

       79
       79
       +
         (** User's rights on this mailbox. *)

     

       80
       80
       +
         is_subscribed : bool;

     

       81
       81
       +
         (** Whether user is subscribed to this mailbox. *)

     

       82
       82
       +
       }

     

       83
       83
       +
       

     

       84
       84
       +
       val id : t -> Jmap_proto.Id.t

     

       85
       85
       +
       val name : t -> string

     

       86
       86
       +
       val parent_id : t -> Jmap_proto.Id.t option

     

       87
       87
       +
       val role : t -> role option

     

       88
       88
       +
       val sort_order : t -> int64

     

       89
       89
       +
       val total_emails : t -> int64

     

       90
       90
       +
       val unread_emails : t -> int64

     

       91
       91
       +
       val total_threads : t -> int64

     

       92
       92
       +
       val unread_threads : t -> int64

     

       93
       93
       +
       val my_rights : t -> Rights.t

     

       94
       94
       +
       val is_subscribed : t -> bool

     

       95
       95
       +
       

     

       96
       96
       +
       val jsont : t Jsont.t

     

       97
       97
       +
       

     

       98
       98
       +
       (** {1 Mailbox Filter Conditions} *)

     

       99
       99
       +
       

     

       100
       100
       +
       (** Filter conditions for Mailbox/query. *)

     

       101
       101
       +
       module Filter_condition : sig

     

       102
       102
       +
         type t = {

     

       103
       103
       +
           parent_id : Jmap_proto.Id.t option option;

     

       104
       104
       +
           (** Filter by parent. [Some None] = top-level only. *)

     

       105
       105
       +
           name : string option;

     

       106
       106
       +
           (** Filter by exact name match. *)

     

       107
       107
       +
           role : role option option;

     

       108
       108
       +
           (** Filter by role. [Some None] = no role. *)

     

       109
       109
       +
           has_any_role : bool option;

     

       110
       110
       +
           (** Filter by whether mailbox has any role. *)

     

       111
       111
       +
           is_subscribed : bool option;

     

       112
       112
       +
           (** Filter by subscription status. *)

     

       113
       113
       +
         }

     

       114
       114
       +
       

     

       115
       115
       +
         val jsont : t Jsont.t

     

       116
       116
       +
       end

+24

proto/mail/search_snippet.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = {

     

       7
       7
       +
         email_id : Jmap_proto.Id.t;

     

       8
       8
       +
         subject : string option;

     

       9
       9
       +
         preview : string option;

     

       10
       10
       +
       }

     

       11
       11
       +
       

     

       12
       12
       +
       let email_id t = t.email_id

     

       13
       13
       +
       let subject t = t.subject

     

       14
       14
       +
       let preview t = t.preview

     

       15
       15
       +
       

     

       16
       16
       +
       let make email_id subject preview = { email_id; subject; preview }

     

       17
       17
       +
       

     

       18
       18
       +
       let jsont =

     

       19
       19
       +
         let kind = "SearchSnippet" in

     

       20
       20
       +
         Jsont.Object.map ~kind make

     

       21
       21
       +
         |> Jsont.Object.mem "emailId" Jmap_proto.Id.jsont ~enc:email_id

     

       22
       22
       +
         |> Jsont.Object.opt_mem "subject" Jsont.string ~enc:subject

     

       23
       23
       +
         |> Jsont.Object.opt_mem "preview" Jsont.string ~enc:preview

     

       24
       24
       +
         |> Jsont.Object.finish

+21

proto/mail/search_snippet.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** SearchSnippet type as defined in RFC 8621 Section 5 *)

     

       7
       7
       +
       

     

       8
       8
       +
       type t = {

     

       9
       9
       +
         email_id : Jmap_proto.Id.t;

     

       10
       10
       +
         (** The email this snippet is for. *)

     

       11
       11
       +
         subject : string option;

     

       12
       12
       +
         (** HTML snippet of matching subject text. *)

     

       13
       13
       +
         preview : string option;

     

       14
       14
       +
         (** HTML snippet of matching body text. *)

     

       15
       15
       +
       }

     

       16
       16
       +
       

     

       17
       17
       +
       val email_id : t -> Jmap_proto.Id.t

     

       18
       18
       +
       val subject : t -> string option

     

       19
       19
       +
       val preview : t -> string option

     

       20
       20
       +
       

     

       21
       21
       +
       val jsont : t Jsont.t

+183

proto/mail/submission.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       module Address = struct

     

       7
       7
       +
         type t = {

     

       8
       8
       +
           email : string;

     

       9
       9
       +
           parameters : (string * string) list option;

     

       10
       10
       +
         }

     

       11
       11
       +
       

     

       12
       12
       +
         let email t = t.email

     

       13
       13
       +
         let parameters t = t.parameters

     

       14
       14
       +
       

     

       15
       15
       +
         let make email parameters = { email; parameters }

     

       16
       16
       +
       

     

       17
       17
       +
         let jsont =

     

       18
       18
       +
           let kind = "EmailSubmission Address" in

     

       19
       19
       +
           Jsont.Object.map ~kind make

     

       20
       20
       +
           |> Jsont.Object.mem "email" Jsont.string ~enc:email

     

       21
       21
       +
           |> Jsont.Object.opt_mem "parameters" (Jmap_proto.Json_map.of_string Jsont.string) ~enc:parameters

     

       22
       22
       +
           |> Jsont.Object.finish

     

       23
       23
       +
       end

     

       24
       24
       +
       

     

       25
       25
       +
       module Envelope = struct

     

       26
       26
       +
         type t = {

     

       27
       27
       +
           mail_from : Address.t;

     

       28
       28
       +
           rcpt_to : Address.t list;

     

       29
       29
       +
         }

     

       30
       30
       +
       

     

       31
       31
       +
         let mail_from t = t.mail_from

     

       32
       32
       +
         let rcpt_to t = t.rcpt_to

     

       33
       33
       +
       

     

       34
       34
       +
         let make mail_from rcpt_to = { mail_from; rcpt_to }

     

       35
       35
       +
       

     

       36
       36
       +
         let jsont =

     

       37
       37
       +
           let kind = "Envelope" in

     

       38
       38
       +
           Jsont.Object.map ~kind make

     

       39
       39
       +
           |> Jsont.Object.mem "mailFrom" Address.jsont ~enc:mail_from

     

       40
       40
       +
           |> Jsont.Object.mem "rcptTo" (Jsont.list Address.jsont) ~enc:rcpt_to

     

       41
       41
       +
           |> Jsont.Object.finish

     

       42
       42
       +
       end

     

       43
       43
       +
       

     

       44
       44
       +
       module Delivery_status = struct

     

       45
       45
       +
         type delivered = Queued | Yes | No | Unknown

     

       46
       46
       +
       

     

       47
       47
       +
         let delivered_to_string = function

     

       48
       48
       +
           | Queued -> "queued"

     

       49
       49
       +
           | Yes -> "yes"

     

       50
       50
       +
           | No -> "no"

     

       51
       51
       +
           | Unknown -> "unknown"

     

       52
       52
       +
       

     

       53
       53
       +
         let delivered_of_string = function

     

       54
       54
       +
           | "queued" -> Queued

     

       55
       55
       +
           | "yes" -> Yes

     

       56
       56
       +
           | "no" -> No

     

       57
       57
       +
           | _ -> Unknown

     

       58
       58
       +
       

     

       59
       59
       +
         let delivered_jsont =

     

       60
       60
       +
           Jsont.map ~kind:"DeliveryStatus.delivered"

     

       61
       61
       +
             ~dec:delivered_of_string ~enc:delivered_to_string Jsont.string

     

       62
       62
       +
       

     

       63
       63
       +
         type displayed = Unknown | Yes

     

       64
       64
       +
       

     

       65
       65
       +
         let displayed_to_string = function

     

       66
       66
       +
           | Unknown -> "unknown"

     

       67
       67
       +
           | Yes -> "yes"

     

       68
       68
       +
       

     

       69
       69
       +
         let displayed_of_string = function

     

       70
       70
       +
           | "yes" -> Yes

     

       71
       71
       +
           | _ -> Unknown

     

       72
       72
       +
       

     

       73
       73
       +
         let displayed_jsont =

     

       74
       74
       +
           Jsont.map ~kind:"DeliveryStatus.displayed"

     

       75
       75
       +
             ~dec:displayed_of_string ~enc:displayed_to_string Jsont.string

     

       76
       76
       +
       

     

       77
       77
       +
         type t = {

     

       78
       78
       +
           smtp_reply : string;

     

       79
       79
       +
           delivered : delivered;

     

       80
       80
       +
           displayed : displayed;

     

       81
       81
       +
         }

     

       82
       82
       +
       

     

       83
       83
       +
         let smtp_reply t = t.smtp_reply

     

       84
       84
       +
         let delivered t = t.delivered

     

       85
       85
       +
         let displayed t = t.displayed

     

       86
       86
       +
       

     

       87
       87
       +
         let make smtp_reply delivered displayed =

     

       88
       88
       +
           { smtp_reply; delivered; displayed }

     

       89
       89
       +
       

     

       90
       90
       +
         let jsont =

     

       91
       91
       +
           let kind = "DeliveryStatus" in

     

       92
       92
       +
           Jsont.Object.map ~kind make

     

       93
       93
       +
           |> Jsont.Object.mem "smtpReply" Jsont.string ~enc:smtp_reply

     

       94
       94
       +
           |> Jsont.Object.mem "delivered" delivered_jsont ~enc:delivered

     

       95
       95
       +
           |> Jsont.Object.mem "displayed" displayed_jsont ~enc:displayed

     

       96
       96
       +
           |> Jsont.Object.finish

     

       97
       97
       +
       end

     

       98
       98
       +
       

     

       99
       99
       +
       type undo_status = Pending | Final | Canceled

     

       100
       100
       +
       

     

       101
       101
       +
       let undo_status_to_string = function

     

       102
       102
       +
         | Pending -> "pending"

     

       103
       103
       +
         | Final -> "final"

     

       104
       104
       +
         | Canceled -> "canceled"

     

       105
       105
       +
       

     

       106
       106
       +
       let undo_status_of_string = function

     

       107
       107
       +
         | "pending" -> Pending

     

       108
       108
       +
         | "final" -> Final

     

       109
       109
       +
         | "canceled" -> Canceled

     

       110
       110
       +
         | s -> Jsont.Error.msgf Jsont.Meta.none "Unknown undo status: %s" s

     

       111
       111
       +
       

     

       112
       112
       +
       let undo_status_jsont =

     

       113
       113
       +
         Jsont.map ~kind:"UndoStatus"

     

       114
       114
       +
           ~dec:undo_status_of_string ~enc:undo_status_to_string Jsont.string

     

       115
       115
       +
       

     

       116
       116
       +
       type t = {

     

       117
       117
       +
         id : Jmap_proto.Id.t;

     

       118
       118
       +
         identity_id : Jmap_proto.Id.t;

     

       119
       119
       +
         email_id : Jmap_proto.Id.t;

     

       120
       120
       +
         thread_id : Jmap_proto.Id.t;

     

       121
       121
       +
         envelope : Envelope.t option;

     

       122
       122
       +
         send_at : Ptime.t;

     

       123
       123
       +
         undo_status : undo_status;

     

       124
       124
       +
         delivery_status : (string * Delivery_status.t) list option;

     

       125
       125
       +
         dsn_blob_ids : Jmap_proto.Id.t list;

     

       126
       126
       +
         mdn_blob_ids : Jmap_proto.Id.t list;

     

       127
       127
       +
       }

     

       128
       128
       +
       

     

       129
       129
       +
       let id t = t.id

     

       130
       130
       +
       let identity_id t = t.identity_id

     

       131
       131
       +
       let email_id t = t.email_id

     

       132
       132
       +
       let thread_id t = t.thread_id

     

       133
       133
       +
       let envelope t = t.envelope

     

       134
       134
       +
       let send_at t = t.send_at

     

       135
       135
       +
       let undo_status t = t.undo_status

     

       136
       136
       +
       let delivery_status t = t.delivery_status

     

       137
       137
       +
       let dsn_blob_ids t = t.dsn_blob_ids

     

       138
       138
       +
       let mdn_blob_ids t = t.mdn_blob_ids

     

       139
       139
       +
       

     

       140
       140
       +
       let make id identity_id email_id thread_id envelope send_at undo_status

     

       141
       141
       +
           delivery_status dsn_blob_ids mdn_blob_ids =

     

       142
       142
       +
         { id; identity_id; email_id; thread_id; envelope; send_at; undo_status;

     

       143
       143
       +
           delivery_status; dsn_blob_ids; mdn_blob_ids }

     

       144
       144
       +
       

     

       145
       145
       +
       let jsont =

     

       146
       146
       +
         let kind = "EmailSubmission" in

     

       147
       147
       +
         Jsont.Object.map ~kind make

     

       148
       148
       +
         |> Jsont.Object.mem "id" Jmap_proto.Id.jsont ~enc:id

     

       149
       149
       +
         |> Jsont.Object.mem "identityId" Jmap_proto.Id.jsont ~enc:identity_id

     

       150
       150
       +
         |> Jsont.Object.mem "emailId" Jmap_proto.Id.jsont ~enc:email_id

     

       151
       151
       +
         |> Jsont.Object.mem "threadId" Jmap_proto.Id.jsont ~enc:thread_id

     

       152
       152
       +
         |> Jsont.Object.opt_mem "envelope" Envelope.jsont ~enc:envelope

     

       153
       153
       +
         |> Jsont.Object.mem "sendAt" Jmap_proto.Date.Utc.jsont ~enc:send_at

     

       154
       154
       +
         |> Jsont.Object.mem "undoStatus" undo_status_jsont ~enc:undo_status

     

       155
       155
       +
         |> Jsont.Object.opt_mem "deliveryStatus" (Jmap_proto.Json_map.of_string Delivery_status.jsont) ~enc:delivery_status

     

       156
       156
       +
         |> Jsont.Object.mem "dsnBlobIds" (Jsont.list Jmap_proto.Id.jsont) ~dec_absent:[] ~enc:dsn_blob_ids

     

       157
       157
       +
         |> Jsont.Object.mem "mdnBlobIds" (Jsont.list Jmap_proto.Id.jsont) ~dec_absent:[] ~enc:mdn_blob_ids

     

       158
       158
       +
         |> Jsont.Object.finish

     

       159
       159
       +
       

     

       160
       160
       +
       module Filter_condition = struct

     

       161
       161
       +
         type t = {

     

       162
       162
       +
           identity_ids : Jmap_proto.Id.t list option;

     

       163
       163
       +
           email_ids : Jmap_proto.Id.t list option;

     

       164
       164
       +
           thread_ids : Jmap_proto.Id.t list option;

     

       165
       165
       +
           undo_status : undo_status option;

     

       166
       166
       +
           before : Ptime.t option;

     

       167
       167
       +
           after : Ptime.t option;

     

       168
       168
       +
         }

     

       169
       169
       +
       

     

       170
       170
       +
         let make identity_ids email_ids thread_ids undo_status before after =

     

       171
       171
       +
           { identity_ids; email_ids; thread_ids; undo_status; before; after }

     

       172
       172
       +
       

     

       173
       173
       +
         let jsont =

     

       174
       174
       +
           let kind = "EmailSubmissionFilterCondition" in

     

       175
       175
       +
           Jsont.Object.map ~kind make

     

       176
       176
       +
           |> Jsont.Object.opt_mem "identityIds" (Jsont.list Jmap_proto.Id.jsont) ~enc:(fun f -> f.identity_ids)

     

       177
       177
       +
           |> Jsont.Object.opt_mem "emailIds" (Jsont.list Jmap_proto.Id.jsont) ~enc:(fun f -> f.email_ids)

     

       178
       178
       +
           |> Jsont.Object.opt_mem "threadIds" (Jsont.list Jmap_proto.Id.jsont) ~enc:(fun f -> f.thread_ids)

     

       179
       179
       +
           |> Jsont.Object.opt_mem "undoStatus" undo_status_jsont ~enc:(fun f -> f.undo_status)

     

       180
       180
       +
           |> Jsont.Object.opt_mem "before" Jmap_proto.Date.Utc.jsont ~enc:(fun f -> f.before)

     

       181
       181
       +
           |> Jsont.Object.opt_mem "after" Jmap_proto.Date.Utc.jsont ~enc:(fun f -> f.after)

     

       182
       182
       +
           |> Jsont.Object.finish

     

       183
       183
       +
       end

+132

proto/mail/submission.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** EmailSubmission type as defined in RFC 8621 Section 7 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Address} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** An address with optional SMTP parameters. *)

     

       11
       11
       +
       module Address : sig

     

       12
       12
       +
         type t = {

     

       13
       13
       +
           email : string;

     

       14
       14
       +
           (** The email address. *)

     

       15
       15
       +
           parameters : (string * string) list option;

     

       16
       16
       +
           (** Optional SMTP parameters. *)

     

       17
       17
       +
         }

     

       18
       18
       +
       

     

       19
       19
       +
         val email : t -> string

     

       20
       20
       +
         val parameters : t -> (string * string) list option

     

       21
       21
       +
       

     

       22
       22
       +
         val jsont : t Jsont.t

     

       23
       23
       +
       end

     

       24
       24
       +
       

     

       25
       25
       +
       (** {1 Envelope} *)

     

       26
       26
       +
       

     

       27
       27
       +
       (** SMTP envelope. *)

     

       28
       28
       +
       module Envelope : sig

     

       29
       29
       +
         type t = {

     

       30
       30
       +
           mail_from : Address.t;

     

       31
       31
       +
           (** MAIL FROM address. *)

     

       32
       32
       +
           rcpt_to : Address.t list;

     

       33
       33
       +
           (** RCPT TO addresses. *)

     

       34
       34
       +
         }

     

       35
       35
       +
       

     

       36
       36
       +
         val mail_from : t -> Address.t

     

       37
       37
       +
         val rcpt_to : t -> Address.t list

     

       38
       38
       +
       

     

       39
       39
       +
         val jsont : t Jsont.t

     

       40
       40
       +
       end

     

       41
       41
       +
       

     

       42
       42
       +
       (** {1 Delivery Status} *)

     

       43
       43
       +
       

     

       44
       44
       +
       (** Status of delivery to a recipient. *)

     

       45
       45
       +
       module Delivery_status : sig

     

       46
       46
       +
         type delivered =

     

       47
       47
       +
           | Queued

     

       48
       48
       +
           | Yes

     

       49
       49
       +
           | No

     

       50
       50
       +
           | Unknown

     

       51
       51
       +
       

     

       52
       52
       +
         type displayed =

     

       53
       53
       +
           | Unknown

     

       54
       54
       +
           | Yes

     

       55
       55
       +
       

     

       56
       56
       +
         type t = {

     

       57
       57
       +
           smtp_reply : string;

     

       58
       58
       +
           (** The SMTP reply string. *)

     

       59
       59
       +
           delivered : delivered;

     

       60
       60
       +
           (** Delivery status. *)

     

       61
       61
       +
           displayed : displayed;

     

       62
       62
       +
           (** MDN display status. *)

     

       63
       63
       +
         }

     

       64
       64
       +
       

     

       65
       65
       +
         val smtp_reply : t -> string

     

       66
       66
       +
         val delivered : t -> delivered

     

       67
       67
       +
         val displayed : t -> displayed

     

       68
       68
       +
       

     

       69
       69
       +
         val jsont : t Jsont.t

     

       70
       70
       +
       end

     

       71
       71
       +
       

     

       72
       72
       +
       (** {1 Undo Status} *)

     

       73
       73
       +
       

     

       74
       74
       +
       type undo_status =

     

       75
       75
       +
         | Pending

     

       76
       76
       +
         | Final

     

       77
       77
       +
         | Canceled

     

       78
       78
       +
       

     

       79
       79
       +
       val undo_status_jsont : undo_status Jsont.t

     

       80
       80
       +
       

     

       81
       81
       +
       (** {1 EmailSubmission} *)

     

       82
       82
       +
       

     

       83
       83
       +
       type t = {

     

       84
       84
       +
         id : Jmap_proto.Id.t;

     

       85
       85
       +
         (** Server-assigned submission id. *)

     

       86
       86
       +
         identity_id : Jmap_proto.Id.t;

     

       87
       87
       +
         (** The identity used to send. *)

     

       88
       88
       +
         email_id : Jmap_proto.Id.t;

     

       89
       89
       +
         (** The email that was submitted. *)

     

       90
       90
       +
         thread_id : Jmap_proto.Id.t;

     

       91
       91
       +
         (** The thread of the submitted email. *)

     

       92
       92
       +
         envelope : Envelope.t option;

     

       93
       93
       +
         (** The envelope used, if different from email headers. *)

     

       94
       94
       +
         send_at : Ptime.t;

     

       95
       95
       +
         (** When the email was/will be sent. *)

     

       96
       96
       +
         undo_status : undo_status;

     

       97
       97
       +
         (** Whether sending can be undone. *)

     

       98
       98
       +
         delivery_status : (string * Delivery_status.t) list option;

     

       99
       99
       +
         (** Delivery status per recipient. *)

     

       100
       100
       +
         dsn_blob_ids : Jmap_proto.Id.t list;

     

       101
       101
       +
         (** Blob ids of received DSN messages. *)

     

       102
       102
       +
         mdn_blob_ids : Jmap_proto.Id.t list;

     

       103
       103
       +
         (** Blob ids of received MDN messages. *)

     

       104
       104
       +
       }

     

       105
       105
       +
       

     

       106
       106
       +
       val id : t -> Jmap_proto.Id.t

     

       107
       107
       +
       val identity_id : t -> Jmap_proto.Id.t

     

       108
       108
       +
       val email_id : t -> Jmap_proto.Id.t

     

       109
       109
       +
       val thread_id : t -> Jmap_proto.Id.t

     

       110
       110
       +
       val envelope : t -> Envelope.t option

     

       111
       111
       +
       val send_at : t -> Ptime.t

     

       112
       112
       +
       val undo_status : t -> undo_status

     

       113
       113
       +
       val delivery_status : t -> (string * Delivery_status.t) list option

     

       114
       114
       +
       val dsn_blob_ids : t -> Jmap_proto.Id.t list

     

       115
       115
       +
       val mdn_blob_ids : t -> Jmap_proto.Id.t list

     

       116
       116
       +
       

     

       117
       117
       +
       val jsont : t Jsont.t

     

       118
       118
       +
       

     

       119
       119
       +
       (** {1 Filter Conditions} *)

     

       120
       120
       +
       

     

       121
       121
       +
       module Filter_condition : sig

     

       122
       122
       +
         type t = {

     

       123
       123
       +
           identity_ids : Jmap_proto.Id.t list option;

     

       124
       124
       +
           email_ids : Jmap_proto.Id.t list option;

     

       125
       125
       +
           thread_ids : Jmap_proto.Id.t list option;

     

       126
       126
       +
           undo_status : undo_status option;

     

       127
       127
       +
           before : Ptime.t option;

     

       128
       128
       +
           after : Ptime.t option;

     

       129
       129
       +
         }

     

       130
       130
       +
       

     

       131
       131
       +
         val jsont : t Jsont.t

     

       132
       132
       +
       end

+21

proto/mail/thread.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = {

     

       7
       7
       +
         id : Jmap_proto.Id.t;

     

       8
       8
       +
         email_ids : Jmap_proto.Id.t list;

     

       9
       9
       +
       }

     

       10
       10
       +
       

     

       11
       11
       +
       let id t = t.id

     

       12
       12
       +
       let email_ids t = t.email_ids

     

       13
       13
       +
       

     

       14
       14
       +
       let make id email_ids = { id; email_ids }

     

       15
       15
       +
       

     

       16
       16
       +
       let jsont =

     

       17
       17
       +
         let kind = "Thread" in

     

       18
       18
       +
         Jsont.Object.map ~kind make

     

       19
       19
       +
         |> Jsont.Object.mem "id" Jmap_proto.Id.jsont ~enc:id

     

       20
       20
       +
         |> Jsont.Object.mem "emailIds" (Jsont.list Jmap_proto.Id.jsont) ~enc:email_ids

     

       21
       21
       +
         |> Jsont.Object.finish

+18

proto/mail/thread.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Thread type as defined in RFC 8621 Section 3 *)

     

       7
       7
       +
       

     

       8
       8
       +
       type t = {

     

       9
       9
       +
         id : Jmap_proto.Id.t;

     

       10
       10
       +
         (** Server-assigned thread id. *)

     

       11
       11
       +
         email_ids : Jmap_proto.Id.t list;

     

       12
       12
       +
         (** Ids of emails in this thread, in date order. *)

     

       13
       13
       +
       }

     

       14
       14
       +
       

     

       15
       15
       +
       val id : t -> Jmap_proto.Id.t

     

       16
       16
       +
       val email_ids : t -> Jmap_proto.Id.t list

     

       17
       17
       +
       

     

       18
       18
       +
       val jsont : t Jsont.t

+39

proto/mail/vacation.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = {

     

       7
       7
       +
         id : Jmap_proto.Id.t;

     

       8
       8
       +
         is_enabled : bool;

     

       9
       9
       +
         from_date : Ptime.t option;

     

       10
       10
       +
         to_date : Ptime.t option;

     

       11
       11
       +
         subject : string option;

     

       12
       12
       +
         text_body : string option;

     

       13
       13
       +
         html_body : string option;

     

       14
       14
       +
       }

     

       15
       15
       +
       

     

       16
       16
       +
       let id t = t.id

     

       17
       17
       +
       let is_enabled t = t.is_enabled

     

       18
       18
       +
       let from_date t = t.from_date

     

       19
       19
       +
       let to_date t = t.to_date

     

       20
       20
       +
       let subject t = t.subject

     

       21
       21
       +
       let text_body t = t.text_body

     

       22
       22
       +
       let html_body t = t.html_body

     

       23
       23
       +
       

     

       24
       24
       +
       let singleton_id = Jmap_proto.Id.of_string_exn "singleton"

     

       25
       25
       +
       

     

       26
       26
       +
       let make id is_enabled from_date to_date subject text_body html_body =

     

       27
       27
       +
         { id; is_enabled; from_date; to_date; subject; text_body; html_body }

     

       28
       28
       +
       

     

       29
       29
       +
       let jsont =

     

       30
       30
       +
         let kind = "VacationResponse" in

     

       31
       31
       +
         Jsont.Object.map ~kind make

     

       32
       32
       +
         |> Jsont.Object.mem "id" Jmap_proto.Id.jsont ~enc:id

     

       33
       33
       +
         |> Jsont.Object.mem "isEnabled" Jsont.bool ~enc:is_enabled

     

       34
       34
       +
         |> Jsont.Object.opt_mem "fromDate" Jmap_proto.Date.Utc.jsont ~enc:from_date

     

       35
       35
       +
         |> Jsont.Object.opt_mem "toDate" Jmap_proto.Date.Utc.jsont ~enc:to_date

     

       36
       36
       +
         |> Jsont.Object.opt_mem "subject" Jsont.string ~enc:subject

     

       37
       37
       +
         |> Jsont.Object.opt_mem "textBody" Jsont.string ~enc:text_body

     

       38
       38
       +
         |> Jsont.Object.opt_mem "htmlBody" Jsont.string ~enc:html_body

     

       39
       39
       +
         |> Jsont.Object.finish

+36

proto/mail/vacation.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** VacationResponse type as defined in RFC 8621 Section 8 *)

     

       7
       7
       +
       

     

       8
       8
       +
       type t = {

     

       9
       9
       +
         id : Jmap_proto.Id.t;

     

       10
       10
       +
         (** Always "singleton" - there is only one vacation response. *)

     

       11
       11
       +
         is_enabled : bool;

     

       12
       12
       +
         (** Whether the vacation response is active. *)

     

       13
       13
       +
         from_date : Ptime.t option;

     

       14
       14
       +
         (** When to start sending responses. *)

     

       15
       15
       +
         to_date : Ptime.t option;

     

       16
       16
       +
         (** When to stop sending responses. *)

     

       17
       17
       +
         subject : string option;

     

       18
       18
       +
         (** Subject for the auto-reply. *)

     

       19
       19
       +
         text_body : string option;

     

       20
       20
       +
         (** Plain text body. *)

     

       21
       21
       +
         html_body : string option;

     

       22
       22
       +
         (** HTML body. *)

     

       23
       23
       +
       }

     

       24
       24
       +
       

     

       25
       25
       +
       val id : t -> Jmap_proto.Id.t

     

       26
       26
       +
       val is_enabled : t -> bool

     

       27
       27
       +
       val from_date : t -> Ptime.t option

     

       28
       28
       +
       val to_date : t -> Ptime.t option

     

       29
       29
       +
       val subject : t -> string option

     

       30
       30
       +
       val text_body : t -> string option

     

       31
       31
       +
       val html_body : t -> string option

     

       32
       32
       +
       

     

       33
       33
       +
       val jsont : t Jsont.t

     

       34
       34
       +
       

     

       35
       35
       +
       (** The singleton id for VacationResponse. *)

     

       36
       36
       +
       val singleton_id : Jmap_proto.Id.t

+316

proto/method_.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (* Foo/get *)

     

       7
       7
       +
       

     

       8
       8
       +
       type get_args = {

     

       9
       9
       +
         account_id : Id.t;

     

       10
       10
       +
         ids : Id.t list option;

     

       11
       11
       +
         properties : string list option;

     

       12
       12
       +
       }

     

       13
       13
       +
       

     

       14
       14
       +
       let get_args ~account_id ?ids ?properties () =

     

       15
       15
       +
         { account_id; ids; properties }

     

       16
       16
       +
       

     

       17
       17
       +
       let get_args_make account_id ids properties =

     

       18
       18
       +
         { account_id; ids; properties }

     

       19
       19
       +
       

     

       20
       20
       +
       let get_args_jsont =

     

       21
       21
       +
         let kind = "GetArgs" in

     

       22
       22
       +
         Jsont.Object.map ~kind get_args_make

     

       23
       23
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun a -> a.account_id)

     

       24
       24
       +
         |> Jsont.Object.opt_mem "ids" (Jsont.list Id.jsont) ~enc:(fun a -> a.ids)

     

       25
       25
       +
         |> Jsont.Object.opt_mem "properties" (Jsont.list Jsont.string) ~enc:(fun a -> a.properties)

     

       26
       26
       +
         |> Jsont.Object.finish

     

       27
       27
       +
       

     

       28
       28
       +
       type 'a get_response = {

     

       29
       29
       +
         account_id : Id.t;

     

       30
       30
       +
         state : string;

     

       31
       31
       +
         list : 'a list;

     

       32
       32
       +
         not_found : Id.t list;

     

       33
       33
       +
       }

     

       34
       34
       +
       

     

       35
       35
       +
       let get_response_jsont (type a) (obj_jsont : a Jsont.t) : a get_response Jsont.t =

     

       36
       36
       +
         let kind = "GetResponse" in

     

       37
       37
       +
         let make account_id state list not_found =

     

       38
       38
       +
           { account_id; state; list; not_found }

     

       39
       39
       +
         in

     

       40
       40
       +
         Jsont.Object.map ~kind make

     

       41
       41
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun r -> r.account_id)

     

       42
       42
       +
         |> Jsont.Object.mem "state" Jsont.string ~enc:(fun r -> r.state)

     

       43
       43
       +
         |> Jsont.Object.mem "list" (Jsont.list obj_jsont) ~enc:(fun r -> r.list)

     

       44
       44
       +
         |> Jsont.Object.mem "notFound" (Jsont.list Id.jsont) ~enc:(fun r -> r.not_found)

     

       45
       45
       +
         |> Jsont.Object.finish

     

       46
       46
       +
       

     

       47
       47
       +
       (* Foo/changes *)

     

       48
       48
       +
       

     

       49
       49
       +
       type changes_args = {

     

       50
       50
       +
         account_id : Id.t;

     

       51
       51
       +
         since_state : string;

     

       52
       52
       +
         max_changes : int64 option;

     

       53
       53
       +
       }

     

       54
       54
       +
       

     

       55
       55
       +
       let changes_args ~account_id ~since_state ?max_changes () =

     

       56
       56
       +
         { account_id; since_state; max_changes }

     

       57
       57
       +
       

     

       58
       58
       +
       let changes_args_make account_id since_state max_changes =

     

       59
       59
       +
         { account_id; since_state; max_changes }

     

       60
       60
       +
       

     

       61
       61
       +
       let changes_args_jsont =

     

       62
       62
       +
         let kind = "ChangesArgs" in

     

       63
       63
       +
         Jsont.Object.map ~kind changes_args_make

     

       64
       64
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun a -> a.account_id)

     

       65
       65
       +
         |> Jsont.Object.mem "sinceState" Jsont.string ~enc:(fun a -> a.since_state)

     

       66
       66
       +
         |> Jsont.Object.opt_mem "maxChanges" Int53.Unsigned.jsont ~enc:(fun a -> a.max_changes)

     

       67
       67
       +
         |> Jsont.Object.finish

     

       68
       68
       +
       

     

       69
       69
       +
       type changes_response = {

     

       70
       70
       +
         account_id : Id.t;

     

       71
       71
       +
         old_state : string;

     

       72
       72
       +
         new_state : string;

     

       73
       73
       +
         has_more_changes : bool;

     

       74
       74
       +
         created : Id.t list;

     

       75
       75
       +
         updated : Id.t list;

     

       76
       76
       +
         destroyed : Id.t list;

     

       77
       77
       +
       }

     

       78
       78
       +
       

     

       79
       79
       +
       let changes_response_make account_id old_state new_state has_more_changes

     

       80
       80
       +
           created updated destroyed =

     

       81
       81
       +
         { account_id; old_state; new_state; has_more_changes; created; updated; destroyed }

     

       82
       82
       +
       

     

       83
       83
       +
       let changes_response_jsont =

     

       84
       84
       +
         let kind = "ChangesResponse" in

     

       85
       85
       +
         Jsont.Object.map ~kind changes_response_make

     

       86
       86
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun r -> r.account_id)

     

       87
       87
       +
         |> Jsont.Object.mem "oldState" Jsont.string ~enc:(fun r -> r.old_state)

     

       88
       88
       +
         |> Jsont.Object.mem "newState" Jsont.string ~enc:(fun r -> r.new_state)

     

       89
       89
       +
         |> Jsont.Object.mem "hasMoreChanges" Jsont.bool ~enc:(fun r -> r.has_more_changes)

     

       90
       90
       +
         |> Jsont.Object.mem "created" (Jsont.list Id.jsont) ~enc:(fun r -> r.created)

     

       91
       91
       +
         |> Jsont.Object.mem "updated" (Jsont.list Id.jsont) ~enc:(fun r -> r.updated)

     

       92
       92
       +
         |> Jsont.Object.mem "destroyed" (Jsont.list Id.jsont) ~enc:(fun r -> r.destroyed)

     

       93
       93
       +
         |> Jsont.Object.finish

     

       94
       94
       +
       

     

       95
       95
       +
       (* Foo/set *)

     

       96
       96
       +
       

     

       97
       97
       +
       type 'a set_args = {

     

       98
       98
       +
         account_id : Id.t;

     

       99
       99
       +
         if_in_state : string option;

     

       100
       100
       +
         create : (Id.t * 'a) list option;

     

       101
       101
       +
         update : (Id.t * Jsont.json) list option;

     

       102
       102
       +
         destroy : Id.t list option;

     

       103
       103
       +
       }

     

       104
       104
       +
       

     

       105
       105
       +
       let set_args ~account_id ?if_in_state ?create ?update ?destroy () =

     

       106
       106
       +
         { account_id; if_in_state; create; update; destroy }

     

       107
       107
       +
       

     

       108
       108
       +
       let set_args_jsont (type a) (obj_jsont : a Jsont.t) : a set_args Jsont.t =

     

       109
       109
       +
         let kind = "SetArgs" in

     

       110
       110
       +
         let make account_id if_in_state create update destroy =

     

       111
       111
       +
           { account_id; if_in_state; create; update; destroy }

     

       112
       112
       +
         in

     

       113
       113
       +
         Jsont.Object.map ~kind make

     

       114
       114
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun a -> a.account_id)

     

       115
       115
       +
         |> Jsont.Object.opt_mem "ifInState" Jsont.string ~enc:(fun a -> a.if_in_state)

     

       116
       116
       +
         |> Jsont.Object.opt_mem "create" (Json_map.of_id obj_jsont) ~enc:(fun a -> a.create)

     

       117
       117
       +
         |> Jsont.Object.opt_mem "update" (Json_map.of_id Jsont.json) ~enc:(fun a -> a.update)

     

       118
       118
       +
         |> Jsont.Object.opt_mem "destroy" (Jsont.list Id.jsont) ~enc:(fun a -> a.destroy)

     

       119
       119
       +
         |> Jsont.Object.finish

     

       120
       120
       +
       

     

       121
       121
       +
       type 'a set_response = {

     

       122
       122
       +
         account_id : Id.t;

     

       123
       123
       +
         old_state : string option;

     

       124
       124
       +
         new_state : string;

     

       125
       125
       +
         created : (Id.t * 'a) list option;

     

       126
       126
       +
         updated : (Id.t * 'a option) list option;

     

       127
       127
       +
         destroyed : Id.t list option;

     

       128
       128
       +
         not_created : (Id.t * Error.set_error) list option;

     

       129
       129
       +
         not_updated : (Id.t * Error.set_error) list option;

     

       130
       130
       +
         not_destroyed : (Id.t * Error.set_error) list option;

     

       131
       131
       +
       }

     

       132
       132
       +
       

     

       133
       133
       +
       let set_response_jsont (type a) (obj_jsont : a Jsont.t) : a set_response Jsont.t =

     

       134
       134
       +
         let kind = "SetResponse" in

     

       135
       135
       +
         let make account_id old_state new_state created updated destroyed

     

       136
       136
       +
             not_created not_updated not_destroyed =

     

       137
       137
       +
           { account_id; old_state; new_state; created; updated; destroyed;

     

       138
       138
       +
             not_created; not_updated; not_destroyed }

     

       139
       139
       +
         in

     

       140
       140
       +
         (* For updated values, the server may return null or an object *)

     

       141
       141
       +
         let nullable_obj = Jsont.(some obj_jsont) in

     

       142
       142
       +
         Jsont.Object.map ~kind make

     

       143
       143
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun r -> r.account_id)

     

       144
       144
       +
         |> Jsont.Object.opt_mem "oldState" Jsont.string ~enc:(fun r -> r.old_state)

     

       145
       145
       +
         |> Jsont.Object.mem "newState" Jsont.string ~enc:(fun r -> r.new_state)

     

       146
       146
       +
         |> Jsont.Object.opt_mem "created" (Json_map.of_id obj_jsont) ~enc:(fun r -> r.created)

     

       147
       147
       +
         |> Jsont.Object.opt_mem "updated" (Json_map.of_id nullable_obj) ~enc:(fun r -> r.updated)

     

       148
       148
       +
         |> Jsont.Object.opt_mem "destroyed" (Jsont.list Id.jsont) ~enc:(fun r -> r.destroyed)

     

       149
       149
       +
         |> Jsont.Object.opt_mem "notCreated" (Json_map.of_id Error.set_error_jsont) ~enc:(fun r -> r.not_created)

     

       150
       150
       +
         |> Jsont.Object.opt_mem "notUpdated" (Json_map.of_id Error.set_error_jsont) ~enc:(fun r -> r.not_updated)

     

       151
       151
       +
         |> Jsont.Object.opt_mem "notDestroyed" (Json_map.of_id Error.set_error_jsont) ~enc:(fun r -> r.not_destroyed)

     

       152
       152
       +
         |> Jsont.Object.finish

     

       153
       153
       +
       

     

       154
       154
       +
       (* Foo/copy *)

     

       155
       155
       +
       

     

       156
       156
       +
       type 'a copy_args = {

     

       157
       157
       +
         from_account_id : Id.t;

     

       158
       158
       +
         if_from_in_state : string option;

     

       159
       159
       +
         account_id : Id.t;

     

       160
       160
       +
         if_in_state : string option;

     

       161
       161
       +
         create : (Id.t * 'a) list;

     

       162
       162
       +
         on_success_destroy_original : bool;

     

       163
       163
       +
         destroy_from_if_in_state : string option;

     

       164
       164
       +
       }

     

       165
       165
       +
       

     

       166
       166
       +
       let copy_args_jsont (type a) (obj_jsont : a Jsont.t) : a copy_args Jsont.t =

     

       167
       167
       +
         let kind = "CopyArgs" in

     

       168
       168
       +
         let make from_account_id if_from_in_state account_id if_in_state create

     

       169
       169
       +
             on_success_destroy_original destroy_from_if_in_state =

     

       170
       170
       +
           { from_account_id; if_from_in_state; account_id; if_in_state; create;

     

       171
       171
       +
             on_success_destroy_original; destroy_from_if_in_state }

     

       172
       172
       +
         in

     

       173
       173
       +
         Jsont.Object.map ~kind make

     

       174
       174
       +
         |> Jsont.Object.mem "fromAccountId" Id.jsont ~enc:(fun a -> a.from_account_id)

     

       175
       175
       +
         |> Jsont.Object.opt_mem "ifFromInState" Jsont.string ~enc:(fun a -> a.if_from_in_state)

     

       176
       176
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun a -> a.account_id)

     

       177
       177
       +
         |> Jsont.Object.opt_mem "ifInState" Jsont.string ~enc:(fun a -> a.if_in_state)

     

       178
       178
       +
         |> Jsont.Object.mem "create" (Json_map.of_id obj_jsont) ~enc:(fun a -> a.create)

     

       179
       179
       +
         |> Jsont.Object.mem "onSuccessDestroyOriginal" Jsont.bool ~dec_absent:false

     

       180
       180
       +
              ~enc:(fun a -> a.on_success_destroy_original)

     

       181
       181
       +
              ~enc_omit:(fun b -> not b)

     

       182
       182
       +
         |> Jsont.Object.opt_mem "destroyFromIfInState" Jsont.string ~enc:(fun a -> a.destroy_from_if_in_state)

     

       183
       183
       +
         |> Jsont.Object.finish

     

       184
       184
       +
       

     

       185
       185
       +
       type 'a copy_response = {

     

       186
       186
       +
         from_account_id : Id.t;

     

       187
       187
       +
         account_id : Id.t;

     

       188
       188
       +
         old_state : string option;

     

       189
       189
       +
         new_state : string;

     

       190
       190
       +
         created : (Id.t * 'a) list option;

     

       191
       191
       +
         not_created : (Id.t * Error.set_error) list option;

     

       192
       192
       +
       }

     

       193
       193
       +
       

     

       194
       194
       +
       let copy_response_jsont (type a) (obj_jsont : a Jsont.t) : a copy_response Jsont.t =

     

       195
       195
       +
         let kind = "CopyResponse" in

     

       196
       196
       +
         let make from_account_id account_id old_state new_state created not_created =

     

       197
       197
       +
           { from_account_id; account_id; old_state; new_state; created; not_created }

     

       198
       198
       +
         in

     

       199
       199
       +
         Jsont.Object.map ~kind make

     

       200
       200
       +
         |> Jsont.Object.mem "fromAccountId" Id.jsont ~enc:(fun r -> r.from_account_id)

     

       201
       201
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun r -> r.account_id)

     

       202
       202
       +
         |> Jsont.Object.opt_mem "oldState" Jsont.string ~enc:(fun r -> r.old_state)

     

       203
       203
       +
         |> Jsont.Object.mem "newState" Jsont.string ~enc:(fun r -> r.new_state)

     

       204
       204
       +
         |> Jsont.Object.opt_mem "created" (Json_map.of_id obj_jsont) ~enc:(fun r -> r.created)

     

       205
       205
       +
         |> Jsont.Object.opt_mem "notCreated" (Json_map.of_id Error.set_error_jsont) ~enc:(fun r -> r.not_created)

     

       206
       206
       +
         |> Jsont.Object.finish

     

       207
       207
       +
       

     

       208
       208
       +
       (* Foo/query *)

     

       209
       209
       +
       

     

       210
       210
       +
       type 'filter query_args = {

     

       211
       211
       +
         account_id : Id.t;

     

       212
       212
       +
         filter : 'filter Filter.filter option;

     

       213
       213
       +
         sort : Filter.comparator list option;

     

       214
       214
       +
         position : int64;

     

       215
       215
       +
         anchor : Id.t option;

     

       216
       216
       +
         anchor_offset : int64;

     

       217
       217
       +
         limit : int64 option;

     

       218
       218
       +
         calculate_total : bool;

     

       219
       219
       +
       }

     

       220
       220
       +
       

     

       221
       221
       +
       let query_args ~account_id ?filter ?sort ?(position = 0L) ?anchor

     

       222
       222
       +
           ?(anchor_offset = 0L) ?limit ?(calculate_total = false) () =

     

       223
       223
       +
         { account_id; filter; sort; position; anchor; anchor_offset; limit; calculate_total }

     

       224
       224
       +
       

     

       225
       225
       +
       let query_args_jsont (type f) (filter_cond_jsont : f Jsont.t) : f query_args Jsont.t =

     

       226
       226
       +
         let kind = "QueryArgs" in

     

       227
       227
       +
         let make account_id filter sort position anchor anchor_offset limit calculate_total =

     

       228
       228
       +
           { account_id; filter; sort; position; anchor; anchor_offset; limit; calculate_total }

     

       229
       229
       +
         in

     

       230
       230
       +
         Jsont.Object.map ~kind make

     

       231
       231
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun a -> a.account_id)

     

       232
       232
       +
         |> Jsont.Object.opt_mem "filter" (Filter.filter_jsont filter_cond_jsont) ~enc:(fun a -> a.filter)

     

       233
       233
       +
         |> Jsont.Object.opt_mem "sort" (Jsont.list Filter.comparator_jsont) ~enc:(fun a -> a.sort)

     

       234
       234
       +
         |> Jsont.Object.mem "position" Int53.Signed.jsont ~dec_absent:0L ~enc:(fun a -> a.position)

     

       235
       235
       +
              ~enc_omit:(fun p -> p = 0L)

     

       236
       236
       +
         |> Jsont.Object.opt_mem "anchor" Id.jsont ~enc:(fun a -> a.anchor)

     

       237
       237
       +
         |> Jsont.Object.mem "anchorOffset" Int53.Signed.jsont ~dec_absent:0L ~enc:(fun a -> a.anchor_offset)

     

       238
       238
       +
              ~enc_omit:(fun o -> o = 0L)

     

       239
       239
       +
         |> Jsont.Object.opt_mem "limit" Int53.Unsigned.jsont ~enc:(fun a -> a.limit)

     

       240
       240
       +
         |> Jsont.Object.mem "calculateTotal" Jsont.bool ~dec_absent:false ~enc:(fun a -> a.calculate_total)

     

       241
       241
       +
              ~enc_omit:(fun b -> not b)

     

       242
       242
       +
         |> Jsont.Object.finish

     

       243
       243
       +
       

     

       244
       244
       +
       type query_response = {

     

       245
       245
       +
         account_id : Id.t;

     

       246
       246
       +
         query_state : string;

     

       247
       247
       +
         can_calculate_changes : bool;

     

       248
       248
       +
         position : int64;

     

       249
       249
       +
         ids : Id.t list;

     

       250
       250
       +
         total : int64 option;

     

       251
       251
       +
       }

     

       252
       252
       +
       

     

       253
       253
       +
       let query_response_make account_id query_state can_calculate_changes position ids total =

     

       254
       254
       +
         { account_id; query_state; can_calculate_changes; position; ids; total }

     

       255
       255
       +
       

     

       256
       256
       +
       let query_response_jsont =

     

       257
       257
       +
         let kind = "QueryResponse" in

     

       258
       258
       +
         Jsont.Object.map ~kind query_response_make

     

       259
       259
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun r -> r.account_id)

     

       260
       260
       +
         |> Jsont.Object.mem "queryState" Jsont.string ~enc:(fun r -> r.query_state)

     

       261
       261
       +
         |> Jsont.Object.mem "canCalculateChanges" Jsont.bool ~enc:(fun r -> r.can_calculate_changes)

     

       262
       262
       +
         |> Jsont.Object.mem "position" Int53.Unsigned.jsont ~enc:(fun r -> r.position)

     

       263
       263
       +
         |> Jsont.Object.mem "ids" (Jsont.list Id.jsont) ~enc:(fun r -> r.ids)

     

       264
       264
       +
         |> Jsont.Object.opt_mem "total" Int53.Unsigned.jsont ~enc:(fun r -> r.total)

     

       265
       265
       +
         |> Jsont.Object.finish

     

       266
       266
       +
       

     

       267
       267
       +
       (* Foo/queryChanges *)

     

       268
       268
       +
       

     

       269
       269
       +
       type 'filter query_changes_args = {

     

       270
       270
       +
         account_id : Id.t;

     

       271
       271
       +
         filter : 'filter Filter.filter option;

     

       272
       272
       +
         sort : Filter.comparator list option;

     

       273
       273
       +
         since_query_state : string;

     

       274
       274
       +
         max_changes : int64 option;

     

       275
       275
       +
         up_to_id : Id.t option;

     

       276
       276
       +
         calculate_total : bool;

     

       277
       277
       +
       }

     

       278
       278
       +
       

     

       279
       279
       +
       let query_changes_args_jsont (type f) (filter_cond_jsont : f Jsont.t) : f query_changes_args Jsont.t =

     

       280
       280
       +
         let kind = "QueryChangesArgs" in

     

       281
       281
       +
         let make account_id filter sort since_query_state max_changes up_to_id calculate_total =

     

       282
       282
       +
           { account_id; filter; sort; since_query_state; max_changes; up_to_id; calculate_total }

     

       283
       283
       +
         in

     

       284
       284
       +
         Jsont.Object.map ~kind make

     

       285
       285
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun a -> a.account_id)

     

       286
       286
       +
         |> Jsont.Object.opt_mem "filter" (Filter.filter_jsont filter_cond_jsont) ~enc:(fun a -> a.filter)

     

       287
       287
       +
         |> Jsont.Object.opt_mem "sort" (Jsont.list Filter.comparator_jsont) ~enc:(fun a -> a.sort)

     

       288
       288
       +
         |> Jsont.Object.mem "sinceQueryState" Jsont.string ~enc:(fun a -> a.since_query_state)

     

       289
       289
       +
         |> Jsont.Object.opt_mem "maxChanges" Int53.Unsigned.jsont ~enc:(fun a -> a.max_changes)

     

       290
       290
       +
         |> Jsont.Object.opt_mem "upToId" Id.jsont ~enc:(fun a -> a.up_to_id)

     

       291
       291
       +
         |> Jsont.Object.mem "calculateTotal" Jsont.bool ~dec_absent:false ~enc:(fun a -> a.calculate_total)

     

       292
       292
       +
              ~enc_omit:(fun b -> not b)

     

       293
       293
       +
         |> Jsont.Object.finish

     

       294
       294
       +
       

     

       295
       295
       +
       type query_changes_response = {

     

       296
       296
       +
         account_id : Id.t;

     

       297
       297
       +
         old_query_state : string;

     

       298
       298
       +
         new_query_state : string;

     

       299
       299
       +
         total : int64 option;

     

       300
       300
       +
         removed : Id.t list;

     

       301
       301
       +
         added : Filter.added_item list;

     

       302
       302
       +
       }

     

       303
       303
       +
       

     

       304
       304
       +
       let query_changes_response_make account_id old_query_state new_query_state total removed added =

     

       305
       305
       +
         { account_id; old_query_state; new_query_state; total; removed; added }

     

       306
       306
       +
       

     

       307
       307
       +
       let query_changes_response_jsont =

     

       308
       308
       +
         let kind = "QueryChangesResponse" in

     

       309
       309
       +
         Jsont.Object.map ~kind query_changes_response_make

     

       310
       310
       +
         |> Jsont.Object.mem "accountId" Id.jsont ~enc:(fun r -> r.account_id)

     

       311
       311
       +
         |> Jsont.Object.mem "oldQueryState" Jsont.string ~enc:(fun r -> r.old_query_state)

     

       312
       312
       +
         |> Jsont.Object.mem "newQueryState" Jsont.string ~enc:(fun r -> r.new_query_state)

     

       313
       313
       +
         |> Jsont.Object.opt_mem "total" Int53.Unsigned.jsont ~enc:(fun r -> r.total)

     

       314
       314
       +
         |> Jsont.Object.mem "removed" (Jsont.list Id.jsont) ~enc:(fun r -> r.removed)

     

       315
       315
       +
         |> Jsont.Object.mem "added" (Jsont.list Filter.added_item_jsont) ~enc:(fun r -> r.added)

     

       316
       316
       +
         |> Jsont.Object.finish

+215

proto/method_.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP standard method types as defined in RFC 8620 Section 5 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Foo/get} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** Arguments for /get methods. *)

     

       11
       11
       +
       type get_args = {

     

       12
       12
       +
         account_id : Id.t;

     

       13
       13
       +
         (** The account to fetch from. *)

     

       14
       14
       +
         ids : Id.t list option;

     

       15
       15
       +
         (** The ids to fetch. [None] means fetch all. *)

     

       16
       16
       +
         properties : string list option;

     

       17
       17
       +
         (** Properties to include. [None] means all. *)

     

       18
       18
       +
       }

     

       19
       19
       +
       

     

       20
       20
       +
       val get_args :

     

       21
       21
       +
         account_id:Id.t ->

     

       22
       22
       +
         ?ids:Id.t list ->

     

       23
       23
       +
         ?properties:string list ->

     

       24
       24
       +
         unit ->

     

       25
       25
       +
         get_args

     

       26
       26
       +
       

     

       27
       27
       +
       val get_args_jsont : get_args Jsont.t

     

       28
       28
       +
       

     

       29
       29
       +
       (** Response for /get methods. *)

     

       30
       30
       +
       type 'a get_response = {

     

       31
       31
       +
         account_id : Id.t;

     

       32
       32
       +
         (** The account fetched from. *)

     

       33
       33
       +
         state : string;

     

       34
       34
       +
         (** Current state string. *)

     

       35
       35
       +
         list : 'a list;

     

       36
       36
       +
         (** The objects fetched. *)

     

       37
       37
       +
         not_found : Id.t list;

     

       38
       38
       +
         (** Ids that were not found. *)

     

       39
       39
       +
       }

     

       40
       40
       +
       

     

       41
       41
       +
       val get_response_jsont : 'a Jsont.t -> 'a get_response Jsont.t

     

       42
       42
       +
       

     

       43
       43
       +
       (** {1 Foo/changes} *)

     

       44
       44
       +
       

     

       45
       45
       +
       (** Arguments for /changes methods. *)

     

       46
       46
       +
       type changes_args = {

     

       47
       47
       +
         account_id : Id.t;

     

       48
       48
       +
         since_state : string;

     

       49
       49
       +
         max_changes : int64 option;

     

       50
       50
       +
       }

     

       51
       51
       +
       

     

       52
       52
       +
       val changes_args :

     

       53
       53
       +
         account_id:Id.t ->

     

       54
       54
       +
         since_state:string ->

     

       55
       55
       +
         ?max_changes:int64 ->

     

       56
       56
       +
         unit ->

     

       57
       57
       +
         changes_args

     

       58
       58
       +
       

     

       59
       59
       +
       val changes_args_jsont : changes_args Jsont.t

     

       60
       60
       +
       

     

       61
       61
       +
       (** Response for /changes methods. *)

     

       62
       62
       +
       type changes_response = {

     

       63
       63
       +
         account_id : Id.t;

     

       64
       64
       +
         old_state : string;

     

       65
       65
       +
         new_state : string;

     

       66
       66
       +
         has_more_changes : bool;

     

       67
       67
       +
         created : Id.t list;

     

       68
       68
       +
         updated : Id.t list;

     

       69
       69
       +
         destroyed : Id.t list;

     

       70
       70
       +
       }

     

       71
       71
       +
       

     

       72
       72
       +
       val changes_response_jsont : changes_response Jsont.t

     

       73
       73
       +
       

     

       74
       74
       +
       (** {1 Foo/set} *)

     

       75
       75
       +
       

     

       76
       76
       +
       (** Arguments for /set methods.

     

       77
       77
       +
       

     

       78
       78
       +
           The ['a] type parameter is the object type being created/updated. *)

     

       79
       79
       +
       type 'a set_args = {

     

       80
       80
       +
         account_id : Id.t;

     

       81
       81
       +
         if_in_state : string option;

     

       82
       82
       +
         (** If set, only apply if current state matches. *)

     

       83
       83
       +
         create : (Id.t * 'a) list option;

     

       84
       84
       +
         (** Objects to create, keyed by temporary id. *)

     

       85
       85
       +
         update : (Id.t * Jsont.json) list option;

     

       86
       86
       +
         (** Objects to update. Value is a PatchObject. *)

     

       87
       87
       +
         destroy : Id.t list option;

     

       88
       88
       +
         (** Ids to destroy. *)

     

       89
       89
       +
       }

     

       90
       90
       +
       

     

       91
       91
       +
       val set_args :

     

       92
       92
       +
         account_id:Id.t ->

     

       93
       93
       +
         ?if_in_state:string ->

     

       94
       94
       +
         ?create:(Id.t * 'a) list ->

     

       95
       95
       +
         ?update:(Id.t * Jsont.json) list ->

     

       96
       96
       +
         ?destroy:Id.t list ->

     

       97
       97
       +
         unit ->

     

       98
       98
       +
         'a set_args

     

       99
       99
       +
       

     

       100
       100
       +
       val set_args_jsont : 'a Jsont.t -> 'a set_args Jsont.t

     

       101
       101
       +
       

     

       102
       102
       +
       (** Response for /set methods. *)

     

       103
       103
       +
       type 'a set_response = {

     

       104
       104
       +
         account_id : Id.t;

     

       105
       105
       +
         old_state : string option;

     

       106
       106
       +
         new_state : string;

     

       107
       107
       +
         created : (Id.t * 'a) list option;

     

       108
       108
       +
         (** Successfully created objects, keyed by temporary id. *)

     

       109
       109
       +
         updated : (Id.t * 'a option) list option;

     

       110
       110
       +
         (** Successfully updated objects. Value may include server-set properties. *)

     

       111
       111
       +
         destroyed : Id.t list option;

     

       112
       112
       +
         (** Successfully destroyed ids. *)

     

       113
       113
       +
         not_created : (Id.t * Error.set_error) list option;

     

       114
       114
       +
         (** Failed creates. *)

     

       115
       115
       +
         not_updated : (Id.t * Error.set_error) list option;

     

       116
       116
       +
         (** Failed updates. *)

     

       117
       117
       +
         not_destroyed : (Id.t * Error.set_error) list option;

     

       118
       118
       +
         (** Failed destroys. *)

     

       119
       119
       +
       }

     

       120
       120
       +
       

     

       121
       121
       +
       val set_response_jsont : 'a Jsont.t -> 'a set_response Jsont.t

     

       122
       122
       +
       

     

       123
       123
       +
       (** {1 Foo/copy} *)

     

       124
       124
       +
       

     

       125
       125
       +
       (** Arguments for /copy methods. *)

     

       126
       126
       +
       type 'a copy_args = {

     

       127
       127
       +
         from_account_id : Id.t;

     

       128
       128
       +
         if_from_in_state : string option;

     

       129
       129
       +
         account_id : Id.t;

     

       130
       130
       +
         if_in_state : string option;

     

       131
       131
       +
         create : (Id.t * 'a) list;

     

       132
       132
       +
         on_success_destroy_original : bool;

     

       133
       133
       +
         destroy_from_if_in_state : string option;

     

       134
       134
       +
       }

     

       135
       135
       +
       

     

       136
       136
       +
       val copy_args_jsont : 'a Jsont.t -> 'a copy_args Jsont.t

     

       137
       137
       +
       

     

       138
       138
       +
       (** Response for /copy methods. *)

     

       139
       139
       +
       type 'a copy_response = {

     

       140
       140
       +
         from_account_id : Id.t;

     

       141
       141
       +
         account_id : Id.t;

     

       142
       142
       +
         old_state : string option;

     

       143
       143
       +
         new_state : string;

     

       144
       144
       +
         created : (Id.t * 'a) list option;

     

       145
       145
       +
         not_created : (Id.t * Error.set_error) list option;

     

       146
       146
       +
       }

     

       147
       147
       +
       

     

       148
       148
       +
       val copy_response_jsont : 'a Jsont.t -> 'a copy_response Jsont.t

     

       149
       149
       +
       

     

       150
       150
       +
       (** {1 Foo/query} *)

     

       151
       151
       +
       

     

       152
       152
       +
       (** Arguments for /query methods. *)

     

       153
       153
       +
       type 'filter query_args = {

     

       154
       154
       +
         account_id : Id.t;

     

       155
       155
       +
         filter : 'filter Filter.filter option;

     

       156
       156
       +
         sort : Filter.comparator list option;

     

       157
       157
       +
         position : int64;

     

       158
       158
       +
         anchor : Id.t option;

     

       159
       159
       +
         anchor_offset : int64;

     

       160
       160
       +
         limit : int64 option;

     

       161
       161
       +
         calculate_total : bool;

     

       162
       162
       +
       }

     

       163
       163
       +
       

     

       164
       164
       +
       val query_args :

     

       165
       165
       +
         account_id:Id.t ->

     

       166
       166
       +
         ?filter:'filter Filter.filter ->

     

       167
       167
       +
         ?sort:Filter.comparator list ->

     

       168
       168
       +
         ?position:int64 ->

     

       169
       169
       +
         ?anchor:Id.t ->

     

       170
       170
       +
         ?anchor_offset:int64 ->

     

       171
       171
       +
         ?limit:int64 ->

     

       172
       172
       +
         ?calculate_total:bool ->

     

       173
       173
       +
         unit ->

     

       174
       174
       +
         'filter query_args

     

       175
       175
       +
       

     

       176
       176
       +
       val query_args_jsont : 'filter Jsont.t -> 'filter query_args Jsont.t

     

       177
       177
       +
       

     

       178
       178
       +
       (** Response for /query methods. *)

     

       179
       179
       +
       type query_response = {

     

       180
       180
       +
         account_id : Id.t;

     

       181
       181
       +
         query_state : string;

     

       182
       182
       +
         can_calculate_changes : bool;

     

       183
       183
       +
         position : int64;

     

       184
       184
       +
         ids : Id.t list;

     

       185
       185
       +
         total : int64 option;

     

       186
       186
       +
       }

     

       187
       187
       +
       

     

       188
       188
       +
       val query_response_jsont : query_response Jsont.t

     

       189
       189
       +
       

     

       190
       190
       +
       (** {1 Foo/queryChanges} *)

     

       191
       191
       +
       

     

       192
       192
       +
       (** Arguments for /queryChanges methods. *)

     

       193
       193
       +
       type 'filter query_changes_args = {

     

       194
       194
       +
         account_id : Id.t;

     

       195
       195
       +
         filter : 'filter Filter.filter option;

     

       196
       196
       +
         sort : Filter.comparator list option;

     

       197
       197
       +
         since_query_state : string;

     

       198
       198
       +
         max_changes : int64 option;

     

       199
       199
       +
         up_to_id : Id.t option;

     

       200
       200
       +
         calculate_total : bool;

     

       201
       201
       +
       }

     

       202
       202
       +
       

     

       203
       203
       +
       val query_changes_args_jsont : 'filter Jsont.t -> 'filter query_changes_args Jsont.t

     

       204
       204
       +
       

     

       205
       205
       +
       (** Response for /queryChanges methods. *)

     

       206
       206
       +
       type query_changes_response = {

     

       207
       207
       +
         account_id : Id.t;

     

       208
       208
       +
         old_query_state : string;

     

       209
       209
       +
         new_query_state : string;

     

       210
       210
       +
         total : int64 option;

     

       211
       211
       +
         removed : Id.t list;

     

       212
       212
       +
         added : Filter.added_item list;

     

       213
       213
       +
       }

     

       214
       214
       +
       

     

       215
       215
       +
       val query_changes_response_jsont : query_changes_response Jsont.t

+132

proto/push.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       module State_change = struct

     

       7
       7
       +
         type type_state = {

     

       8
       8
       +
           type_name : string;

     

       9
       9
       +
           state : string;

     

       10
       10
       +
         }

     

       11
       11
       +
       

     

       12
       12
       +
         type t = {

     

       13
       13
       +
           type_ : string;

     

       14
       14
       +
           changed : (Id.t * type_state list) list;

     

       15
       15
       +
         }

     

       16
       16
       +
       

     

       17
       17
       +
         (* The changed object is account_id -> { typeName: state } *)

     

       18
       18
       +
         let changed_jsont =

     

       19
       19
       +
           let kind = "Changed" in

     

       20
       20
       +
           (* Inner is type -> state string map *)

     

       21
       21
       +
           let type_states_jsont = Json_map.of_string Jsont.string in

     

       22
       22
       +
           (* Convert list of (string * string) to type_state list *)

     

       23
       23
       +
           let decode_type_states pairs =

     

       24
       24
       +
             List.map (fun (type_name, state) -> { type_name; state }) pairs

     

       25
       25
       +
           in

     

       26
       26
       +
           let encode_type_states states =

     

       27
       27
       +
             List.map (fun ts -> (ts.type_name, ts.state)) states

     

       28
       28
       +
           in

     

       29
       29
       +
           Json_map.of_id

     

       30
       30
       +
             (Jsont.map ~kind ~dec:decode_type_states ~enc:encode_type_states type_states_jsont)

     

       31
       31
       +
       

     

       32
       32
       +
         let make type_ changed = { type_; changed }

     

       33
       33
       +
       

     

       34
       34
       +
         let jsont =

     

       35
       35
       +
           let kind = "StateChange" in

     

       36
       36
       +
           Jsont.Object.map ~kind make

     

       37
       37
       +
           |> Jsont.Object.mem "@type" Jsont.string ~enc:(fun t -> t.type_)

     

       38
       38
       +
           |> Jsont.Object.mem "changed" changed_jsont ~enc:(fun t -> t.changed)

     

       39
       39
       +
           |> Jsont.Object.finish

     

       40
       40
       +
       end

     

       41
       41
       +
       

     

       42
       42
       +
       type push_keys = {

     

       43
       43
       +
         p256dh : string;

     

       44
       44
       +
         auth : string;

     

       45
       45
       +
       }

     

       46
       46
       +
       

     

       47
       47
       +
       let push_keys_make p256dh auth = { p256dh; auth }

     

       48
       48
       +
       

     

       49
       49
       +
       let push_keys_jsont =

     

       50
       50
       +
         let kind = "PushKeys" in

     

       51
       51
       +
         Jsont.Object.map ~kind push_keys_make

     

       52
       52
       +
         |> Jsont.Object.mem "p256dh" Jsont.string ~enc:(fun k -> k.p256dh)

     

       53
       53
       +
         |> Jsont.Object.mem "auth" Jsont.string ~enc:(fun k -> k.auth)

     

       54
       54
       +
         |> Jsont.Object.finish

     

       55
       55
       +
       

     

       56
       56
       +
       type t = {

     

       57
       57
       +
         id : Id.t;

     

       58
       58
       +
         device_client_id : string;

     

       59
       59
       +
         url : string;

     

       60
       60
       +
         keys : push_keys option;

     

       61
       61
       +
         verification_code : string option;

     

       62
       62
       +
         expires : Ptime.t option;

     

       63
       63
       +
         types : string list option;

     

       64
       64
       +
       }

     

       65
       65
       +
       

     

       66
       66
       +
       let id t = t.id

     

       67
       67
       +
       let device_client_id t = t.device_client_id

     

       68
       68
       +
       let url t = t.url

     

       69
       69
       +
       let keys t = t.keys

     

       70
       70
       +
       let verification_code t = t.verification_code

     

       71
       71
       +
       let expires t = t.expires

     

       72
       72
       +
       let types t = t.types

     

       73
       73
       +
       

     

       74
       74
       +
       let make id device_client_id url keys verification_code expires types =

     

       75
       75
       +
         { id; device_client_id; url; keys; verification_code; expires; types }

     

       76
       76
       +
       

     

       77
       77
       +
       let jsont =

     

       78
       78
       +
         let kind = "PushSubscription" in

     

       79
       79
       +
         Jsont.Object.map ~kind make

     

       80
       80
       +
         |> Jsont.Object.mem "id" Id.jsont ~enc:id

     

       81
       81
       +
         |> Jsont.Object.mem "deviceClientId" Jsont.string ~enc:device_client_id

     

       82
       82
       +
         |> Jsont.Object.mem "url" Jsont.string ~enc:url

     

       83
       83
       +
         |> Jsont.Object.opt_mem "keys" push_keys_jsont ~enc:keys

     

       84
       84
       +
         |> Jsont.Object.opt_mem "verificationCode" Jsont.string ~enc:verification_code

     

       85
       85
       +
         |> Jsont.Object.opt_mem "expires" Date.Utc.jsont ~enc:expires

     

       86
       86
       +
         |> Jsont.Object.opt_mem "types" (Jsont.list Jsont.string) ~enc:types

     

       87
       87
       +
         |> Jsont.Object.finish

     

       88
       88
       +
       

     

       89
       89
       +
       let get_args_jsont = Method_.get_args_jsont

     

       90
       90
       +
       let get_response_jsont = Method_.get_response_jsont jsont

     

       91
       91
       +
       

     

       92
       92
       +
       type create_args = {

     

       93
       93
       +
         device_client_id : string;

     

       94
       94
       +
         url : string;

     

       95
       95
       +
         keys : push_keys option;

     

       96
       96
       +
         verification_code : string option;

     

       97
       97
       +
         types : string list option;

     

       98
       98
       +
       }

     

       99
       99
       +
       

     

       100
       100
       +
       let create_args_make device_client_id url keys verification_code types =

     

       101
       101
       +
         { device_client_id; url; keys; verification_code; types }

     

       102
       102
       +
       

     

       103
       103
       +
       let create_args_jsont =

     

       104
       104
       +
         let kind = "PushSubscription create" in

     

       105
       105
       +
         Jsont.Object.map ~kind create_args_make

     

       106
       106
       +
         |> Jsont.Object.mem "deviceClientId" Jsont.string ~enc:(fun a -> a.device_client_id)

     

       107
       107
       +
         |> Jsont.Object.mem "url" Jsont.string ~enc:(fun a -> a.url)

     

       108
       108
       +
         |> Jsont.Object.opt_mem "keys" push_keys_jsont ~enc:(fun a -> a.keys)

     

       109
       109
       +
         |> Jsont.Object.opt_mem "verificationCode" Jsont.string ~enc:(fun a -> a.verification_code)

     

       110
       110
       +
         |> Jsont.Object.opt_mem "types" (Jsont.list Jsont.string) ~enc:(fun a -> a.types)

     

       111
       111
       +
         |> Jsont.Object.finish

     

       112
       112
       +
       

     

       113
       113
       +
       type set_args = {

     

       114
       114
       +
         account_id : Id.t option;

     

       115
       115
       +
         if_in_state : string option;

     

       116
       116
       +
         create : (Id.t * create_args) list option;

     

       117
       117
       +
         update : (Id.t * Jsont.json) list option;

     

       118
       118
       +
         destroy : Id.t list option;

     

       119
       119
       +
       }

     

       120
       120
       +
       

     

       121
       121
       +
       let set_args_make account_id if_in_state create update destroy =

     

       122
       122
       +
         { account_id; if_in_state; create; update; destroy }

     

       123
       123
       +
       

     

       124
       124
       +
       let set_args_jsont =

     

       125
       125
       +
         let kind = "PushSubscription/set args" in

     

       126
       126
       +
         Jsont.Object.map ~kind set_args_make

     

       127
       127
       +
         |> Jsont.Object.opt_mem "accountId" Id.jsont ~enc:(fun a -> a.account_id)

     

       128
       128
       +
         |> Jsont.Object.opt_mem "ifInState" Jsont.string ~enc:(fun a -> a.if_in_state)

     

       129
       129
       +
         |> Jsont.Object.opt_mem "create" (Json_map.of_id create_args_jsont) ~enc:(fun a -> a.create)

     

       130
       130
       +
         |> Jsont.Object.opt_mem "update" (Json_map.of_id Jsont.json) ~enc:(fun a -> a.update)

     

       131
       131
       +
         |> Jsont.Object.opt_mem "destroy" (Jsont.list Id.jsont) ~enc:(fun a -> a.destroy)

     

       132
       132
       +
         |> Jsont.Object.finish

+96

proto/push.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP push types as defined in RFC 8620 Section 7 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 StateChange} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** A state change notification for push. *)

     

       11
       11
       +
       module State_change : sig

     

       12
       12
       +
         type type_state = {

     

       13
       13
       +
           type_name : string;

     

       14
       14
       +
           (** The data type that changed (e.g., "Email", "Mailbox"). *)

     

       15
       15
       +
           state : string;

     

       16
       16
       +
           (** The new state string for this type. *)

     

       17
       17
       +
         }

     

       18
       18
       +
       

     

       19
       19
       +
         type t = {

     

       20
       20
       +
           type_ : string;

     

       21
       21
       +
           (** Always "StateChange". *)

     

       22
       22
       +
           changed : (Id.t * type_state list) list;

     

       23
       23
       +
           (** Map of account id to list of type state changes. *)

     

       24
       24
       +
         }

     

       25
       25
       +
       

     

       26
       26
       +
         val jsont : t Jsont.t

     

       27
       27
       +
       end

     

       28
       28
       +
       

     

       29
       29
       +
       (** {1 PushSubscription} *)

     

       30
       30
       +
       

     

       31
       31
       +
       (** Web push subscription keys. *)

     

       32
       32
       +
       type push_keys = {

     

       33
       33
       +
         p256dh : string;

     

       34
       34
       +
         (** P-256 ECDH public key as URL-safe base64. *)

     

       35
       35
       +
         auth : string;

     

       36
       36
       +
         (** Authentication secret as URL-safe base64. *)

     

       37
       37
       +
       }

     

       38
       38
       +
       

     

       39
       39
       +
       val push_keys_jsont : push_keys Jsont.t

     

       40
       40
       +
       

     

       41
       41
       +
       (** A push subscription object. *)

     

       42
       42
       +
       type t = {

     

       43
       43
       +
         id : Id.t;

     

       44
       44
       +
         (** Server-assigned subscription id. *)

     

       45
       45
       +
         device_client_id : string;

     

       46
       46
       +
         (** Client-provided device identifier. *)

     

       47
       47
       +
         url : string;

     

       48
       48
       +
         (** The push endpoint URL. *)

     

       49
       49
       +
         keys : push_keys option;

     

       50
       50
       +
         (** Optional encryption keys for Web Push. *)

     

       51
       51
       +
         verification_code : string option;

     

       52
       52
       +
         (** Code for verifying subscription ownership. *)

     

       53
       53
       +
         expires : Ptime.t option;

     

       54
       54
       +
         (** When the subscription expires. *)

     

       55
       55
       +
         types : string list option;

     

       56
       56
       +
         (** Data types to receive notifications for. [None] means all. *)

     

       57
       57
       +
       }

     

       58
       58
       +
       

     

       59
       59
       +
       val id : t -> Id.t

     

       60
       60
       +
       val device_client_id : t -> string

     

       61
       61
       +
       val url : t -> string

     

       62
       62
       +
       val keys : t -> push_keys option

     

       63
       63
       +
       val verification_code : t -> string option

     

       64
       64
       +
       val expires : t -> Ptime.t option

     

       65
       65
       +
       val types : t -> string list option

     

       66
       66
       +
       

     

       67
       67
       +
       val jsont : t Jsont.t

     

       68
       68
       +
       (** JSON codec for PushSubscription. *)

     

       69
       69
       +
       

     

       70
       70
       +
       (** {1 PushSubscription Methods} *)

     

       71
       71
       +
       

     

       72
       72
       +
       (** Arguments for PushSubscription/get. *)

     

       73
       73
       +
       val get_args_jsont : Method_.get_args Jsont.t

     

       74
       74
       +
       

     

       75
       75
       +
       (** Response for PushSubscription/get. *)

     

       76
       76
       +
       val get_response_jsont : t Method_.get_response Jsont.t

     

       77
       77
       +
       

     

       78
       78
       +
       (** Arguments for PushSubscription/set. *)

     

       79
       79
       +
       type set_args = {

     

       80
       80
       +
         account_id : Id.t option;

     

       81
       81
       +
         (** Not used for PushSubscription. *)

     

       82
       82
       +
         if_in_state : string option;

     

       83
       83
       +
         create : (Id.t * create_args) list option;

     

       84
       84
       +
         update : (Id.t * Jsont.json) list option;

     

       85
       85
       +
         destroy : Id.t list option;

     

       86
       86
       +
       }

     

       87
       87
       +
       

     

       88
       88
       +
       and create_args = {

     

       89
       89
       +
         device_client_id : string;

     

       90
       90
       +
         url : string;

     

       91
       91
       +
         keys : push_keys option;

     

       92
       92
       +
         verification_code : string option;

     

       93
       93
       +
         types : string list option;

     

       94
       94
       +
       }

     

       95
       95
       +
       

     

       96
       96
       +
       val set_args_jsont : set_args Jsont.t

+34

proto/request.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = {

     

       7
       7
       +
         using : string list;

     

       8
       8
       +
         method_calls : Invocation.t list;

     

       9
       9
       +
         created_ids : (Id.t * Id.t) list option;

     

       10
       10
       +
       }

     

       11
       11
       +
       

     

       12
       12
       +
       let create ~using ~method_calls ?created_ids () =

     

       13
       13
       +
         { using; method_calls; created_ids }

     

       14
       14
       +
       

     

       15
       15
       +
       let using t = t.using

     

       16
       16
       +
       let method_calls t = t.method_calls

     

       17
       17
       +
       let created_ids t = t.created_ids

     

       18
       18
       +
       

     

       19
       19
       +
       let make using method_calls created_ids =

     

       20
       20
       +
         { using; method_calls; created_ids }

     

       21
       21
       +
       

     

       22
       22
       +
       let jsont =

     

       23
       23
       +
         let kind = "Request" in

     

       24
       24
       +
         Jsont.Object.map ~kind make

     

       25
       25
       +
         |> Jsont.Object.mem "using" (Jsont.list Jsont.string) ~enc:using

     

       26
       26
       +
         |> Jsont.Object.mem "methodCalls" (Jsont.list Invocation.jsont) ~enc:method_calls

     

       27
       27
       +
         |> Jsont.Object.opt_mem "createdIds" (Json_map.of_id Id.jsont) ~enc:created_ids

     

       28
       28
       +
         |> Jsont.Object.finish

     

       29
       29
       +
       

     

       30
       30
       +
       let single ~using invocation =

     

       31
       31
       +
         { using; method_calls = [invocation]; created_ids = None }

     

       32
       32
       +
       

     

       33
       33
       +
       let batch ~using invocations =

     

       34
       34
       +
         { using; method_calls = invocations; created_ids = None }

+45

proto/request.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP request object as defined in RFC 8620 Section 3.3 *)

     

       7
       7
       +
       

     

       8
       8
       +
       type t = {

     

       9
       9
       +
         using : string list;

     

       10
       10
       +
         (** Capability URIs required for this request. *)

     

       11
       11
       +
         method_calls : Invocation.t list;

     

       12
       12
       +
         (** The method calls to execute. *)

     

       13
       13
       +
         created_ids : (Id.t * Id.t) list option;

     

       14
       14
       +
         (** Map of client-created temporary ids to server-assigned ids.

     

       15
       15
       +
             Used for result references in batch operations. *)

     

       16
       16
       +
       }

     

       17
       17
       +
       

     

       18
       18
       +
       val create :

     

       19
       19
       +
         using:string list ->

     

       20
       20
       +
         method_calls:Invocation.t list ->

     

       21
       21
       +
         ?created_ids:(Id.t * Id.t) list ->

     

       22
       22
       +
         unit ->

     

       23
       23
       +
         t

     

       24
       24
       +
       (** [create ~using ~method_calls ?created_ids ()] creates a JMAP request. *)

     

       25
       25
       +
       

     

       26
       26
       +
       val using : t -> string list

     

       27
       27
       +
       val method_calls : t -> Invocation.t list

     

       28
       28
       +
       val created_ids : t -> (Id.t * Id.t) list option

     

       29
       29
       +
       

     

       30
       30
       +
       val jsont : t Jsont.t

     

       31
       31
       +
       (** JSON codec for JMAP requests. *)

     

       32
       32
       +
       

     

       33
       33
       +
       (** {1 Request Builders} *)

     

       34
       34
       +
       

     

       35
       35
       +
       val single :

     

       36
       36
       +
         using:string list ->

     

       37
       37
       +
         Invocation.t ->

     

       38
       38
       +
         t

     

       39
       39
       +
       (** [single ~using invocation] creates a request with a single method call. *)

     

       40
       40
       +
       

     

       41
       41
       +
       val batch :

     

       42
       42
       +
         using:string list ->

     

       43
       43
       +
         Invocation.t list ->

     

       44
       44
       +
         t

     

       45
       45
       +
       (** [batch ~using invocations] creates a request with multiple method calls. *)

+46

proto/response.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = {

     

       7
       7
       +
         method_responses : Invocation.t list;

     

       8
       8
       +
         created_ids : (Id.t * Id.t) list option;

     

       9
       9
       +
         session_state : string;

     

       10
       10
       +
       }

     

       11
       11
       +
       

     

       12
       12
       +
       let method_responses t = t.method_responses

     

       13
       13
       +
       let created_ids t = t.created_ids

     

       14
       14
       +
       let session_state t = t.session_state

     

       15
       15
       +
       

     

       16
       16
       +
       let make method_responses created_ids session_state =

     

       17
       17
       +
         { method_responses; created_ids; session_state }

     

       18
       18
       +
       

     

       19
       19
       +
       let jsont =

     

       20
       20
       +
         let kind = "Response" in

     

       21
       21
       +
         Jsont.Object.map ~kind make

     

       22
       22
       +
         |> Jsont.Object.mem "methodResponses" (Jsont.list Invocation.jsont) ~enc:method_responses

     

       23
       23
       +
         |> Jsont.Object.opt_mem "createdIds" (Json_map.of_id Id.jsont) ~enc:created_ids

     

       24
       24
       +
         |> Jsont.Object.mem "sessionState" Jsont.string ~enc:session_state

     

       25
       25
       +
         |> Jsont.Object.finish

     

       26
       26
       +
       

     

       27
       27
       +
       let find_response method_call_id response =

     

       28
       28
       +
         List.find_opt

     

       29
       29
       +
           (fun inv -> Invocation.method_call_id inv = method_call_id)

     

       30
       30
       +
           response.method_responses

     

       31
       31
       +
       

     

       32
       32
       +
       let get_response method_call_id response =

     

       33
       33
       +
         match find_response method_call_id response with

     

       34
       34
       +
         | Some inv -> inv

     

       35
       35
       +
         | None -> raise Not_found

     

       36
       36
       +
       

     

       37
       37
       +
       let is_error invocation =

     

       38
       38
       +
         String.equal (Invocation.name invocation) "error"

     

       39
       39
       +
       

     

       40
       40
       +
       let get_error invocation =

     

       41
       41
       +
         if is_error invocation then

     

       42
       42
       +
           match Jsont.Json.decode' Error.method_error_jsont (Invocation.arguments invocation) with

     

       43
       43
       +
           | Ok v -> Some v

     

       44
       44
       +
           | Error _ -> None

     

       45
       45
       +
         else

     

       46
       46
       +
           None

+37

proto/response.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP response object as defined in RFC 8620 Section 3.4 *)

     

       7
       7
       +
       

     

       8
       8
       +
       type t = {

     

       9
       9
       +
         method_responses : Invocation.t list;

     

       10
       10
       +
         (** The method responses. Each is [methodName, responseArgs, methodCallId]. *)

     

       11
       11
       +
         created_ids : (Id.t * Id.t) list option;

     

       12
       12
       +
         (** Map of client-created temporary ids to server-assigned ids. *)

     

       13
       13
       +
         session_state : string;

     

       14
       14
       +
         (** Current session state. Changes indicate session data has changed. *)

     

       15
       15
       +
       }

     

       16
       16
       +
       

     

       17
       17
       +
       val method_responses : t -> Invocation.t list

     

       18
       18
       +
       val created_ids : t -> (Id.t * Id.t) list option

     

       19
       19
       +
       val session_state : t -> string

     

       20
       20
       +
       

     

       21
       21
       +
       val jsont : t Jsont.t

     

       22
       22
       +
       (** JSON codec for JMAP responses. *)

     

       23
       23
       +
       

     

       24
       24
       +
       (** {1 Response Inspection} *)

     

       25
       25
       +
       

     

       26
       26
       +
       val find_response : string -> t -> Invocation.t option

     

       27
       27
       +
       (** [find_response method_call_id response] finds the response for a method call. *)

     

       28
       28
       +
       

     

       29
       29
       +
       val get_response : string -> t -> Invocation.t

     

       30
       30
       +
       (** [get_response method_call_id response] gets the response for a method call.

     

       31
       31
       +
           @raise Not_found if not found. *)

     

       32
       32
       +
       

     

       33
       33
       +
       val is_error : Invocation.t -> bool

     

       34
       34
       +
       (** [is_error invocation] returns [true] if the invocation is an error response. *)

     

       35
       35
       +
       

     

       36
       36
       +
       val get_error : Invocation.t -> Error.method_error option

     

       37
       37
       +
       (** [get_error invocation] returns the error if this is an error response. *)

+96

proto/session.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       module Account = struct

     

       7
       7
       +
         type t = {

     

       8
       8
       +
           name : string;

     

       9
       9
       +
           is_personal : bool;

     

       10
       10
       +
           is_read_only : bool;

     

       11
       11
       +
           account_capabilities : (string * Jsont.json) list;

     

       12
       12
       +
         }

     

       13
       13
       +
       

     

       14
       14
       +
         let name t = t.name

     

       15
       15
       +
         let is_personal t = t.is_personal

     

       16
       16
       +
         let is_read_only t = t.is_read_only

     

       17
       17
       +
         let account_capabilities t = t.account_capabilities

     

       18
       18
       +
       

     

       19
       19
       +
         let make name is_personal is_read_only account_capabilities =

     

       20
       20
       +
           { name; is_personal; is_read_only; account_capabilities }

     

       21
       21
       +
       

     

       22
       22
       +
         let jsont =

     

       23
       23
       +
           let kind = "Account" in

     

       24
       24
       +
           Jsont.Object.map ~kind make

     

       25
       25
       +
           |> Jsont.Object.mem "name" Jsont.string ~enc:name

     

       26
       26
       +
           |> Jsont.Object.mem "isPersonal" Jsont.bool ~enc:is_personal

     

       27
       27
       +
           |> Jsont.Object.mem "isReadOnly" Jsont.bool ~enc:is_read_only

     

       28
       28
       +
           |> Jsont.Object.mem "accountCapabilities" (Json_map.of_string Jsont.json) ~enc:account_capabilities

     

       29
       29
       +
           |> Jsont.Object.finish

     

       30
       30
       +
       end

     

       31
       31
       +
       

     

       32
       32
       +
       type t = {

     

       33
       33
       +
         capabilities : (string * Jsont.json) list;

     

       34
       34
       +
         accounts : (Id.t * Account.t) list;

     

       35
       35
       +
         primary_accounts : (string * Id.t) list;

     

       36
       36
       +
         username : string;

     

       37
       37
       +
         api_url : string;

     

       38
       38
       +
         download_url : string;

     

       39
       39
       +
         upload_url : string;

     

       40
       40
       +
         event_source_url : string;

     

       41
       41
       +
         state : string;

     

       42
       42
       +
       }

     

       43
       43
       +
       

     

       44
       44
       +
       let capabilities t = t.capabilities

     

       45
       45
       +
       let accounts t = t.accounts

     

       46
       46
       +
       let primary_accounts t = t.primary_accounts

     

       47
       47
       +
       let username t = t.username

     

       48
       48
       +
       let api_url t = t.api_url

     

       49
       49
       +
       let download_url t = t.download_url

     

       50
       50
       +
       let upload_url t = t.upload_url

     

       51
       51
       +
       let event_source_url t = t.event_source_url

     

       52
       52
       +
       let state t = t.state

     

       53
       53
       +
       

     

       54
       54
       +
       let make capabilities accounts primary_accounts username api_url

     

       55
       55
       +
           download_url upload_url event_source_url state =

     

       56
       56
       +
         { capabilities; accounts; primary_accounts; username; api_url;

     

       57
       57
       +
           download_url; upload_url; event_source_url; state }

     

       58
       58
       +
       

     

       59
       59
       +
       let jsont =

     

       60
       60
       +
         let kind = "Session" in

     

       61
       61
       +
         Jsont.Object.map ~kind make

     

       62
       62
       +
         |> Jsont.Object.mem "capabilities" (Json_map.of_string Jsont.json) ~enc:capabilities

     

       63
       63
       +
         |> Jsont.Object.mem "accounts" (Json_map.of_id Account.jsont) ~enc:accounts

     

       64
       64
       +
         |> Jsont.Object.mem "primaryAccounts" (Json_map.of_string Id.jsont) ~enc:primary_accounts

     

       65
       65
       +
         |> Jsont.Object.mem "username" Jsont.string ~enc:username

     

       66
       66
       +
         |> Jsont.Object.mem "apiUrl" Jsont.string ~enc:api_url

     

       67
       67
       +
         |> Jsont.Object.mem "downloadUrl" Jsont.string ~enc:download_url

     

       68
       68
       +
         |> Jsont.Object.mem "uploadUrl" Jsont.string ~enc:upload_url

     

       69
       69
       +
         |> Jsont.Object.mem "eventSourceUrl" Jsont.string ~enc:event_source_url

     

       70
       70
       +
         |> Jsont.Object.mem "state" Jsont.string ~enc:state

     

       71
       71
       +
         |> Jsont.Object.finish

     

       72
       72
       +
       

     

       73
       73
       +
       let get_account id session =

     

       74
       74
       +
         List.assoc_opt id session.accounts

     

       75
       75
       +
       

     

       76
       76
       +
       let primary_account_for capability session =

     

       77
       77
       +
         List.assoc_opt capability session.primary_accounts

     

       78
       78
       +
       

     

       79
       79
       +
       let has_capability uri session =

     

       80
       80
       +
         List.exists (fun (k, _) -> k = uri) session.capabilities

     

       81
       81
       +
       

     

       82
       82
       +
       let get_core_capability session =

     

       83
       83
       +
         match List.assoc_opt Capability.core session.capabilities with

     

       84
       84
       +
         | None -> None

     

       85
       85
       +
         | Some json ->

     

       86
       86
       +
           (match Jsont.Json.decode' Capability.Core.jsont json with

     

       87
       87
       +
            | Ok v -> Some v

     

       88
       88
       +
            | Error _ -> None)

     

       89
       89
       +
       

     

       90
       90
       +
       let get_mail_capability session =

     

       91
       91
       +
         match List.assoc_opt Capability.mail session.capabilities with

     

       92
       92
       +
         | None -> None

     

       93
       93
       +
         | Some json ->

     

       94
       94
       +
           (match Jsont.Json.decode' Capability.Mail.jsont json with

     

       95
       95
       +
            | Ok v -> Some v

     

       96
       96
       +
            | Error _ -> None)

+84

proto/session.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP session object as defined in RFC 8620 Section 2 *)

     

       7
       7
       +
       

     

       8
       8
       +
       (** {1 Account} *)

     

       9
       9
       +
       

     

       10
       10
       +
       (** An account available to the user. *)

     

       11
       11
       +
       module Account : sig

     

       12
       12
       +
         type t = {

     

       13
       13
       +
           name : string;

     

       14
       14
       +
           (** Human-readable name for the account. *)

     

       15
       15
       +
           is_personal : bool;

     

       16
       16
       +
           (** Whether this is a personal account. *)

     

       17
       17
       +
           is_read_only : bool;

     

       18
       18
       +
           (** Whether the account is read-only. *)

     

       19
       19
       +
           account_capabilities : (string * Jsont.json) list;

     

       20
       20
       +
           (** Capabilities available for this account. *)

     

       21
       21
       +
         }

     

       22
       22
       +
       

     

       23
       23
       +
         val name : t -> string

     

       24
       24
       +
         val is_personal : t -> bool

     

       25
       25
       +
         val is_read_only : t -> bool

     

       26
       26
       +
         val account_capabilities : t -> (string * Jsont.json) list

     

       27
       27
       +
       

     

       28
       28
       +
         val jsont : t Jsont.t

     

       29
       29
       +
       end

     

       30
       30
       +
       

     

       31
       31
       +
       (** {1 Session} *)

     

       32
       32
       +
       

     

       33
       33
       +
       (** The JMAP session resource. *)

     

       34
       34
       +
       type t = {

     

       35
       35
       +
         capabilities : (string * Jsont.json) list;

     

       36
       36
       +
         (** Server capabilities. Keys are capability URIs. *)

     

       37
       37
       +
         accounts : (Id.t * Account.t) list;

     

       38
       38
       +
         (** Available accounts keyed by account id. *)

     

       39
       39
       +
         primary_accounts : (string * Id.t) list;

     

       40
       40
       +
         (** Map of capability URI to the primary account id for that capability. *)

     

       41
       41
       +
         username : string;

     

       42
       42
       +
         (** The username associated with the credentials. *)

     

       43
       43
       +
         api_url : string;

     

       44
       44
       +
         (** URL to POST JMAP requests to. *)

     

       45
       45
       +
         download_url : string;

     

       46
       46
       +
         (** URL template for downloading blobs. *)

     

       47
       47
       +
         upload_url : string;

     

       48
       48
       +
         (** URL template for uploading blobs. *)

     

       49
       49
       +
         event_source_url : string;

     

       50
       50
       +
         (** URL for push event source. *)

     

       51
       51
       +
         state : string;

     

       52
       52
       +
         (** Opaque session state string. *)

     

       53
       53
       +
       }

     

       54
       54
       +
       

     

       55
       55
       +
       val capabilities : t -> (string * Jsont.json) list

     

       56
       56
       +
       val accounts : t -> (Id.t * Account.t) list

     

       57
       57
       +
       val primary_accounts : t -> (string * Id.t) list

     

       58
       58
       +
       val username : t -> string

     

       59
       59
       +
       val api_url : t -> string

     

       60
       60
       +
       val download_url : t -> string

     

       61
       61
       +
       val upload_url : t -> string

     

       62
       62
       +
       val event_source_url : t -> string

     

       63
       63
       +
       val state : t -> string

     

       64
       64
       +
       

     

       65
       65
       +
       val jsont : t Jsont.t

     

       66
       66
       +
       (** JSON codec for session objects. *)

     

       67
       67
       +
       

     

       68
       68
       +
       (** {1 Session Helpers} *)

     

       69
       69
       +
       

     

       70
       70
       +
       val get_account : Id.t -> t -> Account.t option

     

       71
       71
       +
       (** [get_account id session] returns the account with the given id. *)

     

       72
       72
       +
       

     

       73
       73
       +
       val primary_account_for : string -> t -> Id.t option

     

       74
       74
       +
       (** [primary_account_for capability session] returns the primary account

     

       75
       75
       +
           for the given capability URI. *)

     

       76
       76
       +
       

     

       77
       77
       +
       val has_capability : string -> t -> bool

     

       78
       78
       +
       (** [has_capability uri session] returns [true] if the server supports the capability. *)

     

       79
       79
       +
       

     

       80
       80
       +
       val get_core_capability : t -> Capability.Core.t option

     

       81
       81
       +
       (** [get_core_capability session] returns the parsed core capability. *)

     

       82
       82
       +
       

     

       83
       83
       +
       val get_mail_capability : t -> Capability.Mail.t option

     

       84
       84
       +
       (** [get_mail_capability session] returns the parsed mail capability. *)

+14

proto/unknown.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       type t = Jsont.json

     

       7
       7
       +
       

     

       8
       8
       +
       let empty = Jsont.Object ([], Jsont.Meta.none)

     

       9
       9
       +
       

     

       10
       10
       +
       let is_empty = function

     

       11
       11
       +
         | Jsont.Object ([], _) -> true

     

       12
       12
       +
         | _ -> false

     

       13
       13
       +
       

     

       14
       14
       +
       let mems = Jsont.json_mems

+23

proto/unknown.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Unknown field preservation for forward compatibility.

     

       7
       7
       +
       

     

       8
       8
       +
           All JMAP objects preserve unknown fields to support future spec versions

     

       9
       9
       +
           and custom extensions. *)

     

       10
       10
       +
       

     

       11
       11
       +
       type t = Jsont.json

     

       12
       12
       +
       (** Unknown or unrecognized JSON object members as a generic JSON value.

     

       13
       13
       +
           This is always an object containing the unknown fields. *)

     

       14
       14
       +
       

     

       15
       15
       +
       val empty : t

     

       16
       16
       +
       (** [empty] is the empty set of unknown fields (an empty JSON object). *)

     

       17
       17
       +
       

     

       18
       18
       +
       val is_empty : t -> bool

     

       19
       19
       +
       (** [is_empty u] returns [true] if there are no unknown fields. *)

     

       20
       20
       +
       

     

       21
       21
       +
       val mems : (t, t, Jsont.mem list) Jsont.Object.Mems.map

     

       22
       22
       +
       (** [mems] is the jsont member map for preserving unknown fields.

     

       23
       23
       +
           Use with [Jsont.Object.keep_unknown]. *)

+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
       +

+10

test/proto/capability/valid/core.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "maxSizeUpload": 50000000,

     

       3
       3
       +
         "maxConcurrentUpload": 4,

     

       4
       4
       +
         "maxSizeRequest": 10000000,

     

       5
       5
       +
         "maxConcurrentRequests": 4,

     

       6
       6
       +
         "maxCallsInRequest": 16,

     

       7
       7
       +
         "maxObjectsInGet": 500,

     

       8
       8
       +
         "maxObjectsInSet": 500,

     

       9
       9
       +
         "collationAlgorithms": ["i;ascii-casemap", "i;octet"]

     

       10
       10
       +
       }

test/proto/capability/valid/mail.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "maxSizeMailboxName": 490,

     

       3
       3
       +
         "maxSizeAttachmentsPerEmail": 50000000,

     

       4
       4
       +
         "emailQuerySortOptions": ["receivedAt", "sentAt", "size", "from", "to", "subject"],

     

       5
       5
       +
         "mayCreateTopLevelMailbox": true

     

       6
       6
       +
       }

test/proto/capability/valid/submission.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "maxDelayedSend": 86400,

     

       3
       3
       +
         "submissionExtensions": {

     

       4
       4
       +
           "DELIVERBY": [],

     

       5
       5
       +
           "MT-PRIORITY": ["MIXER", "STANAG4406"]

     

       6
       6
       +
         }

     

       7
       7
       +
       }

test/proto/date/edge/microseconds.json

···

       1
       1
       +
       2024-01-15T10:30:00.123456Z

test/proto/date/edge/negative_offset.json

···

       1
       1
       +
       2024-01-15T10:30:00-08:00

test/proto/date/invalid/bad_format.json

···

       1
       1
       +
       January 15, 2024

test/proto/date/invalid/invalid_date.json

···

       1
       1
       +
       2024-02-30T10:30:00Z

test/proto/date/invalid/lowercase_t.json

···

       1
       1
       +
       2024-01-15t10:30:00Z

test/proto/date/invalid/lowercase_z.json

···

       1
       1
       +
       2024-01-15T10:30:00z

test/proto/date/invalid/missing_seconds.json

···

       1
       1
       +
       2024-01-15T10:30Z

test/proto/date/invalid/no_timezone.json

···

       1
       1
       +
       2024-01-15T10:30:00

test/proto/date/invalid/not_string.json

test/proto/date/valid/negative_offset.json

···

       1
       1
       +
       2024-01-15T10:30:00-08:00

test/proto/date/valid/utc_z.json

···

       1
       1
       +
       2024-01-15T10:30:00Z

test/proto/date/valid/with_milliseconds.json

···

       1
       1
       +
       2024-01-15T10:30:00.123Z

test/proto/date/valid/with_offset.json

···

       1
       1
       +
       2024-01-15T10:30:00+05:30

+17

test/proto/dune

···

       1
       1
       +
       (test

     

       2
       2
       +
        (name test_proto)

     

       3
       3
       +
        (package jmap)

     

       4
       4
       +
        (libraries jmap jmap.mail alcotest jsont.bytesrw)

     

       5
       5
       +
        (deps

     

       6
       6
       +
         (source_tree id)

     

       7
       7
       +
         (source_tree int53)

     

       8
       8
       +
         (source_tree date)

     

       9
       9
       +
         (source_tree session)

     

       10
       10
       +
         (source_tree request)

     

       11
       11
       +
         (source_tree response)

     

       12
       12
       +
         (source_tree invocation)

     

       13
       13
       +
         (source_tree capability)

     

       14
       14
       +
         (source_tree filter)

     

       15
       15
       +
         (source_tree method)

     

       16
       16
       +
         (source_tree error)

     

       17
       17
       +
         (source_tree mail)))

test/proto/error/valid/method_error.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "unknownMethod",

     

       3
       3
       +
         "description": "The method Foo/bar is not supported"

     

       4
       4
       +
       }

test/proto/error/valid/method_error_account_not_found.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "accountNotFound",

     

       3
       3
       +
         "description": "Account with id 'acc123' does not exist"

     

       4
       4
       +
       }

test/proto/error/valid/method_error_account_read_only.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "accountReadOnly",

     

       3
       3
       +
         "description": "This account does not allow modifications"

     

       4
       4
       +
       }

test/proto/error/valid/method_error_forbidden.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "forbidden",

     

       3
       3
       +
         "description": "Access to this method is not permitted"

     

       4
       4
       +
       }

test/proto/error/valid/method_error_invalid_arguments.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "invalidArguments",

     

       3
       3
       +
         "description": "Missing required argument: accountId"

     

       4
       4
       +
       }

test/proto/error/valid/method_error_server_fail.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "serverFail",

     

       3
       3
       +
         "description": "An unexpected error occurred on the server"

     

       4
       4
       +
       }

test/proto/error/valid/request_error.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "urn:ietf:params:jmap:error:notRequest",

     

       3
       3
       +
         "status": 400,

     

       4
       4
       +
         "detail": "Request body is not a valid JSON object"

     

       5
       5
       +
       }

test/proto/error/valid/request_error_limit.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "urn:ietf:params:jmap:error:limit",

     

       3
       3
       +
         "status": 400,

     

       4
       4
       +
         "limit": "maxCallsInRequest",

     

       5
       5
       +
         "detail": "Too many method calls in request"

     

       6
       6
       +
       }

test/proto/error/valid/request_error_not_json.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "urn:ietf:params:jmap:error:notJSON",

     

       3
       3
       +
         "status": 400,

     

       4
       4
       +
         "detail": "The request body is not valid JSON"

     

       5
       5
       +
       }

test/proto/error/valid/set_error.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "invalidProperties",

     

       3
       3
       +
         "description": "The property 'foo' is not valid",

     

       4
       4
       +
         "properties": ["foo", "bar"]

     

       5
       5
       +
       }

test/proto/error/valid/set_error_forbidden.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "forbidden",

     

       3
       3
       +
         "description": "You do not have permission to modify this object"

     

       4
       4
       +
       }

test/proto/error/valid/set_error_invalid_properties.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "invalidProperties",

     

       3
       3
       +
         "description": "Invalid property values",

     

       4
       4
       +
         "properties": ["name", "parentId"]

     

       5
       5
       +
       }

test/proto/error/valid/set_error_not_found.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "notFound",

     

       3
       3
       +
         "description": "Object with id 'abc123' not found"

     

       4
       4
       +
       }

test/proto/error/valid/set_error_over_quota.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "overQuota",

     

       3
       3
       +
         "description": "Account storage quota exceeded"

     

       4
       4
       +
       }

test/proto/error/valid/set_error_singleton.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "type": "singleton",

     

       3
       3
       +
         "description": "Only one VacationResponse object exists per account"

     

       4
       4
       +
       }

test/proto/filter/edge/empty_conditions.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "operator": "AND",

     

       3
       3
       +
         "conditions": []

     

       4
       4
       +
       }

test/proto/filter/valid/and_operator.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "operator": "AND",

     

       3
       3
       +
         "conditions": [

     

       4
       4
       +
           {"hasKeyword": "$seen"},

     

       5
       5
       +
           {"hasKeyword": "$flagged"}

     

       6
       6
       +
         ]

     

       7
       7
       +
       }

test/proto/filter/valid/comparator_descending.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "property": "receivedAt",

     

       3
       3
       +
         "isAscending": false

     

       4
       4
       +
       }

test/proto/filter/valid/comparator_minimal.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "property": "size"

     

       3
       3
       +
       }

test/proto/filter/valid/comparator_with_collation.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "property": "subject",

     

       3
       3
       +
         "isAscending": true,

     

       4
       4
       +
         "collation": "i;unicode-casemap"

     

       5
       5
       +
       }

+18

test/proto/filter/valid/deeply_nested.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "operator": "AND",

     

       3
       3
       +
         "conditions": [

     

       4
       4
       +
           {

     

       5
       5
       +
             "operator": "NOT",

     

       6
       6
       +
             "conditions": [

     

       7
       7
       +
               {

     

       8
       8
       +
                 "operator": "OR",

     

       9
       9
       +
                 "conditions": [

     

       10
       10
       +
                   {"hasKeyword": "$junk"},

     

       11
       11
       +
                   {"hasKeyword": "$spam"}

     

       12
       12
       +
                 ]

     

       13
       13
       +
               }

     

       14
       14
       +
             ]

     

       15
       15
       +
           },

     

       16
       16
       +
           {"inMailbox": "inbox"}

     

       17
       17
       +
         ]

     

       18
       18
       +
       }

+19

test/proto/filter/valid/nested.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "operator": "AND",

     

       3
       3
       +
         "conditions": [

     

       4
       4
       +
           {"inMailbox": "inbox"},

     

       5
       5
       +
           {

     

       6
       6
       +
             "operator": "OR",

     

       7
       7
       +
             "conditions": [

     

       8
       8
       +
               {"from": "boss@company.com"},

     

       9
       9
       +
               {"hasKeyword": "$important"}

     

       10
       10
       +
             ]

     

       11
       11
       +
           },

     

       12
       12
       +
           {

     

       13
       13
       +
             "operator": "NOT",

     

       14
       14
       +
             "conditions": [

     

       15
       15
       +
               {"hasKeyword": "$seen"}

     

       16
       16
       +
             ]

     

       17
       17
       +
           }

     

       18
       18
       +
         ]

     

       19
       19
       +
       }

+13

test/proto/filter/valid/nested_and_or.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "operator": "AND",

     

       3
       3
       +
         "conditions": [

     

       4
       4
       +
           {

     

       5
       5
       +
             "operator": "OR",

     

       6
       6
       +
             "conditions": [

     

       7
       7
       +
               {"inMailbox": "mb1"},

     

       8
       8
       +
               {"inMailbox": "mb2"}

     

       9
       9
       +
             ]

     

       10
       10
       +
           },

     

       11
       11
       +
           {"hasAttachment": true}

     

       12
       12
       +
         ]

     

       13
       13
       +
       }

test/proto/filter/valid/not_operator.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "operator": "NOT",

     

       3
       3
       +
         "conditions": [

     

       4
       4
       +
           {"hasKeyword": "$draft"}

     

       5
       5
       +
         ]

     

       6
       6
       +
       }

test/proto/filter/valid/or_operator.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "operator": "OR",

     

       3
       3
       +
         "conditions": [

     

       4
       4
       +
           {"from": "alice@example.com"},

     

       5
       5
       +
           {"from": "bob@example.com"}

     

       6
       6
       +
         ]

     

       7
       7
       +
       }

test/proto/filter/valid/simple_condition.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "inMailbox": "inbox123"

     

       3
       3
       +
       }

test/proto/id/edge/creation_ref.json

···

       1
       1
       +
       #newEmail1

test/proto/id/edge/digits_only.json

test/proto/id/edge/max_length_255.json

···

       1
       1
       +
       aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

test/proto/id/edge/nil_literal.json

test/proto/id/edge/over_max_length_256.json

···

       1
       1
       +
       aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

test/proto/id/edge/starts_with_dash.json

test/proto/id/edge/starts_with_digit.json

test/proto/id/invalid/empty.json

This is a binary file and will not be displayed.

test/proto/id/invalid/not_string.json

test/proto/id/invalid/null.json

test/proto/id/invalid/with_slash.json

···

       1
       1
       +
       abc/def

test/proto/id/invalid/with_space.json

···

       1
       1
       +
       hello world

test/proto/id/invalid/with_special.json

···

       1
       1
       +
       abc@def

test/proto/id/valid/alphanumeric.json

···

       1
       1
       +
       ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789

test/proto/id/valid/base64_like.json

···

       1
       1
       +
       dXNlcl8xMjM0NTY3ODkw

test/proto/id/valid/simple.json

test/proto/id/valid/single_char.json

test/proto/id/valid/uuid_style.json

···

       1
       1
       +
       550e8400-e29b-41d4-a716-446655440000

test/proto/id/valid/with_hyphen.json

···

       1
       1
       +
       msg-2024-01-15-abcdef

test/proto/id/valid/with_underscore.json

···

       1
       1
       +
       user_123_abc

test/proto/int53/edge/over_max_safe.json

···

       1
       1
       +
       9007199254740992

test/proto/int53/edge/under_min_safe.json

···

       1
       1
       +
       -9007199254740992

test/proto/int53/invalid/float.json

test/proto/int53/invalid/leading_zero.json

test/proto/int53/invalid/null.json

test/proto/int53/invalid/scientific.json

test/proto/int53/invalid/string.json

test/proto/int53/valid/max_safe.json

···

       1
       1
       +
       9007199254740991

test/proto/int53/valid/min_safe.json

···

       1
       1
       +
       -9007199254740991

test/proto/int53/valid/negative.json

test/proto/int53/valid/positive.json

test/proto/int53/valid/zero.json

test/proto/invocation/invalid/not_array.json

···

       1
       1
       +
       {"method": "Email/get", "args": {}, "callId": "c1"}

test/proto/invocation/invalid/wrong_length.json

···

       1
       1
       +
       ["Email/get", {"accountId": "acc1"}]

test/proto/invocation/valid/get.json

···

       1
       1
       +
       ["Email/get", {"accountId": "acc1", "ids": ["e1", "e2"]}, "call-001"]

test/proto/invocation/valid/query.json

···

       1
       1
       +
       ["Email/query", {"accountId": "acc1", "filter": {"inMailbox": "inbox"}, "sort": [{"property": "receivedAt", "isAscending": false}], "limit": 50}, "call-003"]

test/proto/invocation/valid/set.json

···

       1
       1
       +
       ["Mailbox/set", {"accountId": "acc1", "create": {"temp1": {"name": "Drafts"}}}, "call-002"]

+11

test/proto/mail/email/edge/empty_keywords.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e5",

     

       3
       3
       +
         "blobId": "blob5",

     

       4
       4
       +
         "threadId": "t5",

     

       5
       5
       +
         "size": 256,

     

       6
       6
       +
         "receivedAt": "2024-01-19T12:00:00Z",

     

       7
       7
       +
         "mailboxIds": {"mb1": true},

     

       8
       8
       +
         "keywords": {},

     

       9
       9
       +
         "hasAttachment": false,

     

       10
       10
       +
         "preview": "New unread email"

     

       11
       11
       +
       }

+14

test/proto/mail/email/valid/draft_email.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e3",

     

       3
       3
       +
         "blobId": "blob3",

     

       4
       4
       +
         "threadId": "t3",

     

       5
       5
       +
         "size": 512,

     

       6
       6
       +
         "receivedAt": "2024-01-17T14:00:00Z",

     

       7
       7
       +
         "mailboxIds": {"drafts": true},

     

       8
       8
       +
         "keywords": {"$draft": true},

     

       9
       9
       +
         "from": [{"name": "Me", "email": "me@example.com"}],

     

       10
       10
       +
         "to": [{"name": "You", "email": "you@example.com"}],

     

       11
       11
       +
         "subject": "Draft: Meeting notes",

     

       12
       12
       +
         "hasAttachment": false,

     

       13
       13
       +
         "preview": "This is a draft email"

     

       14
       14
       +
       }

+30

test/proto/mail/email/valid/full.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e2",

     

       3
       3
       +
         "blobId": "blob2",

     

       4
       4
       +
         "threadId": "t2",

     

       5
       5
       +
         "mailboxIds": {"inbox": true, "important": true},

     

       6
       6
       +
         "keywords": {"$seen": true, "$flagged": true, "$answered": true},

     

       7
       7
       +
         "size": 5000,

     

       8
       8
       +
         "receivedAt": "2024-01-15T14:30:00Z",

     

       9
       9
       +
         "messageId": ["msg123@example.com"],

     

       10
       10
       +
         "inReplyTo": ["msg100@example.com"],

     

       11
       11
       +
         "references": ["msg100@example.com", "msg99@example.com"],

     

       12
       12
       +
         "sender": [{"name": "Alice Smith", "email": "alice@example.com"}],

     

       13
       13
       +
         "from": [{"name": "Alice Smith", "email": "alice@example.com"}],

     

       14
       14
       +
         "to": [{"name": "Bob Jones", "email": "bob@example.com"}],

     

       15
       15
       +
         "cc": [{"name": "Carol White", "email": "carol@example.com"}],

     

       16
       16
       +
         "bcc": [],

     

       17
       17
       +
         "replyTo": [{"email": "alice-reply@example.com"}],

     

       18
       18
       +
         "subject": "Re: Important meeting",

     

       19
       19
       +
         "sentAt": "2024-01-15T14:29:00Z",

     

       20
       20
       +
         "hasAttachment": true,

     

       21
       21
       +
         "preview": "Thanks for the update. I'll review the documents and get back to you by...",

     

       22
       22
       +
         "bodyValues": {

     

       23
       23
       +
           "1": {"value": "Thanks for the update.\n\nI'll review the documents.", "isEncodingProblem": false, "isTruncated": false}

     

       24
       24
       +
         },

     

       25
       25
       +
         "textBody": [{"partId": "1", "type": "text/plain"}],

     

       26
       26
       +
         "htmlBody": [],

     

       27
       27
       +
         "attachments": [

     

       28
       28
       +
           {"partId": "2", "blobId": "attach1", "type": "application/pdf", "name": "document.pdf", "size": 12345}

     

       29
       29
       +
         ]

     

       30
       30
       +
       }

test/proto/mail/email/valid/minimal.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e1",

     

       3
       3
       +
         "blobId": "blob1",

     

       4
       4
       +
         "threadId": "t1",

     

       5
       5
       +
         "mailboxIds": {"inbox": true},

     

       6
       6
       +
         "keywords": {},

     

       7
       7
       +
         "size": 1024,

     

       8
       8
       +
         "receivedAt": "2024-01-15T10:30:00Z"

     

       9
       9
       +
       }

+15

test/proto/mail/email/valid/multiple_mailboxes.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e2",

     

       3
       3
       +
         "blobId": "blob2",

     

       4
       4
       +
         "threadId": "t2",

     

       5
       5
       +
         "size": 4096,

     

       6
       6
       +
         "receivedAt": "2024-01-16T08:00:00Z",

     

       7
       7
       +
         "mailboxIds": {

     

       8
       8
       +
           "inbox": true,

     

       9
       9
       +
           "important": true,

     

       10
       10
       +
           "work": true

     

       11
       11
       +
         },

     

       12
       12
       +
         "keywords": {"$seen": true},

     

       13
       13
       +
         "hasAttachment": false,

     

       14
       14
       +
         "preview": "Email in multiple mailboxes"

     

       15
       15
       +
       }

+18

test/proto/mail/email/valid/with_all_system_keywords.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e4",

     

       3
       3
       +
         "blobId": "blob4",

     

       4
       4
       +
         "threadId": "t4",

     

       5
       5
       +
         "size": 8192,

     

       6
       6
       +
         "receivedAt": "2024-01-18T09:00:00Z",

     

       7
       7
       +
         "mailboxIds": {"mb1": true},

     

       8
       8
       +
         "keywords": {

     

       9
       9
       +
           "$draft": true,

     

       10
       10
       +
           "$seen": true,

     

       11
       11
       +
           "$flagged": true,

     

       12
       12
       +
           "$answered": true,

     

       13
       13
       +
           "$forwarded": true,

     

       14
       14
       +
           "custom-keyword": true

     

       15
       15
       +
         },

     

       16
       16
       +
         "hasAttachment": false,

     

       17
       17
       +
         "preview": "Email with all system keywords"

     

       18
       18
       +
       }

+16

test/proto/mail/email/valid/with_headers.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e3",

     

       3
       3
       +
         "blobId": "blob3",

     

       4
       4
       +
         "threadId": "t3",

     

       5
       5
       +
         "mailboxIds": {"inbox": true},

     

       6
       6
       +
         "keywords": {},

     

       7
       7
       +
         "size": 2048,

     

       8
       8
       +
         "receivedAt": "2024-01-16T09:00:00Z",

     

       9
       9
       +
         "headers": [

     

       10
       10
       +
           {"name": "X-Priority", "value": "1"},

     

       11
       11
       +
           {"name": "X-Mailer", "value": "Test Client 1.0"},

     

       12
       12
       +
           {"name": "List-Unsubscribe", "value": "<mailto:unsubscribe@example.com>"}

     

       13
       13
       +
         ],

     

       14
       14
       +
         "header:X-Priority:asText": "1",

     

       15
       15
       +
         "header:X-Mailer:asText": "Test Client 1.0"

     

       16
       16
       +
       }

+15

test/proto/mail/email/valid/with_keywords.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e1",

     

       3
       3
       +
         "blobId": "blob1",

     

       4
       4
       +
         "threadId": "t1",

     

       5
       5
       +
         "size": 2048,

     

       6
       6
       +
         "receivedAt": "2024-01-15T10:30:00Z",

     

       7
       7
       +
         "mailboxIds": {"mb1": true},

     

       8
       8
       +
         "keywords": {

     

       9
       9
       +
           "$seen": true,

     

       10
       10
       +
           "$flagged": true,

     

       11
       11
       +
           "$answered": true

     

       12
       12
       +
         },

     

       13
       13
       +
         "hasAttachment": false,

     

       14
       14
       +
         "preview": "This is a flagged and answered email"

     

       15
       15
       +
       }

+15

test/proto/mail/email/valid/with_message_ids.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "e6",

     

       3
       3
       +
         "blobId": "blob6",

     

       4
       4
       +
         "threadId": "t6",

     

       5
       5
       +
         "size": 4096,

     

       6
       6
       +
         "receivedAt": "2024-01-20T16:00:00Z",

     

       7
       7
       +
         "mailboxIds": {"inbox": true},

     

       8
       8
       +
         "keywords": {"$seen": true},

     

       9
       9
       +
         "messageId": ["unique-123@example.com"],

     

       10
       10
       +
         "inReplyTo": ["parent-456@example.com"],

     

       11
       11
       +
         "references": ["root-001@example.com", "parent-456@example.com"],

     

       12
       12
       +
         "subject": "Re: Original thread",

     

       13
       13
       +
         "hasAttachment": false,

     

       14
       14
       +
         "preview": "Reply in thread"

     

       15
       15
       +
       }

test/proto/mail/email_address/valid/email_only.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "email": "anonymous@example.com"

     

       3
       3
       +
       }

test/proto/mail/email_address/valid/full.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "name": "John Doe",

     

       3
       3
       +
         "email": "john.doe@example.com"

     

       4
       4
       +
       }

+28

test/proto/mail/email_body/edge/deep_nesting.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "partId": "0",

     

       3
       3
       +
         "size": 20000,

     

       4
       4
       +
         "type": "multipart/mixed",

     

       5
       5
       +
         "subParts": [

     

       6
       6
       +
           {

     

       7
       7
       +
             "partId": "1",

     

       8
       8
       +
             "size": 15000,

     

       9
       9
       +
             "type": "multipart/mixed",

     

       10
       10
       +
             "subParts": [

     

       11
       11
       +
               {

     

       12
       12
       +
                 "partId": "1.1",

     

       13
       13
       +
                 "size": 10000,

     

       14
       14
       +
                 "type": "multipart/alternative",

     

       15
       15
       +
                 "subParts": [

     

       16
       16
       +
                   {

     

       17
       17
       +
                     "partId": "1.1.1",

     

       18
       18
       +
                     "blobId": "b1",

     

       19
       19
       +
                     "size": 500,

     

       20
       20
       +
                     "type": "text/plain",

     

       21
       21
       +
                     "charset": "utf-8"

     

       22
       22
       +
                   }

     

       23
       23
       +
                 ]

     

       24
       24
       +
               }

     

       25
       25
       +
             ]

     

       26
       26
       +
           }

     

       27
       27
       +
         ]

     

       28
       28
       +
       }

+21

test/proto/mail/email_body/valid/multipart.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "partId": "0",

     

       3
       3
       +
         "size": 5000,

     

       4
       4
       +
         "type": "multipart/alternative",

     

       5
       5
       +
         "subParts": [

     

       6
       6
       +
           {

     

       7
       7
       +
             "partId": "1",

     

       8
       8
       +
             "blobId": "b1",

     

       9
       9
       +
             "size": 200,

     

       10
       10
       +
             "type": "text/plain",

     

       11
       11
       +
             "charset": "utf-8"

     

       12
       12
       +
           },

     

       13
       13
       +
           {

     

       14
       14
       +
             "partId": "2",

     

       15
       15
       +
             "blobId": "b2",

     

       16
       16
       +
             "size": 4800,

     

       17
       17
       +
             "type": "text/html",

     

       18
       18
       +
             "charset": "utf-8"

     

       19
       19
       +
           }

     

       20
       20
       +
         ]

     

       21
       21
       +
       }

+36

test/proto/mail/email_body/valid/multipart_mixed.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "partId": "0",

     

       3
       3
       +
         "size": 10000,

     

       4
       4
       +
         "type": "multipart/mixed",

     

       5
       5
       +
         "subParts": [

     

       6
       6
       +
           {

     

       7
       7
       +
             "partId": "1",

     

       8
       8
       +
             "size": 5000,

     

       9
       9
       +
             "type": "multipart/alternative",

     

       10
       10
       +
             "subParts": [

     

       11
       11
       +
               {

     

       12
       12
       +
                 "partId": "1.1",

     

       13
       13
       +
                 "blobId": "b1",

     

       14
       14
       +
                 "size": 500,

     

       15
       15
       +
                 "type": "text/plain",

     

       16
       16
       +
                 "charset": "utf-8"

     

       17
       17
       +
               },

     

       18
       18
       +
               {

     

       19
       19
       +
                 "partId": "1.2",

     

       20
       20
       +
                 "blobId": "b2",

     

       21
       21
       +
                 "size": 4500,

     

       22
       22
       +
                 "type": "text/html",

     

       23
       23
       +
                 "charset": "utf-8"

     

       24
       24
       +
               }

     

       25
       25
       +
             ]

     

       26
       26
       +
           },

     

       27
       27
       +
           {

     

       28
       28
       +
             "partId": "2",

     

       29
       29
       +
             "blobId": "b3",

     

       30
       30
       +
             "size": 5000,

     

       31
       31
       +
             "type": "application/pdf",

     

       32
       32
       +
             "name": "document.pdf",

     

       33
       33
       +
             "disposition": "attachment"

     

       34
       34
       +
           }

     

       35
       35
       +
         ]

     

       36
       36
       +
       }

test/proto/mail/email_body/valid/text_part.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "partId": "1",

     

       3
       3
       +
         "blobId": "blobpart1",

     

       4
       4
       +
         "size": 500,

     

       5
       5
       +
         "headers": [{"name": "Content-Type", "value": "text/plain; charset=utf-8"}],

     

       6
       6
       +
         "type": "text/plain",

     

       7
       7
       +
         "charset": "utf-8",

     

       8
       8
       +
         "language": ["en"]

     

       9
       9
       +
       }

+23

test/proto/mail/email_body/valid/with_inline_image.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "partId": "0",

     

       3
       3
       +
         "size": 50000,

     

       4
       4
       +
         "type": "multipart/related",

     

       5
       5
       +
         "subParts": [

     

       6
       6
       +
           {

     

       7
       7
       +
             "partId": "1",

     

       8
       8
       +
             "blobId": "b1",

     

       9
       9
       +
             "size": 2000,

     

       10
       10
       +
             "type": "text/html",

     

       11
       11
       +
             "charset": "utf-8"

     

       12
       12
       +
           },

     

       13
       13
       +
           {

     

       14
       14
       +
             "partId": "2",

     

       15
       15
       +
             "blobId": "b2",

     

       16
       16
       +
             "size": 48000,

     

       17
       17
       +
             "type": "image/png",

     

       18
       18
       +
             "name": "logo.png",

     

       19
       19
       +
             "disposition": "inline",

     

       20
       20
       +
             "cid": "logo@example.com"

     

       21
       21
       +
           }

     

       22
       22
       +
         ]

     

       23
       23
       +
       }

test/proto/mail/email_body/valid/with_language.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "partId": "1",

     

       3
       3
       +
         "blobId": "b1",

     

       4
       4
       +
         "size": 1000,

     

       5
       5
       +
         "type": "text/plain",

     

       6
       6
       +
         "charset": "utf-8",

     

       7
       7
       +
         "language": ["en", "de"],

     

       8
       8
       +
         "location": "https://example.com/message.txt"

     

       9
       9
       +
       }

test/proto/mail/identity/valid/simple.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "ident1",

     

       3
       3
       +
         "name": "Work Identity",

     

       4
       4
       +
         "email": "john.doe@company.com",

     

       5
       5
       +
         "replyTo": [{"email": "john.doe@company.com"}],

     

       6
       6
       +
         "textSignature": "-- \nJohn Doe\nSenior Engineer",

     

       7
       7
       +
         "htmlSignature": "<p>-- </p><p><b>John Doe</b><br/>Senior Engineer</p>",

     

       8
       8
       +
         "mayDelete": true

     

       9
       9
       +
       }

+21

test/proto/mail/mailbox/edge/all_rights_false.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "mbReadOnly",

     

       3
       3
       +
         "name": "Read Only Folder",

     

       4
       4
       +
         "sortOrder": 99,

     

       5
       5
       +
         "totalEmails": 50,

     

       6
       6
       +
         "unreadEmails": 10,

     

       7
       7
       +
         "totalThreads": 40,

     

       8
       8
       +
         "unreadThreads": 8,

     

       9
       9
       +
         "myRights": {

     

       10
       10
       +
           "mayReadItems": true,

     

       11
       11
       +
           "mayAddItems": false,

     

       12
       12
       +
           "mayRemoveItems": false,

     

       13
       13
       +
           "maySetSeen": false,

     

       14
       14
       +
           "maySetKeywords": false,

     

       15
       15
       +
           "mayCreateChild": false,

     

       16
       16
       +
           "mayRename": false,

     

       17
       17
       +
           "mayDelete": false,

     

       18
       18
       +
           "maySubmit": false

     

       19
       19
       +
         },

     

       20
       20
       +
         "isSubscribed": false

     

       21
       21
       +
       }

+12

test/proto/mail/mailbox/valid/all_roles.json

···

       1
       1
       +
       [

     

       2
       2
       +
         {"id": "r1", "name": "Inbox", "role": "inbox", "sortOrder": 1},

     

       3
       3
       +
         {"id": "r2", "name": "Drafts", "role": "drafts", "sortOrder": 2},

     

       4
       4
       +
         {"id": "r3", "name": "Sent", "role": "sent", "sortOrder": 3},

     

       5
       5
       +
         {"id": "r4", "name": "Junk", "role": "junk", "sortOrder": 4},

     

       6
       6
       +
         {"id": "r5", "name": "Trash", "role": "trash", "sortOrder": 5},

     

       7
       7
       +
         {"id": "r6", "name": "Archive", "role": "archive", "sortOrder": 6},

     

       8
       8
       +
         {"id": "r7", "name": "All", "role": "all", "sortOrder": 7},

     

       9
       9
       +
         {"id": "r8", "name": "Important", "role": "important", "sortOrder": 8},

     

       10
       10
       +
         {"id": "r9", "name": "Scheduled", "role": "scheduled", "sortOrder": 9},

     

       11
       11
       +
         {"id": "r10", "name": "Subscribed", "role": "subscribed", "sortOrder": 10}

     

       12
       12
       +
       ]

+22

test/proto/mail/mailbox/valid/nested.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "mb2",

     

       3
       3
       +
         "name": "Work",

     

       4
       4
       +
         "parentId": "mb1",

     

       5
       5
       +
         "sortOrder": 10,

     

       6
       6
       +
         "totalEmails": 0,

     

       7
       7
       +
         "unreadEmails": 0,

     

       8
       8
       +
         "totalThreads": 0,

     

       9
       9
       +
         "unreadThreads": 0,

     

       10
       10
       +
         "myRights": {

     

       11
       11
       +
           "mayReadItems": true,

     

       12
       12
       +
           "mayAddItems": true,

     

       13
       13
       +
           "mayRemoveItems": true,

     

       14
       14
       +
           "maySetSeen": true,

     

       15
       15
       +
           "maySetKeywords": true,

     

       16
       16
       +
           "mayCreateChild": true,

     

       17
       17
       +
           "mayRename": true,

     

       18
       18
       +
           "mayDelete": true,

     

       19
       19
       +
           "maySubmit": false

     

       20
       20
       +
         },

     

       21
       21
       +
         "isSubscribed": false

     

       22
       22
       +
       }

+22

test/proto/mail/mailbox/valid/simple.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "mb1",

     

       3
       3
       +
         "name": "Inbox",

     

       4
       4
       +
         "role": "inbox",

     

       5
       5
       +
         "sortOrder": 1,

     

       6
       6
       +
         "totalEmails": 150,

     

       7
       7
       +
         "unreadEmails": 5,

     

       8
       8
       +
         "totalThreads": 100,

     

       9
       9
       +
         "unreadThreads": 3,

     

       10
       10
       +
         "myRights": {

     

       11
       11
       +
           "mayReadItems": true,

     

       12
       12
       +
           "mayAddItems": true,

     

       13
       13
       +
           "mayRemoveItems": true,

     

       14
       14
       +
           "maySetSeen": true,

     

       15
       15
       +
           "maySetKeywords": true,

     

       16
       16
       +
           "mayCreateChild": true,

     

       17
       17
       +
           "mayRename": false,

     

       18
       18
       +
           "mayDelete": false,

     

       19
       19
       +
           "maySubmit": true

     

       20
       20
       +
         },

     

       21
       21
       +
         "isSubscribed": true

     

       22
       22
       +
       }

+22

test/proto/mail/mailbox/valid/with_all_roles.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "mbArchive",

     

       3
       3
       +
         "name": "Archive",

     

       4
       4
       +
         "role": "archive",

     

       5
       5
       +
         "sortOrder": 5,

     

       6
       6
       +
         "totalEmails": 1000,

     

       7
       7
       +
         "unreadEmails": 0,

     

       8
       8
       +
         "totalThreads": 800,

     

       9
       9
       +
         "unreadThreads": 0,

     

       10
       10
       +
         "myRights": {

     

       11
       11
       +
           "mayReadItems": true,

     

       12
       12
       +
           "mayAddItems": true,

     

       13
       13
       +
           "mayRemoveItems": true,

     

       14
       14
       +
           "maySetSeen": true,

     

       15
       15
       +
           "maySetKeywords": true,

     

       16
       16
       +
           "mayCreateChild": true,

     

       17
       17
       +
           "mayRename": true,

     

       18
       18
       +
           "mayDelete": true,

     

       19
       19
       +
           "maySubmit": false

     

       20
       20
       +
         },

     

       21
       21
       +
         "isSubscribed": true

     

       22
       22
       +
       }

+21

test/proto/mail/submission/valid/final_status.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "sub3",

     

       3
       3
       +
         "identityId": "ident1",

     

       4
       4
       +
         "emailId": "e2",

     

       5
       5
       +
         "threadId": "t2",

     

       6
       6
       +
         "envelope": {

     

       7
       7
       +
           "mailFrom": {"email": "sender@example.com"},

     

       8
       8
       +
           "rcptTo": [{"email": "recipient@example.com"}]

     

       9
       9
       +
         },

     

       10
       10
       +
         "sendAt": "2024-01-15T12:00:00Z",

     

       11
       11
       +
         "undoStatus": "final",

     

       12
       12
       +
         "deliveryStatus": {

     

       13
       13
       +
           "recipient@example.com": {

     

       14
       14
       +
             "smtpReply": "250 2.0.0 OK",

     

       15
       15
       +
             "delivered": "yes",

     

       16
       16
       +
             "displayed": "unknown"

     

       17
       17
       +
           }

     

       18
       18
       +
         },

     

       19
       19
       +
         "dsnBlobIds": [],

     

       20
       20
       +
         "mdnBlobIds": []

     

       21
       21
       +
       }

+14

test/proto/mail/submission/valid/simple.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "sub1",

     

       3
       3
       +
         "identityId": "ident1",

     

       4
       4
       +
         "emailId": "e1",

     

       5
       5
       +
         "threadId": "t1",

     

       6
       6
       +
         "envelope": {

     

       7
       7
       +
           "mailFrom": {"email": "sender@example.com"},

     

       8
       8
       +
           "rcptTo": [{"email": "recipient@example.com"}]

     

       9
       9
       +
         },

     

       10
       10
       +
         "sendAt": "2024-01-15T15:00:00Z",

     

       11
       11
       +
         "undoStatus": "pending",

     

       12
       12
       +
         "dsnBlobIds": [],

     

       13
       13
       +
         "mdnBlobIds": []

     

       14
       14
       +
       }

+20

test/proto/mail/submission/valid/with_envelope.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "sub2",

     

       3
       3
       +
         "identityId": "ident1",

     

       4
       4
       +
         "emailId": "e1",

     

       5
       5
       +
         "threadId": "t1",

     

       6
       6
       +
         "envelope": {

     

       7
       7
       +
           "mailFrom": {

     

       8
       8
       +
             "email": "sender@example.com",

     

       9
       9
       +
             "parameters": {"SIZE": "1024", "BODY": "8BITMIME"}

     

       10
       10
       +
           },

     

       11
       11
       +
           "rcptTo": [

     

       12
       12
       +
             {"email": "recipient1@example.com"},

     

       13
       13
       +
             {"email": "recipient2@example.com", "parameters": {"NOTIFY": "SUCCESS,FAILURE"}}

     

       14
       14
       +
           ]

     

       15
       15
       +
         },

     

       16
       16
       +
         "sendAt": "2024-01-15T15:00:00Z",

     

       17
       17
       +
         "undoStatus": "pending",

     

       18
       18
       +
         "dsnBlobIds": [],

     

       19
       19
       +
         "mdnBlobIds": []

     

       20
       20
       +
       }

test/proto/mail/thread/valid/conversation.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "t2",

     

       3
       3
       +
         "emailIds": ["e10", "e11", "e12", "e13", "e14"]

     

       4
       4
       +
       }

test/proto/mail/thread/valid/simple.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "t1",

     

       3
       3
       +
         "emailIds": ["e1"]

     

       4
       4
       +
       }

test/proto/mail/vacation/valid/disabled.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "singleton",

     

       3
       3
       +
         "isEnabled": false

     

       4
       4
       +
       }

test/proto/mail/vacation/valid/enabled.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "singleton",

     

       3
       3
       +
         "isEnabled": true,

     

       4
       4
       +
         "fromDate": "2024-01-20T00:00:00Z",

     

       5
       5
       +
         "toDate": "2024-01-27T23:59:59Z",

     

       6
       6
       +
         "subject": "Out of Office",

     

       7
       7
       +
         "textBody": "I am currently out of the office and will return on January 27th.",

     

       8
       8
       +
         "htmlBody": "<p>I am currently out of the office and will return on January 27th.</p>"

     

       9
       9
       +
       }

test/proto/method/valid/changes_response.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accountId": "acc1",

     

       3
       3
       +
         "oldState": "old123",

     

       4
       4
       +
         "newState": "new456",

     

       5
       5
       +
         "hasMoreChanges": false,

     

       6
       6
       +
         "created": ["id1", "id2"],

     

       7
       7
       +
         "updated": ["id3"],

     

       8
       8
       +
         "destroyed": ["id4", "id5"]

     

       9
       9
       +
       }

test/proto/method/valid/get_args.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accountId": "acc1",

     

       3
       3
       +
         "ids": ["id1", "id2", "id3"],

     

       4
       4
       +
         "properties": ["id", "name", "role"]

     

       5
       5
       +
       }

test/proto/method/valid/get_args_minimal.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accountId": "acc1"

     

       3
       3
       +
       }

+16

test/proto/method/valid/query_args.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accountId": "acc1",

     

       3
       3
       +
         "filter": {

     

       4
       4
       +
           "operator": "AND",

     

       5
       5
       +
           "conditions": [

     

       6
       6
       +
             {"inMailbox": "inbox"},

     

       7
       7
       +
             {"hasKeyword": "$seen"}

     

       8
       8
       +
           ]

     

       9
       9
       +
         },

     

       10
       10
       +
         "sort": [

     

       11
       11
       +
           {"property": "receivedAt", "isAscending": false}

     

       12
       12
       +
         ],

     

       13
       13
       +
         "position": 0,

     

       14
       14
       +
         "limit": 100,

     

       15
       15
       +
         "calculateTotal": true

     

       16
       16
       +
       }

test/proto/method/valid/query_response.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accountId": "acc1",

     

       3
       3
       +
         "queryState": "qs1",

     

       4
       4
       +
         "canCalculateChanges": true,

     

       5
       5
       +
         "position": 0,

     

       6
       6
       +
         "ids": ["e1", "e2", "e3", "e4", "e5"],

     

       7
       7
       +
         "total": 250

     

       8
       8
       +
       }

+12

test/proto/method/valid/set_args.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accountId": "acc1",

     

       3
       3
       +
         "ifInState": "state123",

     

       4
       4
       +
         "create": {

     

       5
       5
       +
           "new1": {"name": "Folder 1"},

     

       6
       6
       +
           "new2": {"name": "Folder 2"}

     

       7
       7
       +
         },

     

       8
       8
       +
         "update": {

     

       9
       9
       +
           "existing1": {"name": "Renamed Folder"}

     

       10
       10
       +
         },

     

       11
       11
       +
         "destroy": ["old1", "old2"]

     

       12
       12
       +
       }

+16

test/proto/method/valid/set_response.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accountId": "acc1",

     

       3
       3
       +
         "oldState": "state123",

     

       4
       4
       +
         "newState": "state456",

     

       5
       5
       +
         "created": {

     

       6
       6
       +
           "new1": {"id": "mb123", "name": "Folder 1"},

     

       7
       7
       +
           "new2": {"id": "mb456", "name": "Folder 2"}

     

       8
       8
       +
         },

     

       9
       9
       +
         "updated": {

     

       10
       10
       +
           "existing1": null

     

       11
       11
       +
         },

     

       12
       12
       +
         "destroyed": ["old1", "old2"],

     

       13
       13
       +
         "notCreated": {},

     

       14
       14
       +
         "notUpdated": {},

     

       15
       15
       +
         "notDestroyed": {}

     

       16
       16
       +
       }

+19

test/proto/method/valid/set_response_with_errors.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accountId": "acc1",

     

       3
       3
       +
         "oldState": "state123",

     

       4
       4
       +
         "newState": "state124",

     

       5
       5
       +
         "created": {

     

       6
       6
       +
           "new1": {"id": "mb789", "name": "Success Folder"}

     

       7
       7
       +
         },

     

       8
       8
       +
         "updated": {},

     

       9
       9
       +
         "destroyed": [],

     

       10
       10
       +
         "notCreated": {

     

       11
       11
       +
           "new2": {"type": "invalidProperties", "properties": ["name"]}

     

       12
       12
       +
         },

     

       13
       13
       +
         "notUpdated": {

     

       14
       14
       +
           "existing1": {"type": "notFound"}

     

       15
       15
       +
         },

     

       16
       16
       +
         "notDestroyed": {

     

       17
       17
       +
           "old1": {"type": "forbidden", "description": "Cannot delete inbox"}

     

       18
       18
       +
         }

     

       19
       19
       +
       }

test/proto/request/invalid/missing_using.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "methodCalls": [

     

       3
       3
       +
           ["Mailbox/get", {"accountId": "acc1"}, "c1"]

     

       4
       4
       +
         ]

     

       5
       5
       +
       }

test/proto/request/invalid/not_object.json

···

       1
       1
       +
       ["urn:ietf:params:jmap:core"]

test/proto/request/valid/empty_methods.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "using": ["urn:ietf:params:jmap:core"],

     

       3
       3
       +
         "methodCalls": []

     

       4
       4
       +
       }

test/proto/request/valid/multiple_methods.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],

     

       3
       3
       +
         "methodCalls": [

     

       4
       4
       +
           ["Mailbox/get", {"accountId": "acc1"}, "c1"],

     

       5
       5
       +
           ["Email/query", {"accountId": "acc1", "filter": {"inMailbox": "inbox1"}}, "c2"],

     

       6
       6
       +
           ["Email/get", {"accountId": "acc1", "#ids": {"resultOf": "c2", "name": "Email/query", "path": "/ids"}}, "c3"]

     

       7
       7
       +
         ]

     

       8
       8
       +
       }

test/proto/request/valid/single_method.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],

     

       3
       3
       +
         "methodCalls": [

     

       4
       4
       +
           ["Mailbox/get", {"accountId": "acc1"}, "c1"]

     

       5
       5
       +
         ]

     

       6
       6
       +
       }

test/proto/request/valid/with_created_ids.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],

     

       3
       3
       +
         "methodCalls": [

     

       4
       4
       +
           ["Mailbox/set", {"accountId": "acc1", "create": {"temp1": {"name": "New Folder", "parentId": null}}}, "c1"]

     

       5
       5
       +
         ],

     

       6
       6
       +
         "createdIds": {

     

       7
       7
       +
           "temp1": "server-assigned-id-1"

     

       8
       8
       +
         }

     

       9
       9
       +
       }

+20

test/proto/request/valid/with_creation_refs.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],

     

       3
       3
       +
         "methodCalls": [

     

       4
       4
       +
           ["Mailbox/set", {

     

       5
       5
       +
             "accountId": "acc1",

     

       6
       6
       +
             "create": {

     

       7
       7
       +
               "newBox": {"name": "New Folder", "parentId": null}

     

       8
       8
       +
             }

     

       9
       9
       +
           }, "c1"],

     

       10
       10
       +
           ["Email/set", {

     

       11
       11
       +
             "accountId": "acc1",

     

       12
       12
       +
             "create": {

     

       13
       13
       +
               "draft1": {

     

       14
       14
       +
                 "mailboxIds": {"#newBox": true},

     

       15
       15
       +
                 "subject": "Draft in new folder"

     

       16
       16
       +
               }

     

       17
       17
       +
             }

     

       18
       18
       +
           }, "c2"]

     

       19
       19
       +
         ]

     

       20
       20
       +
       }

test/proto/request/valid/with_result_reference.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],

     

       3
       3
       +
         "methodCalls": [

     

       4
       4
       +
           ["Mailbox/query", {"accountId": "acc1", "filter": {"role": "inbox"}}, "0"],

     

       5
       5
       +
           ["Mailbox/get", {"accountId": "acc1", "#ids": {"resultOf": "0", "name": "Mailbox/query", "path": "/ids"}}, "1"]

     

       6
       6
       +
         ]

     

       7
       7
       +
       }

test/proto/response/invalid/missing_session_state.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "methodResponses": [

     

       3
       3
       +
           ["Mailbox/get", {"accountId": "acc1", "state": "state1", "list": [], "notFound": []}, "c1"]

     

       4
       4
       +
         ]

     

       5
       5
       +
       }

test/proto/response/valid/multiple_responses.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "methodResponses": [

     

       3
       3
       +
           ["Email/query", {"accountId": "acc1", "queryState": "q1", "canCalculateChanges": true, "position": 0, "ids": ["e1", "e2", "e3"], "total": 100}, "c1"],

     

       4
       4
       +
           ["Email/get", {"accountId": "acc1", "state": "s1", "list": [{"id": "e1", "blobId": "b1", "threadId": "t1", "mailboxIds": {"inbox": true}, "keywords": {"$seen": true}, "size": 1234, "receivedAt": "2024-01-15T10:30:00Z"}], "notFound": []}, "c2"]

     

       5
       5
       +
         ],

     

       6
       6
       +
         "sessionState": "sessionABC"

     

       7
       7
       +
       }

test/proto/response/valid/success.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "methodResponses": [

     

       3
       3
       +
           ["Mailbox/get", {"accountId": "acc1", "state": "state1", "list": [], "notFound": []}, "c1"]

     

       4
       4
       +
         ],

     

       5
       5
       +
         "sessionState": "session123"

     

       6
       6
       +
       }

test/proto/response/valid/with_created_ids.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "methodResponses": [

     

       3
       3
       +
           ["Mailbox/set", {"accountId": "acc1", "oldState": "state1", "newState": "state2", "created": {"temp1": {"id": "real1"}}}, "c1"]

     

       4
       4
       +
         ],

     

       5
       5
       +
         "createdIds": {

     

       6
       6
       +
           "temp1": "real1"

     

       7
       7
       +
         },

     

       8
       8
       +
         "sessionState": "session456"

     

       9
       9
       +
       }

test/proto/response/valid/with_error.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "methodResponses": [

     

       3
       3
       +
           ["error", {"type": "unknownMethod"}, "c1"]

     

       4
       4
       +
         ],

     

       5
       5
       +
         "sessionState": "session789"

     

       6
       6
       +
       }

+22

test/proto/session/edge/empty_accounts.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "capabilities": {

     

       3
       3
       +
           "urn:ietf:params:jmap:core": {

     

       4
       4
       +
             "maxSizeUpload": 50000000,

     

       5
       5
       +
             "maxConcurrentUpload": 4,

     

       6
       6
       +
             "maxSizeRequest": 10000000,

     

       7
       7
       +
             "maxConcurrentRequests": 4,

     

       8
       8
       +
             "maxCallsInRequest": 16,

     

       9
       9
       +
             "maxObjectsInGet": 500,

     

       10
       10
       +
             "maxObjectsInSet": 500,

     

       11
       11
       +
             "collationAlgorithms": []

     

       12
       12
       +
           }

     

       13
       13
       +
         },

     

       14
       14
       +
         "accounts": {},

     

       15
       15
       +
         "primaryAccounts": {},

     

       16
       16
       +
         "username": "anonymous",

     

       17
       17
       +
         "apiUrl": "https://api.example.com/jmap/",

     

       18
       18
       +
         "downloadUrl": "https://api.example.com/download/{accountId}/{blobId}/{name}",

     

       19
       19
       +
         "uploadUrl": "https://api.example.com/upload/{accountId}/",

     

       20
       20
       +
         "eventSourceUrl": "https://api.example.com/events/",

     

       21
       21
       +
         "state": "empty"

     

       22
       22
       +
       }

+10

test/proto/session/invalid/missing_api_url.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "capabilities": {},

     

       3
       3
       +
         "accounts": {},

     

       4
       4
       +
         "primaryAccounts": {},

     

       5
       5
       +
         "username": "test@example.com",

     

       6
       6
       +
         "downloadUrl": "https://api.example.com/download/",

     

       7
       7
       +
         "uploadUrl": "https://api.example.com/upload/",

     

       8
       8
       +
         "eventSourceUrl": "https://api.example.com/events/",

     

       9
       9
       +
         "state": "abc"

     

       10
       10
       +
       }

+17

test/proto/session/invalid/missing_capabilities.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "accounts": {

     

       3
       3
       +
           "acc1": {

     

       4
       4
       +
             "name": "Test Account",

     

       5
       5
       +
             "isPersonal": true,

     

       6
       6
       +
             "isReadOnly": false,

     

       7
       7
       +
             "accountCapabilities": {}

     

       8
       8
       +
           }

     

       9
       9
       +
         },

     

       10
       10
       +
         "primaryAccounts": {},

     

       11
       11
       +
         "username": "test@example.com",

     

       12
       12
       +
         "apiUrl": "https://api.example.com/jmap/",

     

       13
       13
       +
         "downloadUrl": "https://api.example.com/download/",

     

       14
       14
       +
         "uploadUrl": "https://api.example.com/upload/",

     

       15
       15
       +
         "eventSourceUrl": "https://api.example.com/events/",

     

       16
       16
       +
         "state": "abc"

     

       17
       17
       +
       }

+31

test/proto/session/valid/minimal.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "capabilities": {

     

       3
       3
       +
           "urn:ietf:params:jmap:core": {

     

       4
       4
       +
             "maxSizeUpload": 50000000,

     

       5
       5
       +
             "maxConcurrentUpload": 4,

     

       6
       6
       +
             "maxSizeRequest": 10000000,

     

       7
       7
       +
             "maxConcurrentRequests": 4,

     

       8
       8
       +
             "maxCallsInRequest": 16,

     

       9
       9
       +
             "maxObjectsInGet": 500,

     

       10
       10
       +
             "maxObjectsInSet": 500,

     

       11
       11
       +
             "collationAlgorithms": ["i;ascii-casemap", "i;octet"]

     

       12
       12
       +
           }

     

       13
       13
       +
         },

     

       14
       14
       +
         "accounts": {

     

       15
       15
       +
           "acc1": {

     

       16
       16
       +
             "name": "Test Account",

     

       17
       17
       +
             "isPersonal": true,

     

       18
       18
       +
             "isReadOnly": false,

     

       19
       19
       +
             "accountCapabilities": {}

     

       20
       20
       +
           }

     

       21
       21
       +
         },

     

       22
       22
       +
         "primaryAccounts": {

     

       23
       23
       +
           "urn:ietf:params:jmap:core": "acc1"

     

       24
       24
       +
         },

     

       25
       25
       +
         "username": "test@example.com",

     

       26
       26
       +
         "apiUrl": "https://api.example.com/jmap/",

     

       27
       27
       +
         "downloadUrl": "https://api.example.com/jmap/download/{accountId}/{blobId}/{name}?type={type}",

     

       28
       28
       +
         "uploadUrl": "https://api.example.com/jmap/upload/{accountId}/",

     

       29
       29
       +
         "eventSourceUrl": "https://api.example.com/jmap/eventsource/",

     

       30
       30
       +
         "state": "abc123"

     

       31
       31
       +
       }

+44

test/proto/session/valid/with_accounts.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "capabilities": {

     

       3
       3
       +
           "urn:ietf:params:jmap:core": {

     

       4
       4
       +
             "maxSizeUpload": 50000000,

     

       5
       5
       +
             "maxConcurrentUpload": 4,

     

       6
       6
       +
             "maxSizeRequest": 10000000,

     

       7
       7
       +
             "maxConcurrentRequests": 4,

     

       8
       8
       +
             "maxCallsInRequest": 16,

     

       9
       9
       +
             "maxObjectsInGet": 500,

     

       10
       10
       +
             "maxObjectsInSet": 500,

     

       11
       11
       +
             "collationAlgorithms": ["i;ascii-casemap", "i;unicode-casemap"]

     

       12
       12
       +
           }

     

       13
       13
       +
         },

     

       14
       14
       +
         "accounts": {

     

       15
       15
       +
           "acc1": {

     

       16
       16
       +
             "name": "Personal Account",

     

       17
       17
       +
             "isPersonal": true,

     

       18
       18
       +
             "isReadOnly": false,

     

       19
       19
       +
             "accountCapabilities": {

     

       20
       20
       +
               "urn:ietf:params:jmap:core": {},

     

       21
       21
       +
               "urn:ietf:params:jmap:mail": {}

     

       22
       22
       +
             }

     

       23
       23
       +
           },

     

       24
       24
       +
           "acc2": {

     

       25
       25
       +
             "name": "Shared Account",

     

       26
       26
       +
             "isPersonal": false,

     

       27
       27
       +
             "isReadOnly": true,

     

       28
       28
       +
             "accountCapabilities": {

     

       29
       29
       +
               "urn:ietf:params:jmap:core": {},

     

       30
       30
       +
               "urn:ietf:params:jmap:mail": {}

     

       31
       31
       +
             }

     

       32
       32
       +
           }

     

       33
       33
       +
         },

     

       34
       34
       +
         "primaryAccounts": {

     

       35
       35
       +
           "urn:ietf:params:jmap:core": "acc1",

     

       36
       36
       +
           "urn:ietf:params:jmap:mail": "acc1"

     

       37
       37
       +
         },

     

       38
       38
       +
         "username": "user@example.com",

     

       39
       39
       +
         "apiUrl": "https://api.example.com/jmap/",

     

       40
       40
       +
         "downloadUrl": "https://api.example.com/download/{accountId}/{blobId}/{name}?accept={type}",

     

       41
       41
       +
         "uploadUrl": "https://api.example.com/upload/{accountId}/",

     

       42
       42
       +
         "eventSourceUrl": "https://api.example.com/eventsource/?types={types}&closeafter={closeafter}&ping={ping}",

     

       43
       43
       +
         "state": "session123"

     

       44
       44
       +
       }

+56

test/proto/session/valid/with_mail.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "capabilities": {

     

       3
       3
       +
           "urn:ietf:params:jmap:core": {

     

       4
       4
       +
             "maxSizeUpload": 50000000,

     

       5
       5
       +
             "maxConcurrentUpload": 4,

     

       6
       6
       +
             "maxSizeRequest": 10000000,

     

       7
       7
       +
             "maxConcurrentRequests": 4,

     

       8
       8
       +
             "maxCallsInRequest": 16,

     

       9
       9
       +
             "maxObjectsInGet": 500,

     

       10
       10
       +
             "maxObjectsInSet": 500,

     

       11
       11
       +
             "collationAlgorithms": ["i;ascii-casemap", "i;octet"]

     

       12
       12
       +
           },

     

       13
       13
       +
           "urn:ietf:params:jmap:mail": {

     

       14
       14
       +
             "maxMailboxesPerEmail": 1000,

     

       15
       15
       +
             "maxMailboxDepth": 10,

     

       16
       16
       +
             "maxSizeMailboxName": 490,

     

       17
       17
       +
             "maxSizeAttachmentsPerEmail": 50000000,

     

       18
       18
       +
             "emailQuerySortOptions": ["receivedAt", "from", "to", "subject", "size"],

     

       19
       19
       +
             "mayCreateTopLevelMailbox": true

     

       20
       20
       +
           },

     

       21
       21
       +
           "urn:ietf:params:jmap:submission": {

     

       22
       22
       +
             "maxDelayedSend": 86400,

     

       23
       23
       +
             "submissionExtensions": {}

     

       24
       24
       +
           }

     

       25
       25
       +
         },

     

       26
       26
       +
         "accounts": {

     

       27
       27
       +
           "A001": {

     

       28
       28
       +
             "name": "Personal",

     

       29
       29
       +
             "isPersonal": true,

     

       30
       30
       +
             "isReadOnly": false,

     

       31
       31
       +
             "accountCapabilities": {

     

       32
       32
       +
               "urn:ietf:params:jmap:core": {},

     

       33
       33
       +
               "urn:ietf:params:jmap:mail": {}

     

       34
       34
       +
             }

     

       35
       35
       +
           },

     

       36
       36
       +
           "A002": {

     

       37
       37
       +
             "name": "Shared Archive",

     

       38
       38
       +
             "isPersonal": false,

     

       39
       39
       +
             "isReadOnly": true,

     

       40
       40
       +
             "accountCapabilities": {

     

       41
       41
       +
               "urn:ietf:params:jmap:mail": {}

     

       42
       42
       +
             }

     

       43
       43
       +
           }

     

       44
       44
       +
         },

     

       45
       45
       +
         "primaryAccounts": {

     

       46
       46
       +
           "urn:ietf:params:jmap:core": "A001",

     

       47
       47
       +
           "urn:ietf:params:jmap:mail": "A001",

     

       48
       48
       +
           "urn:ietf:params:jmap:submission": "A001"

     

       49
       49
       +
         },

     

       50
       50
       +
         "username": "john.doe@example.com",

     

       51
       51
       +
         "apiUrl": "https://jmap.example.com/api/",

     

       52
       52
       +
         "downloadUrl": "https://jmap.example.com/download/{accountId}/{blobId}/{name}?type={type}",

     

       53
       53
       +
         "uploadUrl": "https://jmap.example.com/upload/{accountId}/",

     

       54
       54
       +
         "eventSourceUrl": "https://jmap.example.com/events/?types={types}&closeafter={closeafter}&ping={ping}",

     

       55
       55
       +
         "state": "xyz789-session-state"

     

       56
       56
       +
       }

+987

test/proto/test_proto.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** JMAP Protocol codec tests using sample JSON files *)

     

       7
       7
       +
       

     

       8
       8
       +
       let read_file path =

     

       9
       9
       +
         let ic = open_in path in

     

       10
       10
       +
         let n = in_channel_length ic in

     

       11
       11
       +
         let s = really_input_string ic n in

     

       12
       12
       +
         close_in ic;

     

       13
       13
       +
         s

     

       14
       14
       +
       

     

       15
       15
       +
       let decode jsont json_str =

     

       16
       16
       +
         Jsont_bytesrw.decode_string' jsont json_str

     

       17
       17
       +
       

     

       18
       18
       +
       let encode jsont value =

     

       19
       19
       +
         Jsont_bytesrw.encode_string' jsont value

     

       20
       20
       +
       

     

       21
       21
       +
       (* Test helpers *)

     

       22
       22
       +
       

     

       23
       23
       +
       let test_decode_success name jsont path () =

     

       24
       24
       +
         let json = read_file path in

     

       25
       25
       +
         match decode jsont json with

     

       26
       26
       +
         | Ok _ -> ()

     

       27
       27
       +
         | Error e ->

     

       28
       28
       +
             Alcotest.failf "%s: expected success but got error: %s" name (Jsont.Error.to_string e)

     

       29
       29
       +
       

     

       30
       30
       +
       let test_decode_failure name jsont path () =

     

       31
       31
       +
         let json = read_file path in

     

       32
       32
       +
         match decode jsont json with

     

       33
       33
       +
         | Ok _ -> Alcotest.failf "%s: expected failure but got success" name

     

       34
       34
       +
         | Error _ -> ()

     

       35
       35
       +
       

     

       36
       36
       +
       let test_roundtrip name jsont path () =

     

       37
       37
       +
         let json = read_file path in

     

       38
       38
       +
         match decode jsont json with

     

       39
       39
       +
         | Error e ->

     

       40
       40
       +
             Alcotest.failf "%s: decode failed: %s" name (Jsont.Error.to_string e)

     

       41
       41
       +
         | Ok value ->

     

       42
       42
       +
             match encode jsont value with

     

       43
       43
       +
             | Error e ->

     

       44
       44
       +
                 Alcotest.failf "%s: encode failed: %s" name (Jsont.Error.to_string e)

     

       45
       45
       +
             | Ok encoded ->

     

       46
       46
       +
                 match decode jsont encoded with

     

       47
       47
       +
                 | Error e ->

     

       48
       48
       +
                     Alcotest.failf "%s: re-decode failed: %s" name (Jsont.Error.to_string e)

     

       49
       49
       +
                 | Ok _ -> ()

     

       50
       50
       +
       

     

       51
       51
       +
       (* ID tests *)

     

       52
       52
       +
       module Id_tests = struct

     

       53
       53
       +
         open Jmap_proto

     

       54
       54
       +
       

     

       55
       55
       +
         let test_valid_simple () =

     

       56
       56
       +
           let json = "\"abc123\"" in

     

       57
       57
       +
           match decode Id.jsont json with

     

       58
       58
       +
           | Ok id -> Alcotest.(check string) "id value" "abc123" (Id.to_string id)

     

       59
       59
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       60
       60
       +
       

     

       61
       61
       +
         let test_valid_single_char () =

     

       62
       62
       +
           let json = "\"a\"" in

     

       63
       63
       +
           match decode Id.jsont json with

     

       64
       64
       +
           | Ok id -> Alcotest.(check string) "id value" "a" (Id.to_string id)

     

       65
       65
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       66
       66
       +
       

     

       67
       67
       +
         let test_valid_with_hyphen () =

     

       68
       68
       +
           let json = "\"msg-2024-01\"" in

     

       69
       69
       +
           match decode Id.jsont json with

     

       70
       70
       +
           | Ok id -> Alcotest.(check string) "id value" "msg-2024-01" (Id.to_string id)

     

       71
       71
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       72
       72
       +
       

     

       73
       73
       +
         let test_valid_with_underscore () =

     

       74
       74
       +
           let json = "\"user_id_123\"" in

     

       75
       75
       +
           match decode Id.jsont json with

     

       76
       76
       +
           | Ok id -> Alcotest.(check string) "id value" "user_id_123" (Id.to_string id)

     

       77
       77
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       78
       78
       +
       

     

       79
       79
       +
         let test_invalid_empty () =

     

       80
       80
       +
           let json = "\"\"" in

     

       81
       81
       +
           match decode Id.jsont json with

     

       82
       82
       +
           | Ok _ -> Alcotest.fail "expected failure for empty id"

     

       83
       83
       +
           | Error _ -> ()

     

       84
       84
       +
       

     

       85
       85
       +
         let test_invalid_with_space () =

     

       86
       86
       +
           let json = "\"hello world\"" in

     

       87
       87
       +
           match decode Id.jsont json with

     

       88
       88
       +
           | Ok _ -> Alcotest.fail "expected failure for id with space"

     

       89
       89
       +
           | Error _ -> ()

     

       90
       90
       +
       

     

       91
       91
       +
         let test_invalid_with_special () =

     

       92
       92
       +
           let json = "\"abc@def\"" in

     

       93
       93
       +
           match decode Id.jsont json with

     

       94
       94
       +
           | Ok _ -> Alcotest.fail "expected failure for id with @"

     

       95
       95
       +
           | Error _ -> ()

     

       96
       96
       +
       

     

       97
       97
       +
         let test_invalid_not_string () =

     

       98
       98
       +
           let json = "12345" in

     

       99
       99
       +
           match decode Id.jsont json with

     

       100
       100
       +
           | Ok _ -> Alcotest.fail "expected failure for non-string"

     

       101
       101
       +
           | Error _ -> ()

     

       102
       102
       +
       

     

       103
       103
       +
         let test_edge_max_length () =

     

       104
       104
       +
           let id_255 = String.make 255 'a' in

     

       105
       105
       +
           let json = Printf.sprintf "\"%s\"" id_255 in

     

       106
       106
       +
           match decode Id.jsont json with

     

       107
       107
       +
           | Ok id -> Alcotest.(check int) "id length" 255 (String.length (Id.to_string id))

     

       108
       108
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       109
       109
       +
       

     

       110
       110
       +
         let test_edge_over_max_length () =

     

       111
       111
       +
           let id_256 = String.make 256 'a' in

     

       112
       112
       +
           let json = Printf.sprintf "\"%s\"" id_256 in

     

       113
       113
       +
           match decode Id.jsont json with

     

       114
       114
       +
           | Ok _ -> Alcotest.fail "expected failure for 256 char id"

     

       115
       115
       +
           | Error _ -> ()

     

       116
       116
       +
       

     

       117
       117
       +
         let tests = [

     

       118
       118
       +
           "valid: simple", `Quick, test_valid_simple;

     

       119
       119
       +
           "valid: single char", `Quick, test_valid_single_char;

     

       120
       120
       +
           "valid: with hyphen", `Quick, test_valid_with_hyphen;

     

       121
       121
       +
           "valid: with underscore", `Quick, test_valid_with_underscore;

     

       122
       122
       +
           "invalid: empty", `Quick, test_invalid_empty;

     

       123
       123
       +
           "invalid: with space", `Quick, test_invalid_with_space;

     

       124
       124
       +
           "invalid: with special", `Quick, test_invalid_with_special;

     

       125
       125
       +
           "invalid: not string", `Quick, test_invalid_not_string;

     

       126
       126
       +
           "edge: max length 255", `Quick, test_edge_max_length;

     

       127
       127
       +
           "edge: over max length 256", `Quick, test_edge_over_max_length;

     

       128
       128
       +
         ]

     

       129
       129
       +
       end

     

       130
       130
       +
       

     

       131
       131
       +
       (* Int53 tests *)

     

       132
       132
       +
       module Int53_tests = struct

     

       133
       133
       +
         open Jmap_proto

     

       134
       134
       +
       

     

       135
       135
       +
         let test_zero () =

     

       136
       136
       +
           match decode Int53.Signed.jsont "0" with

     

       137
       137
       +
           | Ok n -> Alcotest.(check int64) "value" 0L n

     

       138
       138
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       139
       139
       +
       

     

       140
       140
       +
         let test_positive () =

     

       141
       141
       +
           match decode Int53.Signed.jsont "12345" with

     

       142
       142
       +
           | Ok n -> Alcotest.(check int64) "value" 12345L n

     

       143
       143
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       144
       144
       +
       

     

       145
       145
       +
         let test_negative () =

     

       146
       146
       +
           match decode Int53.Signed.jsont "-12345" with

     

       147
       147
       +
           | Ok n -> Alcotest.(check int64) "value" (-12345L) n

     

       148
       148
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       149
       149
       +
       

     

       150
       150
       +
         let test_max_safe () =

     

       151
       151
       +
           match decode Int53.Signed.jsont "9007199254740991" with

     

       152
       152
       +
           | Ok n -> Alcotest.(check int64) "value" 9007199254740991L n

     

       153
       153
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       154
       154
       +
       

     

       155
       155
       +
         let test_min_safe () =

     

       156
       156
       +
           match decode Int53.Signed.jsont "-9007199254740991" with

     

       157
       157
       +
           | Ok n -> Alcotest.(check int64) "value" (-9007199254740991L) n

     

       158
       158
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       159
       159
       +
       

     

       160
       160
       +
         let test_over_max_safe () =

     

       161
       161
       +
           match decode Int53.Signed.jsont "9007199254740992" with

     

       162
       162
       +
           | Ok _ -> Alcotest.fail "expected failure for over max safe"

     

       163
       163
       +
           | Error _ -> ()

     

       164
       164
       +
       

     

       165
       165
       +
         let test_under_min_safe () =

     

       166
       166
       +
           match decode Int53.Signed.jsont "-9007199254740992" with

     

       167
       167
       +
           | Ok _ -> Alcotest.fail "expected failure for under min safe"

     

       168
       168
       +
           | Error _ -> ()

     

       169
       169
       +
       

     

       170
       170
       +
         let test_unsigned_zero () =

     

       171
       171
       +
           match decode Int53.Unsigned.jsont "0" with

     

       172
       172
       +
           | Ok n -> Alcotest.(check int64) "value" 0L n

     

       173
       173
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       174
       174
       +
       

     

       175
       175
       +
         let test_unsigned_max () =

     

       176
       176
       +
           match decode Int53.Unsigned.jsont "9007199254740991" with

     

       177
       177
       +
           | Ok n -> Alcotest.(check int64) "value" 9007199254740991L n

     

       178
       178
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       179
       179
       +
       

     

       180
       180
       +
         let test_unsigned_negative () =

     

       181
       181
       +
           match decode Int53.Unsigned.jsont "-1" with

     

       182
       182
       +
           | Ok _ -> Alcotest.fail "expected failure for negative unsigned"

     

       183
       183
       +
           | Error _ -> ()

     

       184
       184
       +
       

     

       185
       185
       +
         let tests = [

     

       186
       186
       +
           "signed: zero", `Quick, test_zero;

     

       187
       187
       +
           "signed: positive", `Quick, test_positive;

     

       188
       188
       +
           "signed: negative", `Quick, test_negative;

     

       189
       189
       +
           "signed: max safe", `Quick, test_max_safe;

     

       190
       190
       +
           "signed: min safe", `Quick, test_min_safe;

     

       191
       191
       +
           "signed: over max safe", `Quick, test_over_max_safe;

     

       192
       192
       +
           "signed: under min safe", `Quick, test_under_min_safe;

     

       193
       193
       +
           "unsigned: zero", `Quick, test_unsigned_zero;

     

       194
       194
       +
           "unsigned: max", `Quick, test_unsigned_max;

     

       195
       195
       +
           "unsigned: negative fails", `Quick, test_unsigned_negative;

     

       196
       196
       +
         ]

     

       197
       197
       +
       end

     

       198
       198
       +
       

     

       199
       199
       +
       (* Date tests *)

     

       200
       200
       +
       module Date_tests = struct

     

       201
       201
       +
         open Jmap_proto

     

       202
       202
       +
       

     

       203
       203
       +
         let test_utc_z () =

     

       204
       204
       +
           match decode Date.Utc.jsont "\"2024-01-15T10:30:00Z\"" with

     

       205
       205
       +
           | Ok _ -> ()

     

       206
       206
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       207
       207
       +
       

     

       208
       208
       +
         let test_rfc3339_with_offset () =

     

       209
       209
       +
           match decode Date.Rfc3339.jsont "\"2024-01-15T10:30:00+05:30\"" with

     

       210
       210
       +
           | Ok _ -> ()

     

       211
       211
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       212
       212
       +
       

     

       213
       213
       +
         let test_with_milliseconds () =

     

       214
       214
       +
           match decode Date.Rfc3339.jsont "\"2024-01-15T10:30:00.123Z\"" with

     

       215
       215
       +
           | Ok _ -> ()

     

       216
       216
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       217
       217
       +
       

     

       218
       218
       +
         let test_invalid_format () =

     

       219
       219
       +
           match decode Date.Rfc3339.jsont "\"January 15, 2024\"" with

     

       220
       220
       +
           | Ok _ -> Alcotest.fail "expected failure for invalid format"

     

       221
       221
       +
           | Error _ -> ()

     

       222
       222
       +
       

     

       223
       223
       +
         let test_not_string () =

     

       224
       224
       +
           match decode Date.Rfc3339.jsont "1705315800" with

     

       225
       225
       +
           | Ok _ -> Alcotest.fail "expected failure for non-string"

     

       226
       226
       +
           | Error _ -> ()

     

       227
       227
       +
       

     

       228
       228
       +
         let tests = [

     

       229
       229
       +
           "utc: Z suffix", `Quick, test_utc_z;

     

       230
       230
       +
           "rfc3339: with offset", `Quick, test_rfc3339_with_offset;

     

       231
       231
       +
           "rfc3339: with milliseconds", `Quick, test_with_milliseconds;

     

       232
       232
       +
           "invalid: bad format", `Quick, test_invalid_format;

     

       233
       233
       +
           "invalid: not string", `Quick, test_not_string;

     

       234
       234
       +
         ]

     

       235
       235
       +
       end

     

       236
       236
       +
       

     

       237
       237
       +
       (* Session tests *)

     

       238
       238
       +
       module Session_tests = struct

     

       239
       239
       +
         open Jmap_proto

     

       240
       240
       +
       

     

       241
       241
       +
         let test_minimal () =

     

       242
       242
       +
           test_decode_success "minimal session" Session.jsont "session/valid/minimal.json" ()

     

       243
       243
       +
       

     

       244
       244
       +
         let test_with_mail () =

     

       245
       245
       +
           test_decode_success "session with mail" Session.jsont "session/valid/with_mail.json" ()

     

       246
       246
       +
       

     

       247
       247
       +
         let test_roundtrip_minimal () =

     

       248
       248
       +
           test_roundtrip "minimal session roundtrip" Session.jsont "session/valid/minimal.json" ()

     

       249
       249
       +
       

     

       250
       250
       +
         let test_values () =

     

       251
       251
       +
           let json = read_file "session/valid/minimal.json" in

     

       252
       252
       +
           match decode Session.jsont json with

     

       253
       253
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       254
       254
       +
           | Ok session ->

     

       255
       255
       +
               Alcotest.(check string) "username" "test@example.com" (Session.username session);

     

       256
       256
       +
               Alcotest.(check string) "apiUrl" "https://api.example.com/jmap/" (Session.api_url session);

     

       257
       257
       +
               Alcotest.(check string) "state" "abc123" (Session.state session);

     

       258
       258
       +
               Alcotest.(check bool) "has core capability" true

     

       259
       259
       +
                 (Session.has_capability Capability.core session)

     

       260
       260
       +
       

     

       261
       261
       +
         let test_with_accounts () =

     

       262
       262
       +
           test_decode_success "with accounts" Session.jsont "session/valid/with_accounts.json" ()

     

       263
       263
       +
       

     

       264
       264
       +
         let test_empty_accounts () =

     

       265
       265
       +
           test_decode_success "empty accounts" Session.jsont "session/edge/empty_accounts.json" ()

     

       266
       266
       +
       

     

       267
       267
       +
         let test_accounts_values () =

     

       268
       268
       +
           let json = read_file "session/valid/with_accounts.json" in

     

       269
       269
       +
           match decode Session.jsont json with

     

       270
       270
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       271
       271
       +
           | Ok session ->

     

       272
       272
       +
               Alcotest.(check int) "accounts count" 2 (List.length (Session.accounts session));

     

       273
       273
       +
               Alcotest.(check int) "primary_accounts count" 2 (List.length (Session.primary_accounts session))

     

       274
       274
       +
       

     

       275
       275
       +
         let tests = [

     

       276
       276
       +
           "valid: minimal", `Quick, test_minimal;

     

       277
       277
       +
           "valid: with mail", `Quick, test_with_mail;

     

       278
       278
       +
           "valid: with accounts", `Quick, test_with_accounts;

     

       279
       279
       +
           "edge: empty accounts", `Quick, test_empty_accounts;

     

       280
       280
       +
           "roundtrip: minimal", `Quick, test_roundtrip_minimal;

     

       281
       281
       +
           "values: minimal", `Quick, test_values;

     

       282
       282
       +
           "values: accounts", `Quick, test_accounts_values;

     

       283
       283
       +
         ]

     

       284
       284
       +
       end

     

       285
       285
       +
       

     

       286
       286
       +
       (* Request tests *)

     

       287
       287
       +
       module Request_tests = struct

     

       288
       288
       +
         open Jmap_proto

     

       289
       289
       +
       

     

       290
       290
       +
         let test_single_method () =

     

       291
       291
       +
           test_decode_success "single method" Request.jsont "request/valid/single_method.json" ()

     

       292
       292
       +
       

     

       293
       293
       +
         let test_multiple_methods () =

     

       294
       294
       +
           test_decode_success "multiple methods" Request.jsont "request/valid/multiple_methods.json" ()

     

       295
       295
       +
       

     

       296
       296
       +
         let test_with_created_ids () =

     

       297
       297
       +
           test_decode_success "with created ids" Request.jsont "request/valid/with_created_ids.json" ()

     

       298
       298
       +
       

     

       299
       299
       +
         let test_empty_methods () =

     

       300
       300
       +
           test_decode_success "empty methods" Request.jsont "request/valid/empty_methods.json" ()

     

       301
       301
       +
       

     

       302
       302
       +
         let test_values () =

     

       303
       303
       +
           let json = read_file "request/valid/single_method.json" in

     

       304
       304
       +
           match decode Request.jsont json with

     

       305
       305
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       306
       306
       +
           | Ok request ->

     

       307
       307
       +
               Alcotest.(check int) "using count" 2 (List.length (Request.using request));

     

       308
       308
       +
               Alcotest.(check int) "method calls count" 1 (List.length (Request.method_calls request))

     

       309
       309
       +
       

     

       310
       310
       +
         let test_roundtrip () =

     

       311
       311
       +
           test_roundtrip "single method roundtrip" Request.jsont "request/valid/single_method.json" ()

     

       312
       312
       +
       

     

       313
       313
       +
         let tests = [

     

       314
       314
       +
           "valid: single method", `Quick, test_single_method;

     

       315
       315
       +
           "valid: multiple methods", `Quick, test_multiple_methods;

     

       316
       316
       +
           "valid: with created ids", `Quick, test_with_created_ids;

     

       317
       317
       +
           "valid: empty methods", `Quick, test_empty_methods;

     

       318
       318
       +
           "values: single method", `Quick, test_values;

     

       319
       319
       +
           "roundtrip: single method", `Quick, test_roundtrip;

     

       320
       320
       +
         ]

     

       321
       321
       +
       end

     

       322
       322
       +
       

     

       323
       323
       +
       (* Response tests *)

     

       324
       324
       +
       module Response_tests = struct

     

       325
       325
       +
         open Jmap_proto

     

       326
       326
       +
       

     

       327
       327
       +
         let test_success () =

     

       328
       328
       +
           test_decode_success "success" Response.jsont "response/valid/success.json" ()

     

       329
       329
       +
       

     

       330
       330
       +
         let test_with_created_ids () =

     

       331
       331
       +
           test_decode_success "with created ids" Response.jsont "response/valid/with_created_ids.json" ()

     

       332
       332
       +
       

     

       333
       333
       +
         let test_with_error () =

     

       334
       334
       +
           test_decode_success "with error" Response.jsont "response/valid/with_error.json" ()

     

       335
       335
       +
       

     

       336
       336
       +
         let test_multiple_responses () =

     

       337
       337
       +
           test_decode_success "multiple responses" Response.jsont "response/valid/multiple_responses.json" ()

     

       338
       338
       +
       

     

       339
       339
       +
         let test_values () =

     

       340
       340
       +
           let json = read_file "response/valid/success.json" in

     

       341
       341
       +
           match decode Response.jsont json with

     

       342
       342
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       343
       343
       +
           | Ok response ->

     

       344
       344
       +
               Alcotest.(check string) "session state" "session123" (Response.session_state response);

     

       345
       345
       +
               Alcotest.(check int) "method responses count" 1 (List.length (Response.method_responses response))

     

       346
       346
       +
       

     

       347
       347
       +
         let test_roundtrip () =

     

       348
       348
       +
           test_roundtrip "success roundtrip" Response.jsont "response/valid/success.json" ()

     

       349
       349
       +
       

     

       350
       350
       +
         let tests = [

     

       351
       351
       +
           "valid: success", `Quick, test_success;

     

       352
       352
       +
           "valid: with created ids", `Quick, test_with_created_ids;

     

       353
       353
       +
           "valid: with error", `Quick, test_with_error;

     

       354
       354
       +
           "valid: multiple responses", `Quick, test_multiple_responses;

     

       355
       355
       +
           "values: success", `Quick, test_values;

     

       356
       356
       +
           "roundtrip: success", `Quick, test_roundtrip;

     

       357
       357
       +
         ]

     

       358
       358
       +
       end

     

       359
       359
       +
       

     

       360
       360
       +
       (* Invocation tests *)

     

       361
       361
       +
       module Invocation_tests = struct

     

       362
       362
       +
         open Jmap_proto

     

       363
       363
       +
       

     

       364
       364
       +
         let test_get () =

     

       365
       365
       +
           test_decode_success "get" Invocation.jsont "invocation/valid/get.json" ()

     

       366
       366
       +
       

     

       367
       367
       +
         let test_set () =

     

       368
       368
       +
           test_decode_success "set" Invocation.jsont "invocation/valid/set.json" ()

     

       369
       369
       +
       

     

       370
       370
       +
         let test_query () =

     

       371
       371
       +
           test_decode_success "query" Invocation.jsont "invocation/valid/query.json" ()

     

       372
       372
       +
       

     

       373
       373
       +
         let test_values () =

     

       374
       374
       +
           let json = read_file "invocation/valid/get.json" in

     

       375
       375
       +
           match decode Invocation.jsont json with

     

       376
       376
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       377
       377
       +
           | Ok inv ->

     

       378
       378
       +
               Alcotest.(check string) "name" "Email/get" (Invocation.name inv);

     

       379
       379
       +
               Alcotest.(check string) "method call id" "call-001" (Invocation.method_call_id inv)

     

       380
       380
       +
       

     

       381
       381
       +
         let test_invalid_not_array () =

     

       382
       382
       +
           test_decode_failure "not array" Invocation.jsont "invocation/invalid/not_array.json" ()

     

       383
       383
       +
       

     

       384
       384
       +
         let test_invalid_wrong_length () =

     

       385
       385
       +
           test_decode_failure "wrong length" Invocation.jsont "invocation/invalid/wrong_length.json" ()

     

       386
       386
       +
       

     

       387
       387
       +
         let tests = [

     

       388
       388
       +
           "valid: get", `Quick, test_get;

     

       389
       389
       +
           "valid: set", `Quick, test_set;

     

       390
       390
       +
           "valid: query", `Quick, test_query;

     

       391
       391
       +
           "values: get", `Quick, test_values;

     

       392
       392
       +
           "invalid: not array", `Quick, test_invalid_not_array;

     

       393
       393
       +
           "invalid: wrong length", `Quick, test_invalid_wrong_length;

     

       394
       394
       +
         ]

     

       395
       395
       +
       end

     

       396
       396
       +
       

     

       397
       397
       +
       (* Capability tests *)

     

       398
       398
       +
       module Capability_tests = struct

     

       399
       399
       +
         open Jmap_proto

     

       400
       400
       +
       

     

       401
       401
       +
         let test_core () =

     

       402
       402
       +
           test_decode_success "core" Capability.Core.jsont "capability/valid/core.json" ()

     

       403
       403
       +
       

     

       404
       404
       +
         let test_mail () =

     

       405
       405
       +
           test_decode_success "mail" Capability.Mail.jsont "capability/valid/mail.json" ()

     

       406
       406
       +
       

     

       407
       407
       +
         let test_submission () =

     

       408
       408
       +
           test_decode_success "submission" Capability.Submission.jsont "capability/valid/submission.json" ()

     

       409
       409
       +
       

     

       410
       410
       +
         let test_core_values () =

     

       411
       411
       +
           let json = read_file "capability/valid/core.json" in

     

       412
       412
       +
           match decode Capability.Core.jsont json with

     

       413
       413
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       414
       414
       +
           | Ok cap ->

     

       415
       415
       +
               Alcotest.(check int64) "maxSizeUpload" 50000000L (Capability.Core.max_size_upload cap);

     

       416
       416
       +
               Alcotest.(check int) "maxConcurrentUpload" 4 (Capability.Core.max_concurrent_upload cap);

     

       417
       417
       +
               Alcotest.(check int) "maxCallsInRequest" 16 (Capability.Core.max_calls_in_request cap)

     

       418
       418
       +
       

     

       419
       419
       +
         let test_mail_values () =

     

       420
       420
       +
           let json = read_file "capability/valid/mail.json" in

     

       421
       421
       +
           match decode Capability.Mail.jsont json with

     

       422
       422
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       423
       423
       +
           | Ok cap ->

     

       424
       424
       +
               Alcotest.(check int64) "maxSizeMailboxName" 490L (Capability.Mail.max_size_mailbox_name cap);

     

       425
       425
       +
               Alcotest.(check bool) "mayCreateTopLevelMailbox" true (Capability.Mail.may_create_top_level_mailbox cap)

     

       426
       426
       +
       

     

       427
       427
       +
         let tests = [

     

       428
       428
       +
           "valid: core", `Quick, test_core;

     

       429
       429
       +
           "valid: mail", `Quick, test_mail;

     

       430
       430
       +
           "valid: submission", `Quick, test_submission;

     

       431
       431
       +
           "values: core", `Quick, test_core_values;

     

       432
       432
       +
           "values: mail", `Quick, test_mail_values;

     

       433
       433
       +
         ]

     

       434
       434
       +
       end

     

       435
       435
       +
       

     

       436
       436
       +
       (* Method args/response tests *)

     

       437
       437
       +
       module Method_tests = struct

     

       438
       438
       +
         open Jmap_proto

     

       439
       439
       +
       

     

       440
       440
       +
         let test_get_args () =

     

       441
       441
       +
           test_decode_success "get_args" Method.get_args_jsont "method/valid/get_args.json" ()

     

       442
       442
       +
       

     

       443
       443
       +
         let test_get_args_minimal () =

     

       444
       444
       +
           test_decode_success "get_args_minimal" Method.get_args_jsont "method/valid/get_args_minimal.json" ()

     

       445
       445
       +
       

     

       446
       446
       +
         let test_query_response () =

     

       447
       447
       +
           test_decode_success "query_response" Method.query_response_jsont "method/valid/query_response.json" ()

     

       448
       448
       +
       

     

       449
       449
       +
         let test_changes_response () =

     

       450
       450
       +
           test_decode_success "changes_response" Method.changes_response_jsont "method/valid/changes_response.json" ()

     

       451
       451
       +
       

     

       452
       452
       +
         let test_get_args_values () =

     

       453
       453
       +
           let json = read_file "method/valid/get_args.json" in

     

       454
       454
       +
           match decode Method.get_args_jsont json with

     

       455
       455
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       456
       456
       +
           | Ok args ->

     

       457
       457
       +
               Alcotest.(check string) "accountId" "acc1" (Id.to_string args.account_id);

     

       458
       458
       +
               Alcotest.(check (option (list string))) "properties" (Some ["id"; "name"; "role"]) args.properties

     

       459
       459
       +
       

     

       460
       460
       +
         let test_query_response_values () =

     

       461
       461
       +
           let json = read_file "method/valid/query_response.json" in

     

       462
       462
       +
           match decode Method.query_response_jsont json with

     

       463
       463
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       464
       464
       +
           | Ok resp ->

     

       465
       465
       +
               Alcotest.(check int) "ids count" 5 (List.length resp.ids);

     

       466
       466
       +
               Alcotest.(check int64) "position" 0L resp.position;

     

       467
       467
       +
               Alcotest.(check bool) "canCalculateChanges" true resp.can_calculate_changes;

     

       468
       468
       +
               Alcotest.(check (option int64)) "total" (Some 250L) resp.total

     

       469
       469
       +
       

     

       470
       470
       +
         let test_changes_response_values () =

     

       471
       471
       +
           let json = read_file "method/valid/changes_response.json" in

     

       472
       472
       +
           match decode Method.changes_response_jsont json with

     

       473
       473
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       474
       474
       +
           | Ok resp ->

     

       475
       475
       +
               Alcotest.(check string) "oldState" "old123" resp.old_state;

     

       476
       476
       +
               Alcotest.(check string) "newState" "new456" resp.new_state;

     

       477
       477
       +
               Alcotest.(check bool) "hasMoreChanges" false resp.has_more_changes;

     

       478
       478
       +
               Alcotest.(check int) "created count" 2 (List.length resp.created);

     

       479
       479
       +
               Alcotest.(check int) "destroyed count" 2 (List.length resp.destroyed)

     

       480
       480
       +
       

     

       481
       481
       +
         let tests = [

     

       482
       482
       +
           "valid: get_args", `Quick, test_get_args;

     

       483
       483
       +
           "valid: get_args_minimal", `Quick, test_get_args_minimal;

     

       484
       484
       +
           "valid: query_response", `Quick, test_query_response;

     

       485
       485
       +
           "valid: changes_response", `Quick, test_changes_response;

     

       486
       486
       +
           "values: get_args", `Quick, test_get_args_values;

     

       487
       487
       +
           "values: query_response", `Quick, test_query_response_values;

     

       488
       488
       +
           "values: changes_response", `Quick, test_changes_response_values;

     

       489
       489
       +
         ]

     

       490
       490
       +
       end

     

       491
       491
       +
       

     

       492
       492
       +
       (* Error tests *)

     

       493
       493
       +
       module Error_tests = struct

     

       494
       494
       +
         open Jmap_proto

     

       495
       495
       +
       

     

       496
       496
       +
         let test_method_error () =

     

       497
       497
       +
           test_decode_success "method_error" Error.method_error_jsont "error/valid/method_error.json" ()

     

       498
       498
       +
       

     

       499
       499
       +
         let test_set_error () =

     

       500
       500
       +
           test_decode_success "set_error" Error.set_error_jsont "error/valid/set_error.json" ()

     

       501
       501
       +
       

     

       502
       502
       +
         let test_request_error () =

     

       503
       503
       +
           test_decode_success "request_error" Error.Request_error.jsont "error/valid/request_error.json" ()

     

       504
       504
       +
       

     

       505
       505
       +
         let method_error_type_testable =

     

       506
       506
       +
           Alcotest.testable

     

       507
       507
       +
             (fun fmt t -> Format.pp_print_string fmt (Error.method_error_type_to_string t))

     

       508
       508
       +
             (=)

     

       509
       509
       +
       

     

       510
       510
       +
         let test_method_error_values () =

     

       511
       511
       +
           let json = read_file "error/valid/method_error.json" in

     

       512
       512
       +
           match decode Error.method_error_jsont json with

     

       513
       513
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       514
       514
       +
           | Ok err ->

     

       515
       515
       +
               Alcotest.(check method_error_type_testable) "type" Error.Unknown_method err.type_

     

       516
       516
       +
       

     

       517
       517
       +
         (* Additional error type tests *)

     

       518
       518
       +
         let test_set_error_forbidden () =

     

       519
       519
       +
           test_decode_success "set_error_forbidden" Error.set_error_jsont "error/valid/set_error_forbidden.json" ()

     

       520
       520
       +
       

     

       521
       521
       +
         let test_set_error_not_found () =

     

       522
       522
       +
           test_decode_success "set_error_not_found" Error.set_error_jsont "error/valid/set_error_not_found.json" ()

     

       523
       523
       +
       

     

       524
       524
       +
         let test_set_error_invalid_properties () =

     

       525
       525
       +
           test_decode_success "set_error_invalid_properties" Error.set_error_jsont "error/valid/set_error_invalid_properties.json" ()

     

       526
       526
       +
       

     

       527
       527
       +
         let test_set_error_singleton () =

     

       528
       528
       +
           test_decode_success "set_error_singleton" Error.set_error_jsont "error/valid/set_error_singleton.json" ()

     

       529
       529
       +
       

     

       530
       530
       +
         let test_set_error_over_quota () =

     

       531
       531
       +
           test_decode_success "set_error_over_quota" Error.set_error_jsont "error/valid/set_error_over_quota.json" ()

     

       532
       532
       +
       

     

       533
       533
       +
         let test_method_error_invalid_arguments () =

     

       534
       534
       +
           test_decode_success "method_error_invalid_arguments" Error.method_error_jsont "error/valid/method_error_invalid_arguments.json" ()

     

       535
       535
       +
       

     

       536
       536
       +
         let test_method_error_server_fail () =

     

       537
       537
       +
           test_decode_success "method_error_server_fail" Error.method_error_jsont "error/valid/method_error_server_fail.json" ()

     

       538
       538
       +
       

     

       539
       539
       +
         let test_method_error_account_not_found () =

     

       540
       540
       +
           test_decode_success "method_error_account_not_found" Error.method_error_jsont "error/valid/method_error_account_not_found.json" ()

     

       541
       541
       +
       

     

       542
       542
       +
         let test_method_error_forbidden () =

     

       543
       543
       +
           test_decode_success "method_error_forbidden" Error.method_error_jsont "error/valid/method_error_forbidden.json" ()

     

       544
       544
       +
       

     

       545
       545
       +
         let test_method_error_account_read_only () =

     

       546
       546
       +
           test_decode_success "method_error_account_read_only" Error.method_error_jsont "error/valid/method_error_account_read_only.json" ()

     

       547
       547
       +
       

     

       548
       548
       +
         let test_request_error_not_json () =

     

       549
       549
       +
           test_decode_success "request_error_not_json" Error.Request_error.jsont "error/valid/request_error_not_json.json" ()

     

       550
       550
       +
       

     

       551
       551
       +
         let test_request_error_limit () =

     

       552
       552
       +
           test_decode_success "request_error_limit" Error.Request_error.jsont "error/valid/request_error_limit.json" ()

     

       553
       553
       +
       

     

       554
       554
       +
         let set_error_type_testable =

     

       555
       555
       +
           Alcotest.testable

     

       556
       556
       +
             (fun fmt t -> Format.pp_print_string fmt (Error.set_error_type_to_string t))

     

       557
       557
       +
             (=)

     

       558
       558
       +
       

     

       559
       559
       +
         let test_set_error_types () =

     

       560
       560
       +
           let json = read_file "error/valid/set_error_invalid_properties.json" in

     

       561
       561
       +
           match decode Error.set_error_jsont json with

     

       562
       562
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       563
       563
       +
           | Ok err ->

     

       564
       564
       +
               Alcotest.(check set_error_type_testable) "type" Error.Invalid_properties err.Error.type_;

     

       565
       565
       +
               match err.Error.properties with

     

       566
       566
       +
               | None -> Alcotest.fail "expected properties"

     

       567
       567
       +
               | Some props -> Alcotest.(check int) "properties count" 2 (List.length props)

     

       568
       568
       +
       

     

       569
       569
       +
         let tests = [

     

       570
       570
       +
           "valid: method_error", `Quick, test_method_error;

     

       571
       571
       +
           "valid: set_error", `Quick, test_set_error;

     

       572
       572
       +
           "valid: request_error", `Quick, test_request_error;

     

       573
       573
       +
           "valid: set_error forbidden", `Quick, test_set_error_forbidden;

     

       574
       574
       +
           "valid: set_error notFound", `Quick, test_set_error_not_found;

     

       575
       575
       +
           "valid: set_error invalidProperties", `Quick, test_set_error_invalid_properties;

     

       576
       576
       +
           "valid: set_error singleton", `Quick, test_set_error_singleton;

     

       577
       577
       +
           "valid: set_error overQuota", `Quick, test_set_error_over_quota;

     

       578
       578
       +
           "valid: method_error invalidArguments", `Quick, test_method_error_invalid_arguments;

     

       579
       579
       +
           "valid: method_error serverFail", `Quick, test_method_error_server_fail;

     

       580
       580
       +
           "valid: method_error accountNotFound", `Quick, test_method_error_account_not_found;

     

       581
       581
       +
           "valid: method_error forbidden", `Quick, test_method_error_forbidden;

     

       582
       582
       +
           "valid: method_error accountReadOnly", `Quick, test_method_error_account_read_only;

     

       583
       583
       +
           "valid: request_error notJSON", `Quick, test_request_error_not_json;

     

       584
       584
       +
           "valid: request_error limit", `Quick, test_request_error_limit;

     

       585
       585
       +
           "values: method_error", `Quick, test_method_error_values;

     

       586
       586
       +
           "values: set_error types", `Quick, test_set_error_types;

     

       587
       587
       +
         ]

     

       588
       588
       +
       end

     

       589
       589
       +
       

     

       590
       590
       +
       (* Mailbox tests *)

     

       591
       591
       +
       module Mailbox_tests = struct

     

       592
       592
       +
         open Jmap_mail

     

       593
       593
       +
       

     

       594
       594
       +
         let role_testable =

     

       595
       595
       +
           Alcotest.testable

     

       596
       596
       +
             (fun fmt t -> Format.pp_print_string fmt (Mailbox.role_to_string t))

     

       597
       597
       +
             (=)

     

       598
       598
       +
       

     

       599
       599
       +
         let test_simple () =

     

       600
       600
       +
           test_decode_success "simple" Mailbox.jsont "mail/mailbox/valid/simple.json" ()

     

       601
       601
       +
       

     

       602
       602
       +
         let test_nested () =

     

       603
       603
       +
           test_decode_success "nested" Mailbox.jsont "mail/mailbox/valid/nested.json" ()

     

       604
       604
       +
       

     

       605
       605
       +
         let test_values () =

     

       606
       606
       +
           let json = read_file "mail/mailbox/valid/simple.json" in

     

       607
       607
       +
           match decode Mailbox.jsont json with

     

       608
       608
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       609
       609
       +
           | Ok mb ->

     

       610
       610
       +
               Alcotest.(check string) "id" "mb1" (Jmap_proto.Id.to_string (Mailbox.id mb));

     

       611
       611
       +
               Alcotest.(check string) "name" "Inbox" (Mailbox.name mb);

     

       612
       612
       +
               Alcotest.(check (option role_testable)) "role" (Some Mailbox.Inbox) (Mailbox.role mb);

     

       613
       613
       +
               Alcotest.(check int64) "totalEmails" 150L (Mailbox.total_emails mb);

     

       614
       614
       +
               Alcotest.(check int64) "unreadEmails" 5L (Mailbox.unread_emails mb)

     

       615
       615
       +
       

     

       616
       616
       +
         let test_roundtrip () =

     

       617
       617
       +
           test_roundtrip "simple roundtrip" Mailbox.jsont "mail/mailbox/valid/simple.json" ()

     

       618
       618
       +
       

     

       619
       619
       +
         let test_with_all_roles () =

     

       620
       620
       +
           test_decode_success "with all roles" Mailbox.jsont "mail/mailbox/valid/with_all_roles.json" ()

     

       621
       621
       +
       

     

       622
       622
       +
         let test_all_rights_false () =

     

       623
       623
       +
           test_decode_success "all rights false" Mailbox.jsont "mail/mailbox/edge/all_rights_false.json" ()

     

       624
       624
       +
       

     

       625
       625
       +
         let test_roles_values () =

     

       626
       626
       +
           let json = read_file "mail/mailbox/valid/with_all_roles.json" in

     

       627
       627
       +
           match decode Mailbox.jsont json with

     

       628
       628
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       629
       629
       +
           | Ok mb ->

     

       630
       630
       +
               Alcotest.(check (option role_testable)) "role" (Some Mailbox.Archive) (Mailbox.role mb);

     

       631
       631
       +
               Alcotest.(check int64) "totalEmails" 1000L (Mailbox.total_emails mb)

     

       632
       632
       +
       

     

       633
       633
       +
         let tests = [

     

       634
       634
       +
           "valid: simple", `Quick, test_simple;

     

       635
       635
       +
           "valid: nested", `Quick, test_nested;

     

       636
       636
       +
           "valid: with all roles", `Quick, test_with_all_roles;

     

       637
       637
       +
           "edge: all rights false", `Quick, test_all_rights_false;

     

       638
       638
       +
           "values: simple", `Quick, test_values;

     

       639
       639
       +
           "values: roles", `Quick, test_roles_values;

     

       640
       640
       +
           "roundtrip: simple", `Quick, test_roundtrip;

     

       641
       641
       +
         ]

     

       642
       642
       +
       end

     

       643
       643
       +
       

     

       644
       644
       +
       (* Email tests *)

     

       645
       645
       +
       module Email_tests = struct

     

       646
       646
       +
         open Jmap_mail

     

       647
       647
       +
       

     

       648
       648
       +
         let test_minimal () =

     

       649
       649
       +
           test_decode_success "minimal" Email.jsont "mail/email/valid/minimal.json" ()

     

       650
       650
       +
       

     

       651
       651
       +
         let test_full () =

     

       652
       652
       +
           test_decode_success "full" Email.jsont "mail/email/valid/full.json" ()

     

       653
       653
       +
       

     

       654
       654
       +
         let test_with_headers () =

     

       655
       655
       +
           test_decode_success "with_headers" Email.jsont "mail/email/valid/with_headers.json" ()

     

       656
       656
       +
       

     

       657
       657
       +
         let test_minimal_values () =

     

       658
       658
       +
           let json = read_file "mail/email/valid/minimal.json" in

     

       659
       659
       +
           match decode Email.jsont json with

     

       660
       660
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       661
       661
       +
           | Ok email ->

     

       662
       662
       +
               Alcotest.(check string) "id" "e1" (Jmap_proto.Id.to_string (Email.id email));

     

       663
       663
       +
               Alcotest.(check string) "blobId" "blob1" (Jmap_proto.Id.to_string (Email.blob_id email));

     

       664
       664
       +
               Alcotest.(check int64) "size" 1024L (Email.size email)

     

       665
       665
       +
       

     

       666
       666
       +
         let test_full_values () =

     

       667
       667
       +
           let json = read_file "mail/email/valid/full.json" in

     

       668
       668
       +
           match decode Email.jsont json with

     

       669
       669
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       670
       670
       +
           | Ok email ->

     

       671
       671
       +
               Alcotest.(check (option string)) "subject" (Some "Re: Important meeting") (Email.subject email);

     

       672
       672
       +
               Alcotest.(check bool) "hasAttachment" true (Email.has_attachment email);

     

       673
       673
       +
               (* Check from address *)

     

       674
       674
       +
               match Email.from email with

     

       675
       675
       +
               | None -> Alcotest.fail "expected from address"

     

       676
       676
       +
               | Some addrs ->

     

       677
       677
       +
                   Alcotest.(check int) "from count" 1 (List.length addrs);

     

       678
       678
       +
                   let addr = List.hd addrs in

     

       679
       679
       +
                   Alcotest.(check (option string)) "from name" (Some "Alice Smith") (Email_address.name addr);

     

       680
       680
       +
                   Alcotest.(check string) "from email" "alice@example.com" (Email_address.email addr)

     

       681
       681
       +
       

     

       682
       682
       +
         let test_with_keywords () =

     

       683
       683
       +
           test_decode_success "with keywords" Email.jsont "mail/email/valid/with_keywords.json" ()

     

       684
       684
       +
       

     

       685
       685
       +
         let test_multiple_mailboxes () =

     

       686
       686
       +
           test_decode_success "multiple mailboxes" Email.jsont "mail/email/valid/multiple_mailboxes.json" ()

     

       687
       687
       +
       

     

       688
       688
       +
         let test_draft_email () =

     

       689
       689
       +
           test_decode_success "draft email" Email.jsont "mail/email/valid/draft_email.json" ()

     

       690
       690
       +
       

     

       691
       691
       +
         let test_with_all_system_keywords () =

     

       692
       692
       +
           test_decode_success "all system keywords" Email.jsont "mail/email/valid/with_all_system_keywords.json" ()

     

       693
       693
       +
       

     

       694
       694
       +
         let test_empty_keywords () =

     

       695
       695
       +
           test_decode_success "empty keywords" Email.jsont "mail/email/edge/empty_keywords.json" ()

     

       696
       696
       +
       

     

       697
       697
       +
         let test_with_message_ids () =

     

       698
       698
       +
           test_decode_success "with message ids" Email.jsont "mail/email/valid/with_message_ids.json" ()

     

       699
       699
       +
       

     

       700
       700
       +
         let test_keywords_values () =

     

       701
       701
       +
           let json = read_file "mail/email/valid/with_keywords.json" in

     

       702
       702
       +
           match decode Email.jsont json with

     

       703
       703
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       704
       704
       +
           | Ok email ->

     

       705
       705
       +
               let keywords = Email.keywords email in

     

       706
       706
       +
               Alcotest.(check int) "keywords count" 3 (List.length keywords);

     

       707
       707
       +
               Alcotest.(check bool) "$seen present" true (List.mem_assoc "$seen" keywords);

     

       708
       708
       +
               Alcotest.(check bool) "$flagged present" true (List.mem_assoc "$flagged" keywords)

     

       709
       709
       +
       

     

       710
       710
       +
         let test_mailbox_ids_values () =

     

       711
       711
       +
           let json = read_file "mail/email/valid/multiple_mailboxes.json" in

     

       712
       712
       +
           match decode Email.jsont json with

     

       713
       713
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       714
       714
       +
           | Ok email ->

     

       715
       715
       +
               let mailbox_ids = Email.mailbox_ids email in

     

       716
       716
       +
               Alcotest.(check int) "mailboxIds count" 3 (List.length mailbox_ids)

     

       717
       717
       +
       

     

       718
       718
       +
         let tests = [

     

       719
       719
       +
           "valid: minimal", `Quick, test_minimal;

     

       720
       720
       +
           "valid: full", `Quick, test_full;

     

       721
       721
       +
           "valid: with_headers", `Quick, test_with_headers;

     

       722
       722
       +
           "valid: with keywords", `Quick, test_with_keywords;

     

       723
       723
       +
           "valid: multiple mailboxes", `Quick, test_multiple_mailboxes;

     

       724
       724
       +
           "valid: draft email", `Quick, test_draft_email;

     

       725
       725
       +
           "valid: all system keywords", `Quick, test_with_all_system_keywords;

     

       726
       726
       +
           "valid: with message ids", `Quick, test_with_message_ids;

     

       727
       727
       +
           "edge: empty keywords", `Quick, test_empty_keywords;

     

       728
       728
       +
           "values: minimal", `Quick, test_minimal_values;

     

       729
       729
       +
           "values: full", `Quick, test_full_values;

     

       730
       730
       +
           "values: keywords", `Quick, test_keywords_values;

     

       731
       731
       +
           "values: mailboxIds", `Quick, test_mailbox_ids_values;

     

       732
       732
       +
         ]

     

       733
       733
       +
       end

     

       734
       734
       +
       

     

       735
       735
       +
       (* Thread tests *)

     

       736
       736
       +
       module Thread_tests = struct

     

       737
       737
       +
         open Jmap_mail

     

       738
       738
       +
       

     

       739
       739
       +
         let test_simple () =

     

       740
       740
       +
           test_decode_success "simple" Thread.jsont "mail/thread/valid/simple.json" ()

     

       741
       741
       +
       

     

       742
       742
       +
         let test_conversation () =

     

       743
       743
       +
           test_decode_success "conversation" Thread.jsont "mail/thread/valid/conversation.json" ()

     

       744
       744
       +
       

     

       745
       745
       +
         let test_values () =

     

       746
       746
       +
           let json = read_file "mail/thread/valid/conversation.json" in

     

       747
       747
       +
           match decode Thread.jsont json with

     

       748
       748
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       749
       749
       +
           | Ok thread ->

     

       750
       750
       +
               Alcotest.(check string) "id" "t2" (Jmap_proto.Id.to_string (Thread.id thread));

     

       751
       751
       +
               Alcotest.(check int) "emailIds count" 5 (List.length (Thread.email_ids thread))

     

       752
       752
       +
       

     

       753
       753
       +
         let tests = [

     

       754
       754
       +
           "valid: simple", `Quick, test_simple;

     

       755
       755
       +
           "valid: conversation", `Quick, test_conversation;

     

       756
       756
       +
           "values: conversation", `Quick, test_values;

     

       757
       757
       +
         ]

     

       758
       758
       +
       end

     

       759
       759
       +
       

     

       760
       760
       +
       (* Identity tests *)

     

       761
       761
       +
       module Identity_tests = struct

     

       762
       762
       +
         open Jmap_mail

     

       763
       763
       +
       

     

       764
       764
       +
         let test_simple () =

     

       765
       765
       +
           test_decode_success "simple" Identity.jsont "mail/identity/valid/simple.json" ()

     

       766
       766
       +
       

     

       767
       767
       +
         let test_values () =

     

       768
       768
       +
           let json = read_file "mail/identity/valid/simple.json" in

     

       769
       769
       +
           match decode Identity.jsont json with

     

       770
       770
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       771
       771
       +
           | Ok ident ->

     

       772
       772
       +
               Alcotest.(check string) "name" "Work Identity" (Identity.name ident);

     

       773
       773
       +
               Alcotest.(check string) "email" "john.doe@company.com" (Identity.email ident);

     

       774
       774
       +
               Alcotest.(check bool) "mayDelete" true (Identity.may_delete ident)

     

       775
       775
       +
       

     

       776
       776
       +
         let tests = [

     

       777
       777
       +
           "valid: simple", `Quick, test_simple;

     

       778
       778
       +
           "values: simple", `Quick, test_values;

     

       779
       779
       +
         ]

     

       780
       780
       +
       end

     

       781
       781
       +
       

     

       782
       782
       +
       (* Email address tests *)

     

       783
       783
       +
       module Email_address_tests = struct

     

       784
       784
       +
         open Jmap_mail

     

       785
       785
       +
       

     

       786
       786
       +
         let test_full () =

     

       787
       787
       +
           test_decode_success "full" Email_address.jsont "mail/email_address/valid/full.json" ()

     

       788
       788
       +
       

     

       789
       789
       +
         let test_email_only () =

     

       790
       790
       +
           test_decode_success "email_only" Email_address.jsont "mail/email_address/valid/email_only.json" ()

     

       791
       791
       +
       

     

       792
       792
       +
         let test_full_values () =

     

       793
       793
       +
           let json = read_file "mail/email_address/valid/full.json" in

     

       794
       794
       +
           match decode Email_address.jsont json with

     

       795
       795
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       796
       796
       +
           | Ok addr ->

     

       797
       797
       +
               Alcotest.(check (option string)) "name" (Some "John Doe") (Email_address.name addr);

     

       798
       798
       +
               Alcotest.(check string) "email" "john.doe@example.com" (Email_address.email addr)

     

       799
       799
       +
       

     

       800
       800
       +
         let test_email_only_values () =

     

       801
       801
       +
           let json = read_file "mail/email_address/valid/email_only.json" in

     

       802
       802
       +
           match decode Email_address.jsont json with

     

       803
       803
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       804
       804
       +
           | Ok addr ->

     

       805
       805
       +
               Alcotest.(check (option string)) "name" None (Email_address.name addr);

     

       806
       806
       +
               Alcotest.(check string) "email" "anonymous@example.com" (Email_address.email addr)

     

       807
       807
       +
       

     

       808
       808
       +
         let tests = [

     

       809
       809
       +
           "valid: full", `Quick, test_full;

     

       810
       810
       +
           "valid: email_only", `Quick, test_email_only;

     

       811
       811
       +
           "values: full", `Quick, test_full_values;

     

       812
       812
       +
           "values: email_only", `Quick, test_email_only_values;

     

       813
       813
       +
         ]

     

       814
       814
       +
       end

     

       815
       815
       +
       

     

       816
       816
       +
       (* Vacation tests *)

     

       817
       817
       +
       module Vacation_tests = struct

     

       818
       818
       +
         open Jmap_mail

     

       819
       819
       +
       

     

       820
       820
       +
         let test_enabled () =

     

       821
       821
       +
           test_decode_success "enabled" Vacation.jsont "mail/vacation/valid/enabled.json" ()

     

       822
       822
       +
       

     

       823
       823
       +
         let test_disabled () =

     

       824
       824
       +
           test_decode_success "disabled" Vacation.jsont "mail/vacation/valid/disabled.json" ()

     

       825
       825
       +
       

     

       826
       826
       +
         let test_enabled_values () =

     

       827
       827
       +
           let json = read_file "mail/vacation/valid/enabled.json" in

     

       828
       828
       +
           match decode Vacation.jsont json with

     

       829
       829
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       830
       830
       +
           | Ok vac ->

     

       831
       831
       +
               Alcotest.(check bool) "isEnabled" true (Vacation.is_enabled vac);

     

       832
       832
       +
               Alcotest.(check (option string)) "subject" (Some "Out of Office") (Vacation.subject vac)

     

       833
       833
       +
       

     

       834
       834
       +
         let test_disabled_values () =

     

       835
       835
       +
           let json = read_file "mail/vacation/valid/disabled.json" in

     

       836
       836
       +
           match decode Vacation.jsont json with

     

       837
       837
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       838
       838
       +
           | Ok vac ->

     

       839
       839
       +
               Alcotest.(check bool) "isEnabled" false (Vacation.is_enabled vac);

     

       840
       840
       +
               Alcotest.(check (option string)) "subject" None (Vacation.subject vac)

     

       841
       841
       +
       

     

       842
       842
       +
         let tests = [

     

       843
       843
       +
           "valid: enabled", `Quick, test_enabled;

     

       844
       844
       +
           "valid: disabled", `Quick, test_disabled;

     

       845
       845
       +
           "values: enabled", `Quick, test_enabled_values;

     

       846
       846
       +
           "values: disabled", `Quick, test_disabled_values;

     

       847
       847
       +
         ]

     

       848
       848
       +
       end

     

       849
       849
       +
       

     

       850
       850
       +
       (* Comparator tests *)

     

       851
       851
       +
       module Comparator_tests = struct

     

       852
       852
       +
         open Jmap_proto

     

       853
       853
       +
       

     

       854
       854
       +
         let test_minimal () =

     

       855
       855
       +
           test_decode_success "minimal" Filter.comparator_jsont "filter/valid/comparator_minimal.json" ()

     

       856
       856
       +
       

     

       857
       857
       +
         let test_descending () =

     

       858
       858
       +
           test_decode_success "descending" Filter.comparator_jsont "filter/valid/comparator_descending.json" ()

     

       859
       859
       +
       

     

       860
       860
       +
         let test_with_collation () =

     

       861
       861
       +
           test_decode_success "with collation" Filter.comparator_jsont "filter/valid/comparator_with_collation.json" ()

     

       862
       862
       +
       

     

       863
       863
       +
         let test_minimal_values () =

     

       864
       864
       +
           let json = read_file "filter/valid/comparator_minimal.json" in

     

       865
       865
       +
           match decode Filter.comparator_jsont json with

     

       866
       866
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       867
       867
       +
           | Ok comp ->

     

       868
       868
       +
               Alcotest.(check string) "property" "size" (Filter.comparator_property comp);

     

       869
       869
       +
               Alcotest.(check bool) "isAscending" true (Filter.comparator_is_ascending comp);

     

       870
       870
       +
               Alcotest.(check (option string)) "collation" None (Filter.comparator_collation comp)

     

       871
       871
       +
       

     

       872
       872
       +
         let test_collation_values () =

     

       873
       873
       +
           let json = read_file "filter/valid/comparator_with_collation.json" in

     

       874
       874
       +
           match decode Filter.comparator_jsont json with

     

       875
       875
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       876
       876
       +
           | Ok comp ->

     

       877
       877
       +
               Alcotest.(check string) "property" "subject" (Filter.comparator_property comp);

     

       878
       878
       +
               Alcotest.(check (option string)) "collation" (Some "i;unicode-casemap") (Filter.comparator_collation comp)

     

       879
       879
       +
       

     

       880
       880
       +
         let tests = [

     

       881
       881
       +
           "valid: minimal", `Quick, test_minimal;

     

       882
       882
       +
           "valid: descending", `Quick, test_descending;

     

       883
       883
       +
           "valid: with collation", `Quick, test_with_collation;

     

       884
       884
       +
           "values: minimal", `Quick, test_minimal_values;

     

       885
       885
       +
           "values: with collation", `Quick, test_collation_values;

     

       886
       886
       +
         ]

     

       887
       887
       +
       end

     

       888
       888
       +
       

     

       889
       889
       +
       (* EmailBody tests *)

     

       890
       890
       +
       module EmailBody_tests = struct

     

       891
       891
       +
         open Jmap_mail

     

       892
       892
       +
       

     

       893
       893
       +
         let test_text_part () =

     

       894
       894
       +
           test_decode_success "text part" Email_body.Part.jsont "mail/email_body/valid/text_part.json" ()

     

       895
       895
       +
       

     

       896
       896
       +
         let test_multipart () =

     

       897
       897
       +
           test_decode_success "multipart" Email_body.Part.jsont "mail/email_body/valid/multipart.json" ()

     

       898
       898
       +
       

     

       899
       899
       +
         let test_multipart_mixed () =

     

       900
       900
       +
           test_decode_success "multipart mixed" Email_body.Part.jsont "mail/email_body/valid/multipart_mixed.json" ()

     

       901
       901
       +
       

     

       902
       902
       +
         let test_with_inline_image () =

     

       903
       903
       +
           test_decode_success "with inline image" Email_body.Part.jsont "mail/email_body/valid/with_inline_image.json" ()

     

       904
       904
       +
       

     

       905
       905
       +
         let test_with_language () =

     

       906
       906
       +
           test_decode_success "with language" Email_body.Part.jsont "mail/email_body/valid/with_language.json" ()

     

       907
       907
       +
       

     

       908
       908
       +
         let test_deep_nesting () =

     

       909
       909
       +
           test_decode_success "deep nesting" Email_body.Part.jsont "mail/email_body/edge/deep_nesting.json" ()

     

       910
       910
       +
       

     

       911
       911
       +
         let test_multipart_values () =

     

       912
       912
       +
           let json = read_file "mail/email_body/valid/multipart.json" in

     

       913
       913
       +
           match decode Email_body.Part.jsont json with

     

       914
       914
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       915
       915
       +
           | Ok part ->

     

       916
       916
       +
               Alcotest.(check (option string)) "partId" (Some "0") (Email_body.Part.part_id part);

     

       917
       917
       +
               Alcotest.(check string) "type" "multipart/alternative" (Email_body.Part.type_ part);

     

       918
       918
       +
               match Email_body.Part.sub_parts part with

     

       919
       919
       +
               | None -> Alcotest.fail "expected sub_parts"

     

       920
       920
       +
               | Some subs -> Alcotest.(check int) "sub_parts count" 2 (List.length subs)

     

       921
       921
       +
       

     

       922
       922
       +
         let tests = [

     

       923
       923
       +
           "valid: text part", `Quick, test_text_part;

     

       924
       924
       +
           "valid: multipart", `Quick, test_multipart;

     

       925
       925
       +
           "valid: multipart mixed", `Quick, test_multipart_mixed;

     

       926
       926
       +
           "valid: with inline image", `Quick, test_with_inline_image;

     

       927
       927
       +
           "valid: with language", `Quick, test_with_language;

     

       928
       928
       +
           "edge: deep nesting", `Quick, test_deep_nesting;

     

       929
       929
       +
           "values: multipart", `Quick, test_multipart_values;

     

       930
       930
       +
         ]

     

       931
       931
       +
       end

     

       932
       932
       +
       

     

       933
       933
       +
       (* EmailSubmission tests *)

     

       934
       934
       +
       module EmailSubmission_tests = struct

     

       935
       935
       +
         open Jmap_mail

     

       936
       936
       +
       

     

       937
       937
       +
         let test_simple () =

     

       938
       938
       +
           test_decode_success "simple" Submission.jsont "mail/submission/valid/simple.json" ()

     

       939
       939
       +
       

     

       940
       940
       +
         let test_with_envelope () =

     

       941
       941
       +
           test_decode_success "with envelope" Submission.jsont "mail/submission/valid/with_envelope.json" ()

     

       942
       942
       +
       

     

       943
       943
       +
         let test_final_status () =

     

       944
       944
       +
           test_decode_success "final status" Submission.jsont "mail/submission/valid/final_status.json" ()

     

       945
       945
       +
       

     

       946
       946
       +
         let test_simple_values () =

     

       947
       947
       +
           let json = read_file "mail/submission/valid/simple.json" in

     

       948
       948
       +
           match decode Submission.jsont json with

     

       949
       949
       +
           | Error e -> Alcotest.failf "decode failed: %s" (Jsont.Error.to_string e)

     

       950
       950
       +
           | Ok sub ->

     

       951
       951
       +
               Alcotest.(check string) "id" "sub1" (Jmap_proto.Id.to_string (Submission.id sub));

     

       952
       952
       +
               (* Check undoStatus is Pending *)

     

       953
       953
       +
               match Submission.undo_status sub with

     

       954
       954
       +
               | Submission.Pending -> ()

     

       955
       955
       +
               | _ -> Alcotest.fail "expected undoStatus to be pending"

     

       956
       956
       +
       

     

       957
       957
       +
         let tests = [

     

       958
       958
       +
           "valid: simple", `Quick, test_simple;

     

       959
       959
       +
           "valid: with envelope", `Quick, test_with_envelope;

     

       960
       960
       +
           "valid: final status", `Quick, test_final_status;

     

       961
       961
       +
           "values: simple", `Quick, test_simple_values;

     

       962
       962
       +
         ]

     

       963
       963
       +
       end

     

       964
       964
       +
       

     

       965
       965
       +
       (* Run all tests *)

     

       966
       966
       +
       let () =

     

       967
       967
       +
         Alcotest.run "JMAP Proto Codecs" [

     

       968
       968
       +
           "Id", Id_tests.tests;

     

       969
       969
       +
           "Int53", Int53_tests.tests;

     

       970
       970
       +
           "Date", Date_tests.tests;

     

       971
       971
       +
           "Session", Session_tests.tests;

     

       972
       972
       +
           "Request", Request_tests.tests;

     

       973
       973
       +
           "Response", Response_tests.tests;

     

       974
       974
       +
           "Invocation", Invocation_tests.tests;

     

       975
       975
       +
           "Capability", Capability_tests.tests;

     

       976
       976
       +
           "Method", Method_tests.tests;

     

       977
       977
       +
           "Error", Error_tests.tests;

     

       978
       978
       +
           "Comparator", Comparator_tests.tests;

     

       979
       979
       +
           "Mailbox", Mailbox_tests.tests;

     

       980
       980
       +
           "Email", Email_tests.tests;

     

       981
       981
       +
           "EmailBody", EmailBody_tests.tests;

     

       982
       982
       +
           "Thread", Thread_tests.tests;

     

       983
       983
       +
           "Identity", Identity_tests.tests;

     

       984
       984
       +
           "Email_address", Email_address_tests.tests;

     

       985
       985
       +
           "EmailSubmission", EmailSubmission_tests.tests;

     

       986
       986
       +
           "Vacation", Vacation_tests.tests;

     

       987
       987
       +
         ]

Compare changes