Integrasi AI

Hubungkan pengiriman email untuk agen AI

Jalur yang dapat dibaca mesin untuk coding agent dan asisten yang perlu menambahkan email transaksional ke proyek milik orang lain — apa yang dipanggil, dalam urutan apa, dan pemeriksaan apa yang harus dijalankan sebelum setiap pengiriman.

Diperbarui 24 Juli 2026Unduh OpenAPI 3.1

Sebelum menulis kode apa pun

Minta kunci API proyek dari pengguna, atau minta mereka membuat kunci sandbox di https://app.srs-postline.com/id/login — jangan pernah mengarang, menebak, atau menggunakan kembali kunci dari proyek lain.
Letakkan kunci di variabel lingkungan sisi server. Jangan tempatkan di kode frontend, bundel aplikasi mobile, repo publik, atau file .env yang di-commit.
Baca /llms.txt dan openapi/postline.yaml sebelum membuat kode permintaan; jangan menebak nama field atau endpoint.

Pengiriman minimal

POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <id-stabil-per-pengiriman-logis>
Content-Type: application/json

{
  "from": "Sender Name <info@example.com>",
  "to": ["user@example.net"],
  "subject": "Subjek",
  "html": "<p>Isi</p>",
  "text": "Isi"
}

Pemeriksaan yang harus dijalankan sebelum setiap pengiriman

Selalu kirim Idempotency-Key yang diturunkan dari aksi pemicu (ID pesanan, ID event) sehingga percobaan ulang tidak dapat mengirim ganda.
Jangan pernah menaruh kode OTP, token reset kata sandi, atau secret lain di field yang dicatat log atau diteruskan ke luar isi pesan.
Minta scope kunci API yang paling sempit yang dibutuhkan tugas (emails:send sudah cukup untuk pengiriman; jangan minta domains:write atau api_keys:write kecuali tugas tersebut membutuhkannya).
Batasi penerima hingga 100 per panggilan. API saat ini tidak menerima lampiran atau header khusus; tolak file atau berikan tautan tanpa menyatakan bahwa file telah dilampirkan.
Jangan mencoba ulang secara diam-diam pada respons 4xx. Hanya 429 dan 503 yang aman dicoba ulang, dan hanya dengan backoff.

Tangani setiap kode respons

202 — diantrekan, belum terkirim. Simpan id yang dikembalikan jika Anda perlu memeriksa status nanti.
400 — payload tidak valid; perbaiki permintaan, jangan coba ulang tanpa perubahan.
401 — kunci tidak valid atau kedaluwarsa; hentikan dan tampilkan ke pengguna, jangan mengarang kunci baru.
403 — scope hilang atau domain pengirim belum terverifikasi; beri tahu pengguna untuk memverifikasi domain sebelum melanjutkan.
422 — penerima di-suppress (pernah bounce/complaint); jangan coba ulang ke penerima tersebut.
429 — dibatasi rate; mundur (back off) dan coba lagi nanti, jangan melakukan loop ketat.
503 — antrean tidak tersedia; coba ulang dengan backoff, jangan beralih ke transport tidak resmi.

Jika tugas mencakup penerimaan event

Daftarkan endpoint webhook hanya melalui HTTPS. Hitung ulang tanda tangan sendiri sebelum mempercayai payload apa pun; jangan lewati verifikasi hanya karena permintaan 'terlihat internal'.

signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)

bandingkan dengan header Postline-Signature (constant-time compare)
tolak jika Postline-Timestamp berada di luar jendela waktu yang diizinkan
simpan event_id dan proses setiap event tepat satu kali

Referensi yang dapat dibaca mesin

/llms.txt — indeks ringkas aturan ini untuk context window agen.
/openapi/postline.yaml — skema OpenAPI 3.1 lengkap untuk setiap endpoint.
/id/api/ — referensi API untuk manusia.
/id/webhooks/ — detail tanda tangan dan retry webhook.

Model akses saat ini

Kunci saat ini memakai srs_live_. Sebelum domain From diverifikasi, pengirim sandbox bersama hanya dapat mengirim ke anggota proyek. Setelah itu kuota, suppression, batas penerima, dan kontrol abuse tetap berlaku. 202 berarti masuk antrean, bukan terkirim.

Sumber daya integrasi

Gunakan panduan langkah demi langkah untuk manusia dan agen AI; OpenAPI adalah sumber kebenaran field.