Pengiriman tunggal dan batch

Gunakan pengiriman tunggal untuk satu pesan dan batch untuk beberapa pesan. Keduanya mengembalikan HTTP 202 dengan code=000000 saat diterima.

Endpoint dan kegunaan

Email pemasaran dan transaksional

Permintaan non-template tanpa messageType menggunakan default MARKETING; template dapat menentukan tipenya. Jangan menandai konten promosi sebagai transaksional untuk menghindari aturan penerima pemasaran.

Konten langsung dan template

• Konten langsung: isi text atau html yang tidak kosong, atau keduanya. Teks biasa dan HTML menjadi bagian konten berbeda; menyediakan keduanya disarankan untuk kompatibilitas email pemasaran.
• Template: isi template.templateId tanpa text/html yang tidak kosong. subject tetap wajib dan dapat berisi variabel.
• variables hanya merender template; variabel tidak mengganti placeholder pada text/html yang diberikan langsung.
• Tidak ada unggahan lampiran atau penyimpanan konten lampiran yang dapat digunakan. Referensi lampiran dalam model permintaan tidak berarti lampiran akan dikirim; abaikan attachments.

Lihat Template dan variabel untuk pembuatan, review, dan aturan rendering.

Siklus pesan tunggal

1. Platform mengautentikasi dan memvalidasi permintaan serta memeriksa idempotensi.
2. Simpan messageId dan baca X-Request-Id dari header respons.
3. Tahap pengiriman berikutnya memeriksa otorisasi pengirim, template, tipe pesan, supresi, dan perutean kanal.
4. Gunakan catatan pengiriman atau Webhook untuk hasil akhir; ACCEPTED tidak berarti terkirim.

Perilaku batch sebelum dan setelah penerimaan

Sebelum penerimaan: validasi seluruh batch

messages harus berisi 1–100 item, masing-masing dengan struktur yang sama seperti pesan tunggal. Jika satu item gagal validasi field atau bisnis, seluruh batch ditolak dan tidak ada item yang diterima. Batas laju menghitung jumlah pesan, bukan jumlah permintaan HTTP; kapasitas yang tidak mencukupi juga menolak seluruh batch.

Setelah penerimaan: proses setiap pesan secara independen

Setelah diterima, setiap pesan menjalani pemeriksaan template, identitas pengirim, supresi, dan kanal secara independen. Satu batch dapat berisi pesan terkirim, bounce, ditolak, dan gagal secara bersamaan.

{
  "messages": [
    {
      "from": {"email": "news@example.com"},
      "to": [{"email": "alice@example.net"}],
      "subject": "Product update",
      "html": "<p>Hello Alice</p>",
      "messageType": "MARKETING"
    },
    {
      "from": {"email": "news@example.com"},
      "to": [{"email": "bob@example.net"}],
      "subject": "Product update",
      "html": "<p>Hello Bob</p>",
      "messageType": "MARKETING"
    }
  ]
}

Contoh ini mengirim dua email pemasaran independen dan tidak menampilkan alamat Alice kepada Bob. acceptedCount menghitung objek yang diterima, bukan penerima yang terkirim. messages[].index sesuai indeks array input, dan messages[].messageId mengidentifikasi setiap pesan.

Alamat penerima tidak valid

Alamat dalam satu objek dideduplikasi tanpa membedakan huruf besar/kecil dengan urutan To, Cc, lalu Bcc. Jika pesan transaksional memiliki beberapa alamat yang salah format tetapi masih memiliki penerima valid, invalidRecipients dapat berisi ringkasan pemeriksaan awal. Jika semua alamat tidak valid, permintaan ditolak sebelum penerimaan.

Ringkasan ini bukan daftar kegagalan akhir. Keberadaan kotak surat, bounce, keluhan, dan supresi memerlukan hasil pengiriman berikutnya. Pesan pemasaran harus memenuhi aturan satu penerima dalam permintaan asli; deduplikasi tidak dapat digunakan untuk menghindarinya.

Idempotensi dan percobaan ulang

• Berikan setiap tugas bisnis independen sebuah X-Idempotency-Key unik dengan panjang maksimal 128 karakter, lalu simpan bersama body permintaan sebelum panggilan pertama.
• Dengan AppID dan endpoint yang sama, kunci dan konten yang sama memutar ulang hasil awal; tugas yang masih diproses mengembalikan konflik; konten berbeda mengembalikan konflik konten.
• Endpoint tunggal dan batch memiliki namespace idempotensi terpisah. Percobaan ulang batch harus mempertahankan seluruh isi dan urutan array.
• Hasil disimpan selama 24 jam secara default, bergantung pada lingkungan aktual. Kunci kedaluwarsa bukan perlindungan duplikasi jangka panjang.
• Dengan CheckSum, buat Nonce, CurTime, dan CheckSum baru untuk setiap percobaan HTTP sambil mempertahankan kunci dan body asli.

Pertanyaan umum

Apakah penerimaan berarti terkirim?

Tidak. Penerimaan hanya memulai pemrosesan. Gunakan catatan pengiriman atau Webhook untuk hasil akhir.

Sumber terkait