commit 28dc8f46627e6d864425d12614e07f563b685ca9 · anil.recoil.org/ocaml-jmap

+151

README.md

···

       1
       +
       # JMAP OCaml Client

     

       2
       +
       

     

       3
       +
       A type-safe OCaml interface to the JMAP protocol ([RFC8620](https://datatracker.ietf.org/doc/html/rfc8620)) and JMAP Mail extension ([RFC8621](https://datatracker.ietf.org/doc/html/rfc8621)).

     

       4
       +
       

     

       5
       +
       **Note:** This library is largely AI-generated and has not been audited carefully. It's a proof-of-concept implementation of the JMAP specification.

     

       6
       +
       

     

       7
       +
       ## Overview

     

       8
       +
       

     

       9
       +
       JMAP (JSON Meta Application Protocol) is a modern protocol for synchronizing email, calendars, and contacts designed as a replacement for legacy protocols like IMAP. This OCaml implementation provides:

     

       10
       +
       

     

       11
       +
       - Type-safe OCaml interfaces to the JMAP Core and Mail specifications

     

       12
       +
       - Authentication with username/password or API tokens (Fastmail support)

     

       13
       +
       - Convenient functions for common email and mailbox operations

     

       14
       +
       - Support for composing complex multi-part requests with result references

     

       15
       +
       - Typed handling of message flags, keywords, and mailbox attributes

     

       16
       +
       

     

       17
       +
       ## Installation

     

       18
       +
       

     

       19
       +
       Add to your project with opam:

     

       20
       +
       

     

       21
       +
       ```

     

       22
       +
       opam install jmap

     

       23
       +
       ```

     

       24
       +
       

     

       25
       +
       Or pin the development version:

     

       26
       +
       

     

       27
       +
       ```

     

       28
       +
       opam pin add jmap.dev git+https://github.com/example/jmap-ocaml.git

     

       29
       +
       ```

     

       30
       +
       

     

       31
       +
       ## Quick Start

     

       32
       +
       

     

       33
       +
       ```ocaml

     

       34
       +
       open Lwt.Syntax

     

       35
       +
       open Jmap

     

       36
       +
       open Jmap_mail

     

       37
       +
       

     

       38
       +
       (* Authentication *)

     

       39
       +
       let token = Sys.getenv "JMAP_API_TOKEN" in

     

       40
       +
       let* result = Jmap_mail.login_with_token 

     

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

     

       42
       +
         ~api_token:token

     

       43
       +
       in

     

       44
       +
       

     

       45
       +
       match result with

     

       46
       +
       | Error err -> 

     

       47
       +
           Printf.eprintf "Authentication failed\n";

     

       48
       +
           exit 1

     

       49
       +
           

     

       50
       +
       | Ok conn ->

     

       51
       +
           (* Get primary account ID *)

     

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

     

       53
       +
           let account_id = List.assoc mail_capability conn.session.primary_accounts in

     

       54
       +
           

     

       55
       +
           (* Get mailboxes *)

     

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

     

       57
       +
           

     

       58
       +
           match mailboxes_result with

     

       59
       +
           | Error err -> 

     

       60
       +
               Printf.eprintf "Failed to get mailboxes\n";

     

       61
       +
               exit 1

     

       62
       +
               

     

       63
       +
           | Ok mailboxes ->

     

       64
       +
               (* Find the inbox *)

     

       65
       +
               let inbox = List.find_opt (fun m -> 

     

       66
       +
                 m.Types.role = Some Types.Inbox

     

       67
       +
               ) mailboxes in

     

       68
       +
               

     

       69
       +
               match inbox with

     

       70
       +
               | None -> 

     

       71
       +
                   Printf.eprintf "No inbox found\n";

     

       72
       +
                   exit 1

     

       73
       +
                   

     

       74
       +
               | Some inbox ->

     

       75
       +
                   (* Get recent emails *)

     

       76
       +
                   let* emails_result = Jmap_mail.get_messages_in_mailbox

     

       77
       +
                     conn

     

       78
       +
                     ~account_id

     

       79
       +
                     ~mailbox_id:inbox.Types.id

     

       80
       +
                     ~limit:10

     

       81
       +
                     ()

     

       82
       +
                   in

     

       83
       +
                   

     

       84
       +
                   match emails_result with

     

       85
       +
                   | Error err -> 

     

       86
       +
                       Printf.eprintf "Failed to get emails\n";

     

       87
       +
                       exit 1

     

       88
       +
                       

     

       89
       +
                   | Ok emails ->

     

       90
       +
                       (* Display emails *)

     

       91
       +
                       List.iter (fun email ->

     

       92
       +
                         Printf.printf "%s - %s\n" 

     

       93
       +
                           (Option.value ~default:"<unknown>" 

     

       94
       +
                             (Option.map (fun addrs -> 

     

       95
       +
                               match addrs with

     

       96
       +
                               | [] -> "<unknown>"

     

       97
       +
                               | addr::_ -> addr.Types.email

     

       98
       +
                             ) email.Types.from))

     

       99
       +
                           (Option.value ~default:"<no subject>" email.Types.subject)

     

       100
       +
                       ) emails;

     

       101
       +
                       

     

       102
       +
                       Lwt.return_unit

     

       103
       +
       ```

     

       104
       +
       

     

       105
       +
       ## Features

     

       106
       +
       

     

       107
       +
       - **Core JMAP Protocol**

     

       108
       +
         - Session handling

     

       109
       +
         - API request/response management

     

       110
       +
         - Type-safe representation of all JMAP structures

     

       111
       +
         - Result references for composing multi-step requests

     

       112
       +
       

     

       113
       +
       - **JMAP Mail Extension**

     

       114
       +
         - Mailbox operations (folders/labels)

     

       115
       +
         - Email retrieval and manipulation

     

       116
       +
         - Thread handling

     

       117
       +
         - Identity management

     

       118
       +
         - Email submission

     

       119
       +
         - Message flags and keywords

     

       120
       +
       

     

       121
       +
       - **Fastmail Integration**

     

       122
       +
         - API token authentication

     

       123
       +
         - Example tools for listing messages

     

       124
       +
       

     

       125
       +
       ## Documentation

     

       126
       +
       

     

       127
       +
       The library includes comprehensive OCamldoc documentation with cross-references to the relevant sections of the JMAP specifications.

     

       128
       +
       

     

       129
       +
       Build the documentation with:

     

       130
       +
       

     

       131
       +
       ```

     

       132
       +
       dune build @doc

     

       133
       +
       ```

     

       134
       +
       

     

       135
       +
       ## Example Tools

     

       136
       +
       

     

       137
       +
       The package includes several example tools:

     

       138
       +
       

     

       139
       +
       - `fastmail-list`: Lists emails from a Fastmail account (requires JMAP_API_TOKEN)

     

       140
       +
       - `jmap-tutorial-examples`: Demonstrates basic JMAP operations as shown in the tutorial

     

       141
       +
       

     

       142
       +
       ## License

     

       143
       +
       

     

       144
       +
       [MIT License](LICENSE)

     

       145
       +
       

     

       146
       +
       ## References

     

       147
       +
       

     

       148
       +
       - [RFC8620: The JSON Meta Application Protocol (JMAP)](https://datatracker.ietf.org/doc/html/rfc8620)

     

       149
       +
       - [RFC8621: The JSON Meta Application Protocol (JMAP) for Mail](https://datatracker.ietf.org/doc/html/rfc8621)

     

       150
       +
       - [Message Flag and Mailbox Attribute Extension](https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute-02)

     

       151
       +
       - [Fastmail Developer Documentation](https://www.fastmail.com/dev/)