https://github.com/valerius21/sakura-mail
E-Mail REST/JSON API for your inbox.
https://github.com/valerius21/sakura-mail
email imap imap-client ocaml rest-api
Last synced: 22 days ago
JSON representation
E-Mail REST/JSON API for your inbox.
- Host: GitHub
- URL: https://github.com/valerius21/sakura-mail
- Owner: valerius21
- License: agpl-3.0
- Created: 2026-04-05T10:18:28.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-04-05T10:25:00.000Z (3 months ago)
- Last Synced: 2026-04-05T12:14:06.414Z (3 months ago)
- Topics: email, imap, imap-client, ocaml, rest-api
- Language: OCaml
- Homepage:
- Size: 66.4 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# sakura-mail
HTTP API for email, built on OCaml. Wraps [mbsync](https://isync.sourceforge.io/mbsync.html) for IMAP synchronization and stores mail locally in Maildir format.
Tests and docs/openapi.json are AI generated.
## TODO
- [ ] Sending Mails
- [ ] Queueing Mails
## Prerequisites
- OCaml 5.x with opam
- [mbsync](https://isync.sourceforge.io/mbsync.html) (isync)
- Docker (for test IMAP server)
- Node.js (for test seed script)
## Install dependencies
```sh
opam install . --deps-only
```
## Run
```sh
make run
```
Starts on `http://localhost:8080`. Configure with environment variables:
| Variable | Default | Description |
|---|---|---|
| `SAKURA_PORT` | `8080` | HTTP port |
| `SAKURA_MAILDIR` | `~/.sakura-mail` | Data directory |
## API
All endpoints except `POST /accounts` require `Authorization: Bearer sk_...`.
```sh
# Register an account (returns id + api_key)
curl -X POST http://localhost:8080/accounts \
-H 'Content-Type: application/json' \
-d '{"host":"imap.example.com","port":993,"username":"you","password":"pass","use_tls":true}'
# Sync mail from IMAP server
curl -X POST http://localhost:8080/sync -H 'Authorization: Bearer sk_...'
# List mailboxes
curl http://localhost:8080/mailboxes -H 'Authorization: Bearer sk_...'
# List messages (paginated)
curl 'http://localhost:8080/mailboxes/INBOX/messages?limit=20&offset=0' \
-H 'Authorization: Bearer sk_...'
# Read a message
curl http://localhost:8080/messages/{id} -H 'Authorization: Bearer sk_...'
# Read raw RFC 5322 content
curl http://localhost:8080/messages/{id}/raw -H 'Authorization: Bearer sk_...'
# Set flags
curl -X PUT http://localhost:8080/messages/{id}/flags \
-H 'Authorization: Bearer sk_...' \
-H 'Content-Type: application/json' \
-d '{"flags":["Seen","Flagged"]}'
# Move message
curl -X POST http://localhost:8080/messages/{id}/move \
-H 'Authorization: Bearer sk_...' \
-H 'Content-Type: application/json' \
-d '{"destination":"Archive"}'
# Delete (move to Trash)
curl -X DELETE http://localhost:8080/messages/{id} -H 'Authorization: Bearer sk_...'
# Create draft
curl -X POST http://localhost:8080/drafts \
-H 'Authorization: Bearer sk_...' \
-H 'Content-Type: application/json' \
-d '{"to":["alice@example.com"],"cc":[],"bcc":[],"subject":"Hello","body":"Hi there","in_reply_to":null}'
# Delete account
curl -X DELETE http://localhost:8080/accounts -H 'Authorization: Bearer sk_...'
```
## Test
```sh
make test # unit + e2e tests (83 total)
make greenmail-up # start test IMAP server
make seed # seed test emails
```
## Project structure
```
bin/ Entry point
lib/
account/ User registration, API keys, persistence
api/ Dream HTTP routes
email/ RFC 5322 parsing (mrmime) and draft generation
imap/ mbsync CLI wrapper and .mbsyncrc generation
maildir/ Maildir filesystem operations
sync/ Background sync scheduler with per-user locking
test/
seed/ Node.js script to seed test emails via SMTP
```