Postivo API & SMTP Relay

Pengenalan

Postivo adalah layanan email transaksional: OTP, reset password, invoice, notifikasi. Anda mengirim lewat REST API atau SMTP; Postivo memvalidasi, mengantrekan, menandatangani DKIM, mengirim lewat relay, lalu melaporkan setiap perubahan status.

REST / SMTP → validasi (domain, kuota, suppression) → antrean → tanda tangan DKIM → relay (Stalwart; fallback Brevo bila gangguan sementara) → event: queued · sent · delivered · bounced · complained

• Satu pintu masuk. REST dan SMTP memakai aturan validasi yang sama, sehingga hasilnya konsisten.
• Satu email, banyak penerima. Setiap penerima punya status sendiri (dispatch) dan timeline sendiri.
• Aman bagi OTP. Open/click tracking mati secara bawaan agar link verifikasi tidak ditulis ulang.

Quickstart 5 menit

1. Buat akun dan verifikasi email Anda.
2. Buka Domains → tambahkan domain pengirim (disarankan subdomain, mis. mail.contoh.com).
3. Pasang lima record DNS di penyedia DNS Anda, lalu klik Verifikasi sampai status Active.
4. Buka API Keys → buat key live dengan scope emails:send. Salin — hanya tampil sekali.
5. Kirim email pertama:

curl https://api.postivo.my.id/v1/emails \
  -H "Authorization: Bearer $POSTIVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Kode verifikasi Anda",
    "html": "<p>Kode: <b>123456</b></p>",
    "text": "Kode: 123456"
  }'

const res = await fetch('https://api.postivo.my.id/v1/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTIVO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'Acme <[email protected]>',
    to: ['[email protected]'],
    subject: 'Kode verifikasi Anda',
    html: '<p>Kode: <b>123456</b></p>',
    text: 'Kode: 123456',
  }),
});
console.log(res.status, await res.json()); // 202

$res = Http::withToken(env('POSTIVO_API_KEY'))
    ->post('https://api.postivo.my.id/v1/emails', [
        'from'    => 'Acme <[email protected]>',
        'to'      => ['[email protected]'],
        'subject' => 'Kode verifikasi Anda',
        'html'    => '<p>Kode: <b>123456</b></p>',
        'text'    => 'Kode: 123456',
    ]);
$res->status(); // 202

import os, requests

r = requests.post(
    "https://api.postivo.my.id/v1/emails",
    headers={"Authorization": f"Bearer {os.environ['POSTIVO_API_KEY']}"},
    json={
        "from": "Acme <[email protected]>",
        "to": ["[email protected]"],
        "subject": "Kode verifikasi Anda",
        "html": "<p>Kode: <b>123456</b></p>",
        "text": "Kode: 123456",
    },
)
print(r.status_code, r.json())  # 202

Respons 202 Accepted berarti email sudah divalidasi dan masuk antrean — bukan berarti sudah terkirim. Pantau statusnya di Emails atau lewat webhook.

{
  "id": "0192f3a0-7c1e-7b3a-9d4e-5a1f0c2b8e11",
  "status": "queued",
  "created_at": "2026-10-27T08:15:30Z",
  "recipients": [
    { "email": "[email protected]", "dispatch_id": "0192f3a0-7c20-7d11-8a2b-1c3d4e5f6a7b", "status": "QUEUED" }
  ]
}

Autentikasi & API key

Kirim API key di header Authorization: Bearer psv_live_…. Format key: psv_{live|test}_ + 32 karakter. Key disimpan sebagai hash — Postivo tidak bisa menampilkannya lagi, jadi simpan di secret manager, bukan di kode.

{ "error": { "code": "unauthenticated", "message": "Invalid or missing API key.", "request_id": "9b2c…" } }

Menambah domain

Email hanya bisa dikirim dari domain milik organisasi Anda yang berstatus Active. Domain diambil dari alamat pada header From.

• Lewat console: Domains → Tambah. Lewat API: POST /v1/domains (scope domains:manage).
• Gunakan subdomain khusus (mis. mail.contoh.com) agar reputasi pengiriman transaksional terpisah dari domain utama.
• Postivo membuat pasangan kunci DKIM RSA-2048 per domain. Kunci privat disimpan terenkripsi dan tidak pernah ditampilkan.

curl https://api.postivo.my.id/v1/domains \
  -H "Authorization: Bearer $POSTIVO_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain":"mail.contoh.com"}'

Lima record DNS

Pasang record berikut di penyedia DNS domain Anda (Cloudflare, Niagahoster, dsb.). Nilai persisnya tampil di halaman domain — tombol salin tersedia.

Verifikasi & status domain

Klik Verifikasi sekarang di console atau panggil POST /v1/domains/{id}/verify. Postivo juga mengaudit ulang semua domain otomatis setiap 15 menit.

