Address

Address = 1 inbox di salah satu domain layanan kamu. Model Mailinator: address bersifat permanen — tidak ada TTL yang membuatnya kedaluwarsa.

> Field expiresAt selalu berisi tanggal far-future (~10 tahun) dan ttlSeconds selalu 0. Keduanya dipertahankan untuk kompatibilitas, bukan janji kedaluwarsa. Body ttlSeconds saat create diabaikan. Untuk berhenti menerima email, hapus address-nya.

List address

GET /v1/services/:id/addresses

Auth: API key (read) atau JWT. :id = ID layanan.

Query params (semua opsional):

curl -H "X-API-Key: clk_live_xxx" \
  "https://api.cloudin.id/v1/services/SVC_ID/addresses?limit=20"

Response:

{
  "data": [
    {
      "id": "01HXY...",
      "domainId": "01HXY...",
      "hostname": "inbox.brandkamu.id",
      "localPart": "abc12",
      "fullAddress": "abc12@inbox.brandkamu.id",
      "hasPassword": false,
      "ttlSeconds": 0,
      "expiresAt": "2036-05-28T08:00:00.000Z",
      "lastMessageAt": null,
      "messageCount": 0,
      "createdAt": "2026-05-28T08:00:00.000Z"
    }
  ],
  "meta": { "cursor": "MDFIWFku...", "hasMore": true }
}

Generate address

POST /v1/services/:id/addresses

Auth: API key (write) atau JWT.

Body (application/json):

curl -X POST https://api.cloudin.id/v1/services/SVC_ID/addresses \
  -H "X-API-Key: clk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "DOMAIN_ID",
    "localPart": "signup-bot"
  }'

Response 201:

{
  "data": {
    "id": "01HXY...",
    "domainId": "01HXY...",
    "localPart": "signup-bot",
    "fullAddress": "signup-bot@inbox.brandkamu.id",
    "hasPassword": false,
    "ttlSeconds": 0,
    "expiresAt": "2036-05-28T08:00:00.000Z",
    "createdAt": "2026-05-28T08:00:00.000Z"
  }
}

Membuat address memicu event webhook address.created.

Perpanjang address

POST /v1/addresses/:id/extend

Auth: JWT saja (tidak ada di allow-list API key). Karena address permanen, endpoint ini hanya mendorong expiresAt lebih jauh; tidak diperlukan dalam alur integrator biasa. Tidak ada body — perpanjangan sebesar 600 detik dari waktu sekarang diterapkan pada level far-future.

Response:

{ "data": { "expiresAt": "2036-05-28T08:10:00.000Z" } }

Hapus address

DELETE /v1/addresses/:id

Auth: JWT saja. Menghapus address dan seluruh pesannya. Response 204 No Content (tanpa body).

> Endpoint extend dan delete di atas tidak ada di allow-list API key — dipanggil dari dashboard (JWT). Untuk mengelola inbox lewat API key, generate address baru dan hapus lewat dashboard bila perlu.