anil.recoil.org
this repo has no description
Add README with library overview and usage instructions
This adds a comprehensive README.md that describes the library, including:
- Overview of features
- Installation instructions
- Quick start example code
- Documentation information
- References to specifications
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
+151
+151
README.md
+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/)