Gangguan resolver DNS tidak dihitung sebagai record gagal: status record terakhir dipertahankan sampai pengecekan berikutnya berhasil.

Troubleshooting DNS

• Record sudah dipasang tapi belum terdeteksi — propagasi bisa sampai beberapa jam. Kolom “Terdeteksi” di halaman domain menampilkan apa yang benar-benar terbaca.
• Penyedia DNS menambahkan domain otomatis — banyak panel menambahkan .{domain} sendiri. Jika host Anda menjadi postivo._domainkey.mail.contoh.com.mail.contoh.com, isi hanya bagian depan (postivo._domainkey).
• Nilai DKIM terpotong — kunci publik panjang; sebagian panel meminta nilai dipecah dalam tanda kutip. Hasil akhirnya harus tetap satu string utuh.
• CNAME tidak bisa di apex — itulah alasan disarankan memakai subdomain.
• Cloudflare — set record CNAME ke DNS only (awan abu-abu), bukan proxied.

POST /v1/emails

Mengirim satu email ke satu atau beberapa penerima. Scope: emails:send.

Setiap penerima menjadi satu dispatch terpisah dan menerima email sendiri (alamat penerima lain tidak terlihat). Penerima yang ada di suppression list ditandai SUPPRESSED dan tidak dikirimi; bila semua penerima suppressed, permintaan ditolak 422 recipient_suppressed.

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "request_id": "9b2c…",
    "details": { "to.0": ["The to.0 field must be a valid email address."] }
  }
}

Pengiriman batch

POST /v1/emails/batch menerima {"emails": [ … ]} berisi 1–100 objek dengan skema yang sama seperti POST /v1/emails. Respons 207 Multi-Status memuat hasil per item sehingga satu item gagal tidak membatalkan yang lain. Satu Idempotency-Key berlaku untuk seluruh batch (diturunkan per indeks).

{ "results": [
  { "index": 0, "status": 202, "data": { "id": "0192…", "status": "queued" } },
  { "index": 1, "status": 422, "error": { "code": "validation_failed", "details": { "to.0": ["…"] } } }
] }

Lampiran

"attachments": [
  { "filename": "invoice.pdf", "content": "<base64>", "content_type": "application/pdf" }
]

• Maks 10 lampiran; total payload maks 25 MB. Konten harus base64 valid.
• Tipe berbahaya (.exe .bat .cmd .scr .js .vbs .jar .msi .dll) ditolak pada jalur SMTP.

Idempotency

Kirim header Idempotency-Key: <nilai unik> agar retry jaringan tidak menghasilkan email ganda.

• Key sama + body sama → 200 dengan respons email yang sudah dibuat (tidak dikirim lagi).
• Key sama + body berbeda → 409 conflict.
• Key berlaku per organisasi. Gunakan identitas kejadian, mis. otp-{user_id}-{timestamp}.

Jadwal, tag, metadata

• scheduled_at — kirim nanti. Email terjadwal masih bisa dibatalkan dengan POST /v1/emails/{id}/cancel selama berstatus QUEUED.
• tags — hingga 10 label (mis. ["otp"]) untuk memfilter: GET /v1/emails?tag=otp.
• metadata — pasangan kunci-nilai bebas (mis. {"user_id":"8812"}) yang dikembalikan di respons dan di setiap payload webhook. Jangan menaruh data sensitif.

Open & click tracking

Tracking bersifat opt-in. Aktifkan per email (track_opens, track_clicks) atau sebagai bawaan per domain di console.

• Click — link http(s) ditulis ulang ke /c/<token> lalu dialihkan (302). Link berhenti berlangganan milik sistem tidak ikut ditulis ulang.
• Open — piksel GIF 1×1 di /o/<token>.gif.
• Pembuka otomatis (proxy privasi, scanner keamanan, crawler) terdeteksi dan diberi tanda is_bot — jangan menganggapnya pembacaan manusia.
• Pasang CNAME trk.{domain} agar link memakai domain Anda.

Kredensial & port SMTP

Pakai Postivo sebagai relay untuk aplikasi/CMS yang hanya mendukung SMTP (WordPress, Laravel Mail, Nodemailer, dst.).

• Domain pengirim ditentukan oleh header From; MAIL FROM amplop diabaikan (Postivo memakai Return-Path sendiri untuk menangkap bounce).
• Penerima di amplop yang tidak tercantum di header To/Cc diperlakukan sebagai Bcc.
• 10 kegagalan autentikasi dalam 10 menit dari satu IP memblokir sementara IP tersebut.

Kode balasan SMTP

Pesan dianggap diterima (250) hanya setelah tersimpan dan masuk antrean. Karena validasi berjalan sebelum balasan dikirim, penolakan datang dengan kode yang tepat.

Contoh koneksi

