Broadcasts

const draft = {  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' },} const reach = await openemail.broadcasts.preview(draft)console.log(reach.recipients, reach.unsubscribed, reach.suppressed) const broadcast = await openemail.broadcasts.send(draft) let latest = await openemail.broadcasts.get(broadcast.id)while (['scheduled', 'queued', 'sending'].includes(latest.status)) {  await new Promise((resolve) => setTimeout(resolve, 5_000))  latest = await openemail.broadcasts.get(broadcast.id)} for await (const copy of openemail.emails.iterate({ broadcastId: broadcast.id })) {  console.log(copy.id, copy.status)} const later = await openemail.broadcasts.send({ ...draft, scheduledAt: 'P1D' })await openemail.broadcasts.cancel(later.id) const history = await openemail.broadcasts.list({ audienceId: draft.audienceIds[0] })console.log(latest.status, latest.counts.sent, history.items.length)

Ein Broadcast sendet eine Nachricht an alle in einer oder mehreren Audiences, als eigene Kopie für jede Person. 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. emails.list({ broadcastId }) listet sie auf. Die Kopien werden nicht im Ordner „Gesendet“ abgelegt, weil der Broadcast der Nachweis ist.

send löst sofort mit dem Broadcast als queued auf, oder als scheduled, wenn Sie scheduledAt übergeben, und der Versand läuft im Hintergrund. send braucht emails:send und audiences:read, preview braucht audiences:read, list, listAll, iterate und get brauchen emails:read, und cancel braucht emails:send.

subject, html und text werden für jede Person aus ihrem Kontakt ausgefüllt. {{firstName}} ist das erste Wort des Kontaktnamens, {{lastName}} der Rest davon, {{name}} der ganze Name, {{email}} die Adresse, an die die Kopie geht, und {{unsubscribeUrl}} der Link, der die Person abmeldet.

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, und jedes andere {{…}} bleibt genau so stehen, wie es geschrieben ist.

Übergeben Sie template statt html und text, um eine gespeicherte Vorlage zu senden. Dieselben fünf Werte erreichen sie als Props, aber nur die Props, die die Vorlage deklariert, sodass eine Vorlage, die firstName deklariert, ihn bekommt, und eine, die es nicht tut, nie deswegen abgelehnt wird. Alles in template.props geht an jede Kopie gleich.

Jede Kopie trägt die Ein-Klick-Abmelde-Header, mit denen ein Mailprogramm seine eigene Abmelde-Schaltfläche zeigen kann, was die großen Postfachanbieter von Massenmails verlangen. Ein html- oder text-Inhalt, der {{unsubscribeUrl}} nicht selbst platziert, bekommt eine einzeilige Fußzeile mit dem Link. Eine Vorlage wird genau so gesendet, wie sie ist, setzen Sie {{unsubscribeUrl}} also in die Vorlage.

Abmelden markiert die Person in jeder Audience, an die dieser Broadcast ging, als abgemeldet, und AudienceContactResource.unsubscribedAt zeigt es bei audiences.listContacts. Sie bleibt in der Audience und im Adressbuch, ihre anderen Audiences bleiben unberührt, und Mail, die einzeln an sie gesendet wird, geht weiterhin hinaus. Wenn Sie sie aus der Audience nehmen und wieder hinzufügen, ist sie neu angemeldet.

Ein Broadcast erreicht jeden Kontakt in mindestens einer der audienceIds, einmal, egal in wie vielen er ist. Er überspringt einen Kontakt, der sich von jeder dieser Audiences abgemeldet hat, in der er ist, und eine Adresse auf der Sperrliste nach einem Bounce oder einer Beschwerde oder weil jemand sie hinzugefügt hat. Ein Kontakt, der nach send, aber bevor der Versand ihn erreicht, zu einer der Audiences hinzukommt, ist dabei.

preview liefert dieselben Zahlen, ohne zu senden: recipients, unsubscribed und suppressed. Ein send, das niemanden erreichen würde, wirft 422 no_recipients.

get liest counts live aus den Kopien, fragen Sie es also während des Versands ab. status geht von scheduled oder queued zu sending und bleibt bei sent stehen, sobald jede übergebene Kopie hinausgegangen oder fehlgeschlagen ist. Er bleibt sending, solange noch Kopien warten, auch wenn completedAt schon sagt, dass die letzte Person erreicht wurde. failed heißt, dass der ganze Broadcast gestoppt ist, und lastError sagt warum: Von der from-Adresse kann nicht mehr gesendet werden, die Vorlage lässt sich nicht mehr auflösen, der Plan ist unterwegs ausgeschöpft, der Versand selbst ist wiederholt fehlgeschlagen, oder keine einzige Kopie ließ sich schreiben.

cancel stoppt einen Broadcast, der scheduled, queued oder sending ist. Niemand wird mehr hinzugefügt, und jede noch wartende Kopie wird abgebrochen, während hinausgegangene Kopien sich nicht zurückholen lassen. Sobald jede Kopie hinausgegangen ist, wirft cancel 409 broadcast_not_cancellable, und das Abbrechen eines abgebrochenen Broadcasts löst mit ihm so auf, wie er ist.

send, get und cancel lösen jeweils mit einem davon auf. list löst mit einer Seite davon auf, { items, hasMore, nextCursor }, die neueste zuerst, und listAll und iterate gehen jede Seite durch. preview löst mit einer BroadcastPreviewResource mit audienceIds, recipients, unsubscribed und suppressed auf.