PBS Mail Partner API v1

Dokumentasi API Partner

Halaman ini menjelaskan cara memakai Partner API untuk membuat alias email sementara, membaca pesan milik alias tersebut, dan mengambil OTP. Halaman ini publik dan tidak memerlukan login admin.

Ringkasnya

Gunakan header x-api-key.
Scope menentukan akses endpoint.
Alias hanya bisa diakses oleh API key pemiliknya.
OTP bisa dipolling sampai batas waktu.

1. Autentikasi

Header API Key

Semua request ke endpoint partner harus menyertakan API key pada header berikut:

x-api-key: tpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API key hanya ditampilkan sekali saat dibuat atau di-rotate.
Jika key kadaluarsa atau dicabut, semua request akan ditolak.
Beberapa key bisa dibatasi berdasarkan domain, IP, scope, dan rate limit.
Jika field domain tidak dikirim saat create alias, server akan memilih domain aktif yang diizinkan oleh API key.
Untuk integrasi API key, gunakan endpoint /api/v1/partner/*, bukan endpoint publik lama /api/aliases.

2. Scope

Hak akses yang tersedia

alias:create

Mengizinkan create alias baru melalui endpoint /aliases.

messages:read

Mengizinkan baca daftar pesan dan detail pesan.

otp:read

Mengizinkan polling OTP terbaru dari pesan alias.

3. Endpoint

Daftar endpoint partner

Method	Path	Fungsi
POST	`/api/v1/partner/aliases`	Buat alias email baru untuk API key yang sedang aktif.
GET	`/api/v1/partner/messages?alias=nama@domain.com`	Ambil daftar pesan untuk alias yang dimiliki API key.
GET	`/api/v1/partner/messages/:id?alias=nama@domain.com`	Ambil detail satu pesan untuk alias yang dimiliki API key.
GET	`/api/v1/partner/otp?alias=nama@domain.com&waitSeconds=20`	Polling OTP terbaru untuk alias tertentu.
GET	`/api/v1/partner/health`	Cek status API key, scope, dan rate limit yang tersisa.

4. Alur Pakai

Flow integrasi yang disarankan

Admin membuat API key dari dashboard admin.
Partner memanggil endpoint create alias untuk membuat alamat email sementara.
Partner memanggil endpoint messages untuk membaca inbox alias tersebut.
Jika email berisi OTP, partner memanggil endpoint otp dan menunggu sampai kode ditemukan.

5. Contoh Integrasi

Contoh di beberapa bahasa umum

JavaScript / Node.js

const res = await fetch('https://your-domain.com/api/v1/partner/aliases', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PBS_API_KEY,
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    localPart: 'demo123',
    ttlMinutes: 60,
    reference: 'order-001'
  })
});

const data = await res.json();

Python

import requests

res = requests.post(
    'https://your-domain.com/api/v1/partner/aliases',
    headers={'x-api-key': 'tpk_xxx'},
    json={'localPart': 'demo123', 'ttlMinutes': 60}
)
data = res.json()

PHP

$client = new GuzzleHttpClient();
$res = $client->post('https://your-domain.com/api/v1/partner/aliases', [
  'headers' => ['x-api-key' => 'tpk_xxx'],
  'json' => ['localPart' => 'demo123', 'ttlMinutes' => 60],
]);
$data = json_decode((string) $res->getBody(), true);

req, _ := http.NewRequest(http.MethodPost, "https://your-domain.com/api/v1/partner/aliases", strings.NewReader(body))
req.Header.Set("x-api-key", os.Getenv("PBS_API_KEY"))
req.Header.Set("content-type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

6. Benar vs Salah

Cara pakai yang disarankan

Benar

Kirim hanya localPart saat domain tidak perlu dipaksa.
Biarkan server memilih domain aktif jika key tidak dibatasi domain.
Cek endpoint /health saat integrasi baru.
Gunakan alias yang sudah dikembalikan oleh server untuk request berikutnya.

Salah

Mengirim address penuh dengan domain yang tidak aktif.
Mengubah domain sendiri tanpa memastikan domain itu aktif di PBS.
Menganggap semua domain bebas jika API key dibatasi domain.
Menebak format OTP tanpa membaca response dari server.

Contoh 1

Buat alias

curl -X POST https://your-domain.com/api/v1/partner/aliases   -H "x-api-key: tpk_xxx"   -H "content-type: application/json"   -d '{
    "localPart": "demo123",
    "ttlMinutes": 60,
    "reference": "partner-order-001"
  }'

Kalau domain tidak perlu dipaksa, jangan kirim field domain. Server akan memilih domain aktif yang cocok untuk API key.

Contoh 2

Ambil OTP

GET /api/v1/partner/otp?alias=demo123@pbsmailer.tech&waitSeconds=20

Parameter waitSeconds bersifat opsional. Jika diisi, API akan polling sampai kode ditemukan atau batas waktu habis.

Catatan Penting

Endpoint messages dan otp hanya bisa membaca alias yang dimiliki API key tersebut.
Rate limit dihitung per API key.
Gunakan scope sekecil mungkin untuk kebutuhan integrasi.
Rotasi API key lama setelah key baru aktif.

Contoh Respons

Health check

{
  "ok": true,
  "partnerApiEnabled": true,
  "rateLimit": {
    "limitPerMin": 60,
    "remaining": 58,
    "resetAt": "2026-04-21T10:30:00.000Z"
  }
}