Pengiriman batch

POST /v1/email/batches menerima hingga 100 payload pengiriman lengkap dalam satu request. Setiap item adalah pesan independen dengan pengirim, penerima, dan kontennya sendiri. Gunakan batch untuk mengirimkan tanda terima, notifikasi, atau pesan per penerima lainnya dengan lebih sedikit request API. Untuk satu pesan, lihat Mengirim email.

Kapan menggunakan apa

Pesan-pesan independen yang sudah Anda miliki. Gunakan batch dan serahkan semuanya dalam satu request.
Aliran volume tinggi yang stabil. Memanggil endpoint pengiriman tunggal dalam loop adalah arsitektur yang baik, dan batch tidak membuat satu pesan pun lebih murah atau lebih cepat terkirim. Yang berubah adalah throughput, karena request batch menggunakan grup pembatasan laju permintaan email_batch alih-alih grup email_send, dan setiap request menampung hingga 100 pesan.
Satu email ke audiens tersimpan. Itu adalah broadcast, yang me-resolve audiens menjadi penerima dan mempersonalisasi per kontak.

Pengiriman batch

Body request adalah objek JSON yang array messages-nya menampung 1 hingga 100 objek pesan. Setiap item adalah request pengiriman lengkap dan independen dengan from, to, subject, konten, dan opsional category, ip_pool_id, tag, serta metadata sendiri. Skema item sama persis dengan payload pengiriman tunggal, jadi semua yang ada di mengirim email berlaku per item, termasuk default category yaitu marketing dan pengiriman dengan template.

Ini termasuk scheduled_at, sehingga batch dapat mencampur pesan yang dikirim sekarang dengan pesan yang dikirim nanti, masing-masing pada waktunya sendiri. Aturan dan kuota di pengiriman terjadwal berlaku per item, dan item terjadwal dibatalkan berdasarkan ID-nya sendiri seperti pesan terjadwal lainnya.

const batch = await bird.email.sendBatch({
  messages: [
    {
      from: { email: "onboarding@messagebird.dev", name: "Bird" },
      to: ["alice@example.com"],
      subject: "Your receipt",
      html: "<p>Thanks, Alice.</p>",
    },
    {
      from: { email: "onboarding@messagebird.dev", name: "Bird" },
      to: ["bob@example.com"],
      subject: "Your receipt",
      html: "<p>Thanks, Bob.</p>",
    },
  ],
});
for (const item of batch.data) console.log(item.id, item.status);

batch = client.email.send_batch(
    messages=[
        {
            "from_": {"email": "onboarding@messagebird.dev", "name": "Bird"},
            "to": ["delivered@messagebird.dev"],
            "subject": "Hello from Bird",
            "html": "<p>My first Bird email.</p>",
        },
        {
            "from_": {"email": "onboarding@messagebird.dev", "name": "Bird"},
            "to": ["someone-else@messagebird.dev"],
            "subject": "Hello again from Bird",
            "text": "My second Bird email.",
        },
    ],
)
for item in batch.data:
    print(item.id, item.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	batch, err := client.Email.SendBatch(context.Background(), bird.EmailSendBatchParams{
		Messages: []bird.EmailSendParams{
			{
				From:    "onboarding@messagebird.dev",
				To:      []string{"alice@example.com"},
				Subject: "Hello, Alice",
				HTML:    "<p>Welcome!</p>",
			},
			{
				From:    "onboarding@messagebird.dev",
				To:      []string{"bob@example.com"},
				Subject: "Hello, Bob",
				HTML:    "<p>Welcome!</p>",
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, item := range batch.Data {
		fmt.Println(item.Id)
	}
}

$batch = $bird->email->sendBatch(messages: [
    (new EmailMessageSendRequest())
        ->setFrom((new EmailAddress())->setEmail('onboarding@messagebird.dev')->setName('Bird'))
        ->setTo([(new EmailAddress())->setEmail('delivered@messagebird.dev')])
        ->setSubject('Hello from Bird')
        ->setHtml('<p>My first Bird email.</p>'),
    (new EmailMessageSendRequest())
        ->setFrom((new EmailAddress())->setEmail('onboarding@messagebird.dev')->setName('Bird'))
        ->setTo([(new EmailAddress())->setEmail('someone-else@messagebird.dev')])
        ->setSubject('Hello again from Bird')
        ->setText('My second Bird email.'),
]);
foreach ($batch->getData() ?? [] as $item) {
    echo $item->getId(), ' ', $item->getStatus(), "\n";
}

bird email send-batch --body-file - <<'JSON'
{
  "messages": [
    {
      "from": {
        "email": "noreply@acme.com",
        "name": "Acme Support"
      },
      "to": [
        {
          "email": "delivered@messagebird.dev",
          "name": "Jane Doe"
        }
      ],
      "subject": "Your receipt for order #1234",
      "text": "Thanks for your purchase! Your receipt is attached."
    },
    {
      "from": {
        "email": "noreply@acme.com",
        "name": "Acme Support"
      },
      "to": [
        {
          "email": "delivered@messagebird.dev",
          "name": "John Roe"
        }
      ],
      "subject": "Your receipt for order #1235",
      "text": "Thanks for your purchase! Your receipt is attached."
    }
  ]
}
JSON

{
  "name": "email_send_batch",
  "arguments": {
    "messages": [
      {
        "from": {
          "email": "noreply@acme.com",
          "name": "Acme Support"
        },
        "subject": "Your receipt for order #1234",
        "text": "Thanks for your purchase! Your receipt is attached.",
        "to": [
          {
            "email": "delivered@messagebird.dev",
            "name": "Jane Doe"
          }
        ]
      },
      {
        "from": {
          "email": "noreply@acme.com",
          "name": "Acme Support"
        },
        "subject": "Your receipt for order #1235",
        "text": "Thanks for your purchase! Your receipt is attached.",
        "to": [
          {
            "email": "delivered@messagebird.dev",
            "name": "John Roe"
          }
        ]
      }
    ]
  }
}

curl -X POST https://us1.platform.bird.com/v1/email/batches \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-2026-07-23-001" \
  -d '{
    "messages": [
      {
        "from": "hello@yourdomain.com",
        "to": ["delivered@messagebird.dev"],
        "subject": "Your receipt",
        "html": "<p>Thanks for your order.</p>",
        "category": "transactional"
      },
      {
        "from": "newsletter@yourdomain.com",
        "to": ["delivered@messagebird.dev"],
        "subject": "June product news",
        "html": "<p>What shipped this month.</p>",
        "category": "marketing"
      },
      {
        "from": "alerts@yourdomain.com",
        "to": ["delivered@messagebird.dev"],
        "subject": "Usage threshold reached",
        "text": "You have used 80% of your quota.",
        "category": "transactional"
      }
    ]
  }'

Validasi all-or-nothing

Setiap item divalidasi sebelum item mana pun diantrikan. Jika satu pesan gagal, entah kesalahan validasi tingkat field atau domain pengirim yang belum diverifikasi, seluruh batch ditolak dengan 422 dan tidak ada yang terkirim: perbaiki item tersebut dan kirim ulang batch.

Supresi bukan bagian dari pemeriksaan itu. Item yang semua penerimanya disupresi tetap diterima dan mendapat ID em_ sendiri, dan penerima tersebut dilaporkan sebagai status: rejected setelah pesan diproses (lihat supresi).

Menangani respons 202

Batch yang berhasil mengembalikan 202 Accepted dengan satu entri per pesan, sesuai urutan pengiriman:

Contoh kode

{
  "data": [
    { "id": "em_01ky7q1vmkerwa7fxyycfe5ks1", "status": "accepted", "category": "transactional" },
    { "id": "em_01ky7q1vmkesr9h1y52tkqng9f", "status": "accepted", "category": "marketing" },
    { "id": "em_01ky7q1vmkesyr1z1h4s48jjxm", "status": "accepted", "category": "transactional" }
  ]
}

Setiap child adalah pesan biasa: lacak berdasarkan ID em_ melalui GET /v1/email/messages/{message_id}, endpoint penerima dan event, serta webhook, persis seperti jika Anda mengirimnya secara terpisah. Model async yang sama berlaku, sehingga 202 berarti diterima secara durable dan hasil per penerima tiba kemudian.

Retry idempoten

Kirim header Idempotency-Key bersama batch, seperti yang dilakukan contoh request. Jika request berhasil tetapi Anda tidak pernah melihat responsnya, mengulangnya dengan key yang sama mengembalikan hasil asli, yaitu ID pesan child yang sama dan header Idempotency-Replay, alih-alih mengirim semua pesan lagi. Satu duplikasi tidak disengaja di sini menghabiskan hingga 100 email, jadi perlakukan key sebagai wajib di production. Lihat idempotensi.

Lampiran dan batas body

Setiap item batch dapat memiliki attachments sendiri, dengan kontrak field dan anggaran ukuran per pesan yang sama dengan pengiriman tunggal (lihat lampiran). Satu batas lagi berlaku untuk batch secara keseluruhan: body request JSON yang diserialisasi dibatasi pada 20 MB, dan body yang lebih besar ditolak dengan 413. Lampiran berenkode Base64 dihitung terhadapnya, jadi batch dengan banyak lampiran cepat mencapai batas. Pecah ke beberapa batch, atau kirim satu per satu.

Broadcast

Broadcast mengirim satu email ke audiens tersimpan. Kami me-resolve anggota audiens saat ini, dikurangi supresi, menjadi daftar penerima saat pengiriman dimulai, dan properti kontak setiap penerima mengisi variabel template. Jalankan dari dashboard, dari /v1/email/broadcasts, atau dengan perintah bird email broadcasts. Broadcast memiliki panduan lengkapnya.

Langkah selanjutnya

Mengirim email: payload per item secara lengkap, termasuk field, batas, dan tag vs metadata
Broadcast: satu email ke audiens tersimpan, dipersonalisasi per kontak
Kategori: marketing dan transactional, dan pengaruh masing-masing terhadap kebijakan supresi
Idempotensi: format key, retensi, dan semantik replay
Referensi API: skema request dan respons batch lengkap
Kirim 100 email dalam satu panggilan API: video yang menunjukkan batch terkirim dan bagaimana setiap pesan melaporkan hasilnya

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Jelajahi kemampuannyaEmail batch sending Ikuti jalur pembelajaranBuild your first integration

Dapatkan ringkasan implementasi