Wysyłanie wsadowe
POST /v1/email/batches przyjmuje do 100 kompletnych ładunków wysyłki w jednym żądaniu. Każdy element to niezależna wiadomość z własnym nadawcą, odbiorcami i treścią. Użyj wsadu, aby przesłać potwierdzenia, alerty lub inne wiadomości per odbiorca przy mniejszej liczbie żądań API. Aby wysłać pojedynczą wiadomość, zobacz Wysyłanie e-maili.
Kiedy czego użyć
- Niezależne wiadomości, które masz już przygotowane. Użyj wsadu i przekaż je w jednym żądaniu.
- Stały strumień o dużym wolumenie. Wywoływanie endpointu pojedynczej wysyłki w pętli to solidna architektura, a wsad nie sprawia, że pojedyncza wiadomość jest tańsza ani szybciej dostarczana. Zmienia się przepustowość, bo żądania wsadowe korzystają z email_batch grupy limitów, a nie z grupy email_send, i każde przyjmuje do 100 wiadomości.
- Jeden e-mail do zapisanej grupy odbiorców. To jest broadcast, który rozwiązuje grupę odbiorców na listę adresatów i personalizuje treść per kontakt.
Wysyłki wsadowe
Ciało żądania to obiekt JSON, którego tablica messages zawiera od 1 do 100 obiektów wiadomości. Każdy element to kompletne, niezależne żądanie wysyłki z własnym from, to, subject, treścią, a opcjonalnie także własnym category, ip_pool_id, tagami i metadanymi. Schemat elementu jest identyczny z ładunkiem pojedynczej wysyłki, więc wszystko z sekcji wysyłanie e-maili obowiązuje per element, łącznie z domyślną wartością category równą marketing i wysyłką przez szablon.
Obejmuje to scheduled_at, więc wsad może łączyć wiadomości wysyłane natychmiast z wiadomościami wysyłanymi później, każdą we własnym czasie. Reguły i limity opisane w sekcji wysyłka zaplanowana obowiązują per element, a zaplanowany element anuluje się po jego własnym ID, tak jak każdą inną zaplanowaną wiadomość.
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"
}
]
}'Walidacja wszystko albo nic
Każdy element jest walidowany, zanim którykolwiek trafi do kolejki. Jeśli jedna wiadomość nie przejdzie walidacji, czy to błąd walidacji na poziomie pola, czy niezweryfikowana domena nadawcy, cały wsad jest odrzucany z 422 i nic nie zostaje wysłane: popraw ten element i prześlij wsad ponownie.
Wyciszenie nie jest częścią tego sprawdzenia. Element, którego wszyscy odbiorcy są wyciszeni, i tak zostaje zaakceptowany i otrzymuje własny identyfikator em_, a ci odbiorcy wracają jako status: rejected po przetworzeniu wiadomości (zobacz wyciszenia).
Obsłuż odpowiedź 202
Pomyślny wsad zwraca 202 Accepted z jednym wpisem na wiadomość, w kolejności przesłania:
Przykład kodu
{
"data": [
{ "id": "em_01ky7q1vmkerwa7fxyycfe5ks1", "status": "accepted", "category": "transactional" },
{ "id": "em_01ky7q1vmkesr9h1y52tkqng9f", "status": "accepted", "category": "marketing" },
{ "id": "em_01ky7q1vmkesyr1z1h4s48jjxm", "status": "accepted", "category": "transactional" }
]
}Każdy element potomny to zwykła wiadomość: śledź ją po identyfikatorze em_ przez GET /v1/email/messages/{message_id}, endpointy odbiorców i zdarzeń oraz webhooki, dokładnie tak, jakbyś wysłał ją osobno. Obowiązuje ten sam model asynchroniczny, więc 202 oznacza trwałe zaakceptowanie, a wyniki per odbiorca docierają później.
Idempotentne ponawianie
Wyślij nagłówek Idempotency-Key razem ze wsadem, tak jak w przykładowym żądaniu. Jeśli żądanie się powiodło, ale nie zobaczyłeś odpowiedzi, powtórzenie go z tym samym kluczem zwraca oryginalny wynik, te same identyfikatory wiadomości potomnych i nagłówek Idempotency-Replay, zamiast wysyłać wszystkie wiadomości ponownie. Jeden przypadkowy duplikat kosztuje tu do 100 e-maili, więc traktuj klucz jako wymagany na produkcji. Zobacz idempotentność.
Załączniki i limit rozmiaru ciała żądania
Każdy element wsadu może mieć własne attachments, na tych samych zasadach i z tym samym budżetem rozmiaru per wiadomość co pojedyncza wysyłka (zobacz załączniki). Jeden dodatkowy limit dotyczy wsadu jako całości: zserializowane ciało żądania JSON jest ograniczone do 20 MB, a większe ciało jest odrzucane z 413. Załączniki zakodowane w Base64 wliczają się w ten limit, więc wsady z dużą liczbą załączników szybko go osiągają. Podziel je na kilka wsadów lub wysyłaj pojedynczo.
Broadcasty
Broadcast wysyła jeden e-mail do zapisanej grupy odbiorców. Rozwiązujemy aktualnych członków grupy, pomniejszonych o wyciszenia, na listę adresatów w momencie rozpoczęcia wysyłki, a właściwości kontaktu każdego odbiorcy wypełniają zmienne szablonu. Uruchom broadcast z dashboardu, z /v1/email/broadcasts lub za pomocą poleceń bird email broadcasts. Broadcasty zawierają pełny opis krok po kroku.
Następne kroki
- Wysyłanie e-maili: pełny ładunek per element, łącznie z polami, limitami oraz tagi a metadane
- Broadcasty: jeden e-mail do zapisanej grupy odbiorców, personalizowany per kontakt
- Kategorie: marketing i transactional oraz wpływ każdej z nich na politykę wyciszeń
- Idempotentność: format klucza, retencja i semantyka powtórzeń
- Referencja API: pełne schematy żądania i odpowiedzi wsadu
- Wyślij 100 e-maili w jednym wywołaniu API: film pokazujący wysyłkę wsadu i sposób raportowania każdej wiadomości
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.