Premium API Documentation

API khusus owner premium untuk inbox private + OTP automation.

Konsep Keamanan

1. Tiap owner punya API key sendiri (header X-Owner-API-Key).

2. API key hanya boleh akses inbox private buyer yang dimiliki owner itu.

3. Jika domain/buyer milik A diakses pakai API key milik B, hasilnya 403 Forbidden.

4. Jika owner expired / nonaktif, API key owner otomatis tidak valid.

Flow Singkat

  1. Owner login ke /owner.
  2. Tambah domain private dan pastikan status active.
  3. Generate buyer (email + PIN).
  4. Buat API Key Premium di dashboard owner.
  5. Pakai API key itu untuk baca inbox/OTP buyer via endpoint premium.
GET /api/premium/emails/:address

Ambil daftar email inbox private buyer.

Header wajib: X-Owner-API-Key: your-owner-api-key

Query optional: ?limit=50

curl -H "X-Owner-API-Key: your-owner-api-key" \
  "https://emailqu.com/api/premium/emails/abc@canvamail.com?limit=20"
GET /api/premium/emails/:address/latest

Ambil email terbaru inbox private buyer.

curl -H "X-Owner-API-Key: your-owner-api-key" \
  "https://emailqu.com/api/premium/emails/abc@canvamail.com/latest"
GET /api/premium/otp/:address/latest

Ambil OTP terbaru (auto extract angka 4-8 digit) dari email terbaru.

curl -H "X-Owner-API-Key: your-owner-api-key" \
  "https://emailqu.com/api/premium/otp/abc@canvamail.com/latest"

Manage Owner API Key

Endpoint ini dipakai dari owner dashboard / backend owner (butuh owner token Bearer).

GET /api/owner/api-keys - list key owner

POST /api/owner/api-keys - create key baru

DELETE /api/owner/api-keys/:id - revoke key

curl -X POST "https://emailqu.com/api/owner/api-keys" \
  -H "Authorization: Bearer owner_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"primary","duration_days":90}'

Contoh Isolasi A vs B

# buyer milik owner A
GET /api/premium/emails/abc@canvamail.com
X-Owner-API-Key: key_owner_B

Response:

{
  "error": "This private inbox is not accessible by provided API key"
}
# HTTP 403

HTTP Status

Code Arti
200 Berhasil
401 Header API key owner tidak ada / invalid token owner
403 Inbox private tidak boleh diakses key tersebut (A vs B), atau key expired
404 Data key tidak ditemukan (pada revoke/list tertentu)
500 Server error