README.md — sigil-jmap

1# sigil-jmap

A [Sigil](https://codeberg.org/sigil/sigil) library for JMAP email (RFC 8620/8621). Works with Fastmail, Stalwart, Cyrus, Apache James, and other JMAP-compatible servers.

5## Features

7- **Session discovery** -- Bearer token or Basic auth, automatic capability detection

8- **Mailbox operations** -- list, find by role/name, create, update, delete

9- **Email querying** -- filter by mailbox, sort, paginate with back-referenced query+get

10- **Email retrieval** -- single or batch with full body content

11- **Email mutations** -- move between mailboxes, set/remove keywords, delete

12- **Email sending** -- with identity selection, to/cc/bcc, text and HTML bodies

13- **Blob download** -- fetch attachments via template URL expansion

14- **Error handling** -- JMAP-level error type checking

16## Usage

18Add `sigil-jmap` as a dependency in your `package.sgl`:

20```scheme

21(from-git url: "codeberg:sigil/sigil-jmap" package: "sigil-jmap")

22```

24Then connect and query email:

26```scheme

27(import (sigil jmap))

29(define session (jmap-connect

30 url: "https://api.fastmail.com/jmap/session"

31 token: (getenv "JMAP_TOKEN")))

33;; List mailboxes

34(define mailboxes (jmap-mailboxes session))

36;; Find inbox

37(define inbox (jmap-mailbox-by-role session "inbox"))

39;; Query recent emails

40(define emails (jmap-email-query session

41 mailbox-id: (jmap-mailbox-id inbox)

42 limit: 10))

43```

45## Modules

47| Module | Description |

48|--------|-------------|

49| `(sigil jmap)` | Top-level re-exports |

50| `(sigil jmap client)` | Session discovery, JMAP request/response handling |

51| `(sigil jmap mailbox)` | Mailbox CRUD operations |

52| `(sigil jmap email)` | Email query, get, update, move, delete |

53| `(sigil jmap send)` | Identity listing and email submission |

55## Dependencies

57- sigil-stdlib

58- sigil-json

59- sigil-http

61## Building

63```bash

64sigil deps install

65sigil build

66sigil test

67```

69## License

71BSD-3-Clause