Referensi API

REST API email transaksional

API menerima permintaan yang terautentikasi, memverifikasi scope proyek dan status domain, memeriksa suppression, lalu mengantrekan pesan yang diterima.

2026-10-13Unduh OpenAPI 3.1

Autentikasi

Kirim kunci srs_live_ scoped dari dasbor sebagai token Bearer. Setiap kunci punya scope sendiri (emails:send, webhooks:write …); kunci yang dicabut atau kedaluwarsa ditolak dengan 401.

POST /v1/emails

Permintaan / Respons

curl --request POST 'https://api.srs-postline.com/v1/emails' \
  --header 'Authorization: Bearer srs_live_...' \
  --header 'Idempotency-Key: order_4821' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from": "Postline <info@example.com>",
    "to": ["user@example.net"],
    "subject": "Your order is ready",
    "html": "<p>Order #4821 is ready.</p>",
    "text": "Order #4821 is ready."
  }'

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id": "msg_01JPOSTLINEEXAMPLE",
  "status": "queued",
  "created_at": "2026-08-22T12:00:00Z"
}

Parameter input

Parameter	Tipe	Wajib	Deskripsi	Contoh
`Authorization`	`header · string`	Ya	Kunci API scoped yang diterbitkan dasbor sebagai token Bearer.	`Bearer srs_live_…`
`Idempotency-Key`	`header · string`	Tidak	Pengenal stabil untuk satu pengiriman logis; sangat disarankan.	`order_4821`
`from`	`string`	Ya	Nama dan alamat pengirim pada domain terverifikasi.	`Postline <info@example.com>`
`to`	`string[]`	Ya	Alamat penerima; to + cc + bcc maksimal 100 secara total.	`["user@example.net"]`
`subject`	`string`	Ya	Subjek pesan.	`Pesanan Anda siap`
`html`	`string`	Tidak	Isi HTML. Salah satu dari html atau text wajib diisi.	`<p>…</p>`
`text`	`string`	Tidak	Isi teks biasa. Salah satu dari text atau html wajib diisi.	`Pesanan #4821…`
`cc / bcc`	`string[]`	Tidak	Tembusan dan tembusan tersembunyi (dihitung dalam batas 100).	`["team@example.com"]`
`reply_to`	`string[]`	Tidak	Hingga 10 alamat balasan.	`["support@example.com"]`
`send_at`	`string · date-time`	Tidak	Jadwalkan pengiriman hingga 30 hari (RFC 3339).	`2026-11-06T09:00:00Z`
`tags`	`object`	Tidak	Hingga 20 tag kunci/nilai.	`{"type":"receipt"}`
`headers`	`object`	Tidak	Hingga 8: In-Reply-To, References, List-Unsubscribe, List-Unsubscribe-Post.	`{"References":"<…>"}`
`template / variables`	`string / object`	Tidak	ID template terbit; subjek dan isi dari variables.	`"order-ready"`

Kode respons

Status	HTTP	Deskripsi
`202`	Accepted	Pesan masuk antrean; ini belum berarti pesan terkirim ke kotak masuk.
`400`	Bad Request	JSON tidak valid atau bidang tidak didukung.
`401`	Unauthorized	Kunci API tidak valid, kedaluwarsa, atau dicabut.
`403`	Forbidden	Scope tidak ada atau domain pengirim belum diverifikasi.
`422`	Unprocessable Entity	Penerima berada dalam daftar suppression.
`429`	Too Many Requests	Batas permintaan proyek terlampaui.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "recipient suppressed"
}

Kirim email

POST /v1/emails
Authorization: Bearer srs_live_…
Idempotency-Key: reset-4821
Content-Type: application/json

Resource inti

POST/v1/emailsmengantrekan satu pesan

POST/v1/emails/batchhingga 100 pesan per permintaan

GET/v1/emailsdaftar pesan terbaru

GET/v1/emails/{id}status pesan

DELETE/v1/emails/{id}/schedulemembatalkan pengiriman terjadwal

GET/POST/v1/domainsdaftar atau tambah domain pengirim

POST/v1/domains/{id}/verifymenjalankan pemeriksaan DNS

POST/v1/suppressionsmen-suppress penerima

GET/DELETE/v1/suppressions/{email}memeriksa atau menghapus suppression

GET/POST/v1/webhooksdaftar atau buat endpoint webhook

DELETE/v1/webhooks/{id}menghapus endpoint

GET/v1/webhooks/{id}/deliverieslog percobaan pengiriman

POST/v1/webhooks/{id}/deliveries/{deliveryId}/replaymengirim ulang pengiriman

GET/POST/v1/templatesdaftar atau buat template

Model respons

202 berarti diantrekan, bukan masuk inbox. 403 dapat mengindikasikan scope yang hilang atau domain yang belum terverifikasi. 422 memblokir penerima yang di-suppress. 429 mengindikasikan rate limiting.

Batas layanan saat ini

API REST menolak lampiran. Hanya header khusus In-Reply-To, References, List-Unsubscribe dan List-Unsubscribe-Post yang diterima (maksimal 8). Email terkelola terpisah: klien web menerima 20 lampiran, total 25 MiB; klien desktop yang dirilis membatasi pengiriman 10 MiB. HTTP 202 dan email.accepted berarti diterima untuk diproses; penerimaan SMTP tidak menjamin pengiriman atau masuk ke kotak masuk.

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.