const transporter = nodemailer.createTransport({
  host: 'smtp.postivo.my.id',
  port: 587,
  secure: false,          // STARTTLS
  requireTLS: true,
  auth: { user: 'postivo', pass: process.env.POSTIVO_API_KEY },
});

MAIL_MAILER=smtp
MAIL_HOST=smtp.postivo.my.id
MAIL_PORT=587
MAIL_USERNAME=postivo
MAIL_PASSWORD=psv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
[email protected]

import smtplib, ssl
from email.message import EmailMessage

msg = EmailMessage()
msg["From"], msg["To"], msg["Subject"] = "Acme <[email protected]>", "[email protected]", "Halo"
msg.set_content("Tes SMTP")

with smtplib.SMTP("smtp.postivo.my.id", 587) as s:
    s.starttls(context=ssl.create_default_context())
    s.login("postivo", "psv_live_…")
    s.send_message(msg)

Siklus status

Setiap penerima punya satu status. Status hanya maju: event yang datang terlambat tidak bisa memundurkannya (mis. delivered setelah bounced diabaikan).

opened, clicked, dan unsubscribed adalah event, bukan status — satu email bisa berstatus DELIVERED dan tetap menerima event opened berkali-kali.

Bounce & komplain

Suppression list

Daftar alamat yang tidak akan dikirimi email dari organisasi Anda. Terisi otomatis oleh HARD_BOUNCE, COMPLAINT, dan UNSUBSCRIBE; Anda juga bisa menambah manual (MANUAL) atau menghapus entri bila perlu (console atau /v1/suppressions).

Pencocokan memakai alamat huruf kecil; titik dan +tag pada Gmail tidak dinormalisasi.

Berhenti berlangganan: sertakan header List-Unsubscribe Anda sendiri lewat field headers. Tautan /u/<token> milik Postivo mendukung one-click (RFC 8058) dan langsung men-suppress penerima.

Event & payload

Buat endpoint di Webhooks (HTTPS publik) dan pilih event. Postivo mengirim POST JSON setiap ada perubahan.

Tipe event: email.queued email.sent email.delivered email.deferred email.bounced email.complained email.failed email.suppressed email.opened email.clicked email.unsubscribed, atau * untuk semuanya.

{
  "id": "evt_0192…",
  "type": "email.delivered",
  "created_at": "2026-10-27T08:15:32Z",
  "data": {
    "email_id": "0192…", "dispatch_id": "0192…",
    "recipient": "[email protected]", "domain": "mail.contoh.com",
    "tags": ["otp"], "metadata": { "user_id": "8812" },
    "smtp_response": "250 2.0.0 OK", "bounce": null
  }
}

Header: Postivo-Signature, Postivo-Event-Id, User-Agent: Postivo-Webhook/1.0. Endpoint harus membalas 2xx dalam 10 detik. Pengiriman bersifat at-least-once — jadikan handler idempoten pada Postivo-Event-Id.

Verifikasi tanda tangan

Header Postivo-Signature: t=<unix>,v1=<hex>, dengan v1 = HMAC_SHA256(secret, "{t}.{raw_body}"). Secret berformat whsec_… dan hanya tampil sekali saat endpoint dibuat. Gunakan body mentah (sebelum di-parse), bandingkan dengan waktu konstan, dan tolak bila |sekarang − t| > 5 menit (anti-replay).

import crypto from 'node:crypto';

app.post('/webhooks/postivo', express.raw({ type: 'application/json' }), (req, res) => {
  const [t, v1] = req.get('Postivo-Signature').split(',').map((p) => p.split('=')[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);

  const expected = crypto.createHmac('sha256', process.env.POSTIVO_WEBHOOK_SECRET)
    .update(`${t}.${req.body.toString('utf8')}`).digest('hex');
  const ok = expected.length === v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body);   // proses idempoten berdasarkan event.id
  res.sendStatus(200);
});

$header = $request->header('Postivo-Signature');           // "t=…,v1=…"
parse_str(str_replace(',', '&', $header), $p);
$raw = $request->getContent();

abort_if(abs(time() - (int) $p['t']) > 300, 400);
$expected = hash_hmac('sha256', $p['t'].'.'.$raw, config('services.postivo.webhook_secret'));
abort_unless(hash_equals($expected, $p['v1']), 401);

import hmac, hashlib, time
from flask import request, abort

parts = dict(x.split("=", 1) for x in request.headers["Postivo-Signature"].split(","))
raw = request.get_data()
if abs(time.time() - int(parts["t"])) > 300: abort(400)
expected = hmac.new(SECRET.encode(), f"{parts['t']}.".encode() + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, parts["v1"]): abort(401)

Retry & auto-disable

• Respons non-2xx atau timeout dicoba ulang dengan jeda 30 dtk, 2 mnt, 10 mnt, 1 jam, 6 jam, 24 jam.
• Setelah 50 kegagalan beruntun, endpoint dinonaktifkan otomatis dan Anda diberi tahu lewat email. Aktifkan kembali di halaman Webhooks setelah memperbaiki endpoint.
• Riwayat pengiriman terakhir (status HTTP, durasi) tampil di console.

Daftar endpoint

Base URL https://api.postivo.my.id/v1 · JSON UTF-8 · waktu ISO-8601 UTC. Setiap respons membawa X-Request-Id — sertakan saat melapor masalah.

Pagination memakai cursor: respons daftar berisi {"data": […], "next_cursor": "…"}; kirim nilainya sebagai ?cursor= untuk halaman berikutnya.

Format & kode error

{ "error": { "code": "validation_failed", "message": "…", "request_id": "9b2c…", "details": { "field": ["…"] } } }

Rate limit & kuota

• Rate limit: POST /emails 20 permintaan/detik per API key; endpoint lain 10/detik. Header X-RateLimit-Limit, -Remaining, -Reset ada di setiap respons.
• Kuota bulanan & batas harian mengikuti paket. Hanya penerima yang benar-benar diproses yang dihitung (yang SUPPRESSED dan sandbox tidak).
• Saat 429, tunggu sesuai Retry-After lalu ulangi dengan Idempotency-Key yang sama.
• Anda mendapat email peringatan saat kuota mencapai 80% dan 100%.

Paket & batas

Kuota direset setiap awal bulan kalender. Batas per pesan: 25 MB, 50 penerima. Bila paket berbayar berakhir tanpa perpanjangan, akun otomatis kembali ke Free — data, domain, dan API key tetap aman.

Checkout & pembayaran

1. Buka Billing di console, pilih paket, tentukan durasi (1/3/6/12 bulan).
2. Klik Buat tagihan & bayar — Anda diarahkan ke halaman pembayaran aman Xendit.
3. Pilih metode: QRIS, virtual account (BCA, BNI, BRI, Mandiri, Permata, CIMB), Indomaret/Alfamart, atau e-wallet.
4. Setelah dibayar, paket aktif otomatis (lewat webhook; halaman tagihan juga memeriksa status langsung ke Xendit saat Anda kembali).

• Tagihan berlaku 24 jam. Yang kedaluwarsa bisa dibuat ulang tanpa biaya.
• Perpanjangan paket yang sama menyambung dari tanggal berakhir; ganti paket berlaku dari saat pembayaran.
• Hanya owner dan admin organisasi yang dapat membeli.
• Anda menerima email saat tagihan dibuat, saat pembayaran diterima, dan sebelum paket berakhir (7 dan 1 hari).

Email dari Postivo

Email sistem dikirim dari [email protected]; balasan diarahkan ke [email protected]. Pastikan keduanya tidak masuk filter spam Anda.

Keamanan & kepatuhan

• Transport: TLS 1.2+ untuk API dan SMTP. API key disimpan sebagai hash; kunci DKIM privat dan secret webhook dienkripsi.
• Isolasi: setiap organisasi hanya melihat data miliknya; key bisa dibatasi per domain.
• Retensi: isi email (HTML/teks) dihapus setelah 30 hari; event setelah 90 hari. Metadata ringkas tetap ada untuk audit.
• Penggunaan yang diizinkan: hanya email transaksional/berizin. Spam, daftar yang dibeli, phishing, dan konten ilegal berujung penangguhan akun.
• Melapor celah keamanan: [email protected] (jangan sertakan data pelanggan).

FAQ

Respons 202 tapi email tidak sampai?

202 hanya berarti diterima & diantrekan. Buka detail email di console: timeline menunjukkan sent, delivered, atau bounced lengkap dengan respons SMTP server penerima. Cek juga folder spam dan pastikan SPF/DKIM/DMARC hijau.

Berapa lama email sampai?

Umumnya hitungan detik. Angka “< 50 ms” pada materi kami hanya merujuk ke waktu API menerima & mengantrekan, bukan ke waktu sampai di inbox.

Bisa mengirim dari domain tanpa subdomain?

Bisa, tetapi subdomain khusus disarankan: reputasi terpisah dan CNAME Return-Path/Tracking tidak berbenturan dengan record utama.

Email ke satu penerima ditolak recipient_suppressed?

Alamat itu pernah bounce keras, komplain, atau berhenti berlangganan. Hapus dari Suppressions hanya bila Anda yakin masalahnya sudah selesai.

Bagaimana menguji tanpa mengirim email sungguhan?

Gunakan API key test (sandbox): validasi penuh dan event tercatat, tetapi tidak ada email yang keluar dan kuota tidak terpakai.

Kontak

Email [email protected] dengan menyertakan X-Request-Id atau ID email terkait.