Batch-Versand

POST /v1/email/batches nimmt bis zu 100 vollständige Versand-Payloads in einem Request entgegen. Das entspricht dem Muster für Massen-E-Mails: ein Aufruf für viele unabhängige Nachrichten. Jedes Element hat eigenen Absender, eigene Empfänger und eigenen Inhalt. Verwenden Sie einen Batch, um Belege, Benachrichtigungen oder andere empfängerspezifische Nachrichten mit weniger API-Requests zu übermitteln. Für eine einzelne Nachricht siehe E-Mail senden.

Wann Sie was verwenden

Unabhängige Nachrichten, die Sie bereits vorliegen haben. Verwenden Sie einen Batch und übergeben Sie alle in einem Request.
Ein stetiger Strom mit hohem Volumen. Den Endpunkt für den Einzelversand in einer Schleife aufzurufen, ist eine sinnvolle Architektur. Ein Batch macht die Zustellung einzelner Nachrichten weder günstiger noch schneller. Er verändert den Durchsatz, da Batch-Requests die Richtlinie zur Begrenzung der Anfragerate email_batch anstelle der Richtlinie email_send nutzen und jeder Request bis zu 100 Nachrichten enthält.
Eine E-Mail an eine gespeicherte Zielgruppe. Das ist ein Broadcast, der die Zielgruppe in Empfänger auflöst und pro Kontakt personalisiert.

Templates in einem Batch

Jedes Element kann ein veröffentlichtes template mit eigenem parameters und eigenem language verwenden.

Ein Template, das Kontaktattribute verwendet, wird für jede To-Adresse separat personalisiert, anhand von Kontakten im selben Workspace. Cc- und Bcc-Empfänger erhalten eine Kopie der personalisierten E-Mail jedes To-Empfängers und benötigen keinen passenden Kontakt. Der Batch teilt Abfragen für wiederholte Adressen und liest die Attribute, die jedes Template verwendet. Eine ausgewählte Sprache und ein Request-Envelope ohne Kontaktverweise lösen keine Kontaktabfrage aus.

Empfängerwerte werden gespeichert, wenn der Batch akzeptiert wird, auch für geplante Elemente. Wenn Sie später einen Kontakt oder Fallback bearbeiten, ändert das keine Nachricht in der Warteschlange. Ein fehlender To-Kontakt, ein fehlender Pflichtparameter, eine mehrdeutige Kontaktzuordnung oder ein ungültiger Kontaktwert führt zur Ablehnung des Batches, bevor ein Element angenommen wird. Bei einem Datenbankfehler wird ein Fehler zurückgegeben, den Sie erneut versuchen können, statt den Kontakt als fehlend zu behandeln. Regeln zu fehlenden Werten und Fallbacks finden Sie unter Template-Personalisierung.

Batch-Versand

Der Request-Body ist ein JSON-Objekt, dessen messages-Array 1 bis 100 Nachrichtenobjekte enthält. Jedes Element ist ein vollständiger, unabhängiger Versand-Request mit eigenem from, to, subject, Inhalt und optional eigenem category, ip_pool_id, Tags und Metadaten. Das Element-Schema entspricht exakt dem Einzelversand-Payload, daher gilt alles aus E-Mail senden pro Element, einschließlich des category-Standardwerts marketing und des Versands per Template.

Das schließt scheduled_at ein. Ein Batch kann also Nachrichten, die sofort versendet werden, mit solchen kombinieren, die später versendet werden, jede zu ihrem eigenen Zeitpunkt. Die Regeln und das Kontingent unter geplanter Versand gelten pro Element, und Sie stornieren ein geplantes Element wie jede andere geplante Nachricht über seine eigene ID.

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

curl -X POST https://us1.platform.bird.com/v1/email/batches \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -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"
      }
    ]
  }'

Alles-oder-nichts-Validierung

Jedes Element wird validiert, bevor ein Element in die Warteschlange kommt. Wenn eine Nachricht fehlschlägt, etwa durch einen Validierungsfehler auf Feldebene oder eine nicht verifizierte Absenderdomain, wird der gesamte Batch mit einem 422 abgelehnt und nichts versendet. Beheben Sie das betroffene Element und senden Sie den Batch erneut.

Unterdrückung ist nicht Teil dieser Prüfung. Ein Element, dessen Empfänger alle unterdrückt sind, wird trotzdem akzeptiert und erhält seine eigene em_-ID, und diese Empfänger erscheinen als status: rejected, sobald die Nachricht verarbeitet ist (siehe Unterdrückungen).

Die `202`-Antwort verarbeiten

Ein erfolgreicher Batch gibt 202 Accepted mit einem Eintrag pro Nachricht zurück, in Einreichungsreihenfolge:

Codebeispiel

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

Jedes untergeordnete Element ist eine gewöhnliche Nachricht: Verfolgen Sie es über seine em_-ID durch GET /v1/email/messages/{message_id}, seine Empfänger- und Event-Endpoints sowie Webhooks, genau so, als hätten Sie es einzeln gesendet. Dasselbe asynchrone Modell gilt, d. h. 202 bedeutet dauerhaft akzeptiert, und Ergebnisse pro Empfänger treffen danach ein.

Idempotente erneute Versuche

Idempotenz ist optional. Die SDKs erzeugen einen Schlüssel für automatische erneute Versuche. Hinweise zur Wiederverwendung von Schlüsseln und zu Wiedergabegrenzen bei separaten Aufrufen oder direkter Nutzung von HTTP finden Sie im Idempotenzleitfaden.

Anhänge und das Body-Limit

Jedes Batch-Element kann eigene attachments haben, mit demselben Feldvertrag und demselben Größenbudget pro Nachricht wie ein Einzelversand (siehe Anhänge). Ein weiteres Limit gilt für den Batch als Ganzes: Der serialisierte JSON-Request-Body ist auf 20 MB begrenzt, und ein größerer Body wird mit einem 413 abgelehnt. Base64-kodierte Anhänge werden auf dieses Limit angerechnet, daher erreichen anhangslastige Batches es schnell. Teilen Sie sie auf mehrere Batches auf oder senden Sie sie einzeln.

Broadcasts

Ein Broadcast sendet eine E-Mail an eine gespeicherte Zielgruppe. Die aktuellen Mitglieder der Zielgruppe werden beim Versandstart abzüglich Unterdrückungen in die Empfängerliste aufgelöst, und die Kontakteigenschaften jedes Empfängers füllen die Variablen des Templates. Starten Sie einen Broadcast über das Dashboard, über /v1/email/broadcasts oder mit den bird email broadcasts-Befehlen. Broadcasts enthält die Schritt-für-Schritt-Anleitung.

Nächste Schritte

E-Mail senden: das vollständige Element-Payload, einschließlich Felder, Limits und Tags vs. Metadaten
Broadcasts: eine E-Mail an eine gespeicherte Zielgruppe, personalisiert pro Kontakt
Kategorien: marketing und transactional, und was jede für die Unterdrückungsrichtlinie bedeutet
Idempotenz: Schlüsselformat, Aufbewahrung und Replay-Semantik
API-Referenz: die vollständigen Batch-Request- und -Response-Schemas
100 E-Mails in einem API-Aufruf senden: ein Video, das einen Batch-Versand zeigt und wie jede Nachricht ihren Status zurückmeldet

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Implementierungs-Briefing erhalten

Verwandte Ressourcen