An Audiences senden

Sendet eine Nachricht an alle in einer oder mehreren Audiences, als eigene Kopie für jede Person und aus jedem Kontakt personalisiert. Jede Kopie hat genau einen Empfänger und kein Cc oder Bcc, sodass niemand sieht, an wen sie sonst ging, und jede Kopie ist eine gewöhnliche E-Mail mit eigener msg_-ID, eigenen Events, Tracking und Webhooks. Der Aufruf antwortet sofort mit 202, und der Versand läuft im Hintergrund, verfolgen Sie ihn also mit GET /broadcasts/{id}.

Benötigt emails:send und audiences:read. audienceIds enthält 1 bis 10 IDs. Der Inhalt kommt aus html und/oder text oder aus einer gespeicherten template, nie aus beidem, und subject ist Pflicht, sofern die Vorlage ihn nicht liefert.

curl -X POST "$OE/broadcasts" -H "$AUTH" -H 'content-type: application/json' -d '{  "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"],  "from": "Acme <[email protected]>",  "subject": "{{firstName|Hello}}, the September release is out",  "html": "<p>Hi {{firstName|there}},</p><p>Here is what changed this month.</p>",  "text": "Hi {{firstName|there}}, here is what changed this month. Unsubscribe: {{unsubscribeUrl}}",  "tags": { "campaign": "release-2026-09" },  "scheduledAt": "PT2H"}'

{  "object": "broadcast",  "id": "brd_5a8c1e3f7b2d94a06c8e1f3b",  "status": "scheduled",  "mode": "live",  "source": "api",  "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"],  "from": "Acme <[email protected]>",  "subject": "{{firstName|Hello}}, the September release is out",  "counts": {    "recipients": 412,    "created": 0,    "skipped": 0,    "failedToQueue": 0,    "queued": 0,    "sending": 0,    "sent": 0,    "failed": 0,    "cancelled": 0  },  "lastError": null,  "scheduledAt": "2026-09-23T14:00:00.000Z",  "startedAt": null,  "completedAt": null,  "cancelledAt": null,  "createdAt": "2026-09-23T12:00:00.000Z",  "updatedAt": "2026-09-23T12:00:00.000Z",  "replayed": false}

Jeder Kontakt in mindestens einer der Audiences, einmal gezählt, egal in wie vielen er ist. Zwei Arten von Kontakten fallen weg: einer, der sich von jeder gewählten Audience abgemeldet hat, in der er ist, und einer, dessen Adresse nach einem Bounce oder einer Beschwerde oder weil jemand sie hinzugefügt hat auf der Sperrliste steht. Ein Kontakt, der nach dem Aufruf, aber bevor der Versand ihn erreicht, zu einer der Audiences hinzukommt, ist dabei.

Der Versand geht die Audiences in Schritten von 50 Personen durch und übergibt jede Kopie derselben Pipeline, die POST /emails nutzt, sodass jede Kopie wie jede andere Nachricht wiederholt, verfolgt und gemeldet wird. POST /broadcasts/preview gibt die Zahl zurück, von der dieser Aufruf ausgehen würde, ohne etwas zu senden.

subject, html und text werden für jede Person ausgefüllt. Jedes Feld nimmt nach einem Strich einen Ersatzwert, der verwendet wird, wenn der Kontakt dafür keinen Wert hat, sodass {{firstName|there}} für einen ohne Namen gespeicherten Kontakt zu „there“ wird. Werte werden in html maskiert, Leerzeichen innerhalb der Klammern sind erlaubt, und jedes andere {{…}} bleibt genau so stehen, wie es geschrieben ist.

Mit template statt eines Inhalts werden dieselben fünf Werte als Props übergeben, aber nur die Props, die die Vorlage deklariert. Eine Vorlage, die firstName deklariert, bekommt ihn, und ein nicht deklariertes Prop wird nie gesendet, sodass die Kopien nie an einem unbekannten Prop scheitern. Alles, was Sie in template.props angeben, geht an jede Kopie gleich.

Jede Kopie trägt List-Unsubscribe und List-Unsubscribe-Post: List-Unsubscribe=One-Click. Damit kann ein Mailprogramm seine eigene Abmelde-Schaltfläche zeigen, und genau das verlangen die großen Postfachanbieter von Massenmails.

Ein html- oder text-Inhalt, der {{unsubscribeUrl}} nicht selbst platziert, bekommt eine einzeilige Fußzeile: „You are receiving this because you are on this mailing list. Unsubscribe“. Eine Vorlage wird genau so gesendet, wie sie ist, setzen Sie {{unsubscribeUrl}} also in die Vorlage.

Der Link öffnet eine Seite mit einer Abmelde-Schaltfläche, sodass ein Linkscanner, der ihn abruft, niemanden abmeldet, während die Ein-Klick-Anfrage eines Mailprogramms sofort abmeldet. So oder so wird die Person in jeder Audience, an die dieser Broadcast ging, als abgemeldet markiert, was als unsubscribedAt bei GET /audiences/{id}/contacts erscheint. Ihre anderen Audiences, ihr Kontakt und Mail, die einzeln an sie gesendet wird, sind nicht betroffen.