API Dokumentasi

Dokumentasi REST API AstroMail. Menggunakan format JSON-LD + Hydra. Semua respons berformat application/ld+json.

Format
JSON-LD / Hydra
Auth
Bearer JWT (HS256)
Retensi
2 jam

Autentikasi

Endpoint privat memerlukan header:

Authorization: Bearer <JWT_TOKEN>

Dapatkan token via POST /token. Token berlaku 7 hari.

Format Error

Setiap error mengembalikan HTTP status yang sesuai + body:

{
  "@context": "/contexts/Error",
  "@type": "hydra:Error",
  "status": 401,
  "title": "Unauthorized",
  "hydra:title": "Unauthorized",
  "hydra:description": ""
}
Code Arti
400 Body / JSON tidak valid
401 Token hilang / kadaluarsa
403 Bukan pemilik resource
404 Resource tidak ditemukan
422 Validasi gagal (address/domain/password)
500 Kesalahan internal

Rate Limit

Mengikuti default Cloudflare Workers per zone/IP. Untuk pemakaian API publik, batasi polling ≥ 4 detik. Cleanup otomatis menghapus pesan > 2 jam tiap 10 menit.

Domains

GET /domains Public

Daftar domain yang tersedia untuk membuat alamat.

curl {{BASE}}/domains
▶ Contoh respons 
{
  "@context": "/contexts/Domain",
  "@id": "/domains",
  "@type": "hydra:Collection",
  "hydra:totalItems": 2,
  "hydra:member": [
    { "@id":"/domains/dom_abc", "id":"dom_abc", "domain":"astromail.web.id", "isActive":true, "isPrivate":false },
    { "@id":"/domains/dom_xyz", "id":"dom_xyz", "domain":"mailru.web.id", "isActive":true, "isPrivate":false }
  ]
}
GET /domains/{id} Public

Detail satu domain.

curl {{BASE}}/domains/dom_edu

Accounts

POST /accounts Public

Buat akun baru dengan alamat pada salah satu domain aktif.

Body 
{
  "address": "yourname@astromail.web.id",
  "password": "min-6-char"
}
cURL 
curl -X POST {{BASE}}/accounts \
  -H "content-type: application/json" \
  -d '{"address":"yourname@astromail.web.id","password":"secret123"}'
JS Fetch 
await fetch("{{BASE}}/accounts", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ address, password })
}).then(r => r.json());
GET /accounts/{id} Auth

Info akun (hanya pemilik).

DELETE /accounts/{id} Auth

Soft-delete akun. Menerima 204 No Content.

Token

POST /token Public

Login → JWT (berlaku 7 hari).

curl -X POST {{BASE}}/token \
  -H "content-type: application/json" \
  -d '{"address":"yourname@astromail.web.id","password":"secret123"}'
{ "token": "eyJhbGciOi...", "id": "acc_xxxx" }

Me

GET /me Auth

Kembalikan akun pemilik token.

curl {{BASE}}/me -H "authorization: Bearer $TOKEN"

Messages

GET /messages?page=1 Auth

Daftar pesan inbox. Paginasi page default 1, 30 per halaman.

curl "{{BASE}}/messages?page=1" -H "authorization: Bearer $TOKEN"
▶ Contoh respons 
{
  "@context":"/contexts/Message",
  "@id":"/messages",
  "@type":"hydra:Collection",
  "hydra:totalItems": 1,
  "hydra:member":[
    {
      "@id":"/messages/msg_...",
      "id":"msg_...",
      "from":{"address":"noreply@github.com","name":"GitHub"},
      "to":[{"address":"yourname@astromail.web.id","name":""}],
      "subject":"Verifikasi email",
      "intro":"Hi, klik tautan berikut untuk memverifikasi...",
      "seen":false,
      "hasAttachments":false,
      "size":4820,
      "createdAt":"2026-07-10T19:00:00.000Z"
    }
  ]
}
GET /messages/{id} Auth

Detail pesan lengkap (body text, html, attachments). Otomatis di-mark seen.

PATCH /messages/{id} Auth

Ubah flag seen atau flagged.

curl -X PATCH {{BASE}}/messages/msg_xxx \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"seen":true,"flagged":false}'
DELETE /messages/{id} Auth

Hapus pesan. 204 No Content.

Playground

Coba request langsung dari browser. Token disimpan di localStorage.

Response 
—