Broadcasts

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"}} reach = client.broadcasts.preview(draft)puts reach[:recipients], reach[:unsubscribed], reach[:suppressed] broadcast = client.broadcasts.send(draft) latest = client.broadcasts.get(broadcast[:id])while %w[scheduled queued sending].include?(latest[:status])  sleep 5  latest = client.broadcasts.get(broadcast[:id])end client.broadcasts.iterate_recipients(broadcast[:id]) do |copy|  puts copy[:email], copy[:status], copy[:opens], copy[:clicks]end bounced = client.broadcasts.list_recipients(broadcast[:id], filter: "bounced")bounced.items.each { |row| puts "#{row[:emailId]} #{row[:email]}" } copy = client.broadcasts.get_recipient(broadcast[:id], "msg_01dad25067bc4dac966d515d")puts copy[:subject], copy[:bouncedAt] stats = client.broadcasts.stats(broadcast[:id], grain: "day")puts stats.dig(:totals, :opened), stats.dig(:totals, :clicked), stats.dig(:totals, :unsubscribed) lately = client.broadcasts.stats(broadcast[:id], days: 1)puts lately.dig(:window, :opened) later = client.broadcasts.send(draft, scheduledAt: "P1D")client.broadcasts.cancel(later[:id]) history = client.broadcasts.list(audience_id: draft[:audienceIds].first)puts latest[:status], latest.dig(:counts, :sent), history.items.size month = client.broadcasts.analytics(days: 30)month[:broadcasts].each do |row|  puts row[:subject], row[:sent], row[:opened]end

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. list_recipients listet sie mit dem auf, was mit jeder geschah. Die Kopien werden nicht im Ordner „Gesendet“ abgelegt, weil der Broadcast der Nachweis ist.

send kehrt sofort mit dem Broadcast als queued zurück, oder als scheduled, wenn Sie scheduledAt: übergeben, und der Versand läuft im Hintergrund. send braucht emails:send und audiences:read, und preview braucht audiences:read. list, list_all, iterate, get, list_recipients, list_all_recipients, iterate_recipients, get_recipient, stats und analytics brauchen emails:read, und cancel braucht emails:send.

broadcast = client.broadcasts.send(  audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"],  from: "Acme <[email protected]>",  subject: "Doors open on Friday",  text: "Hi {{firstName|there}}, doors open at nine. Unsubscribe: {{unsubscribeUrl}}",  scheduledAt: Time.now + 3600,  idempotency_key: "doors-open-2026-10") puts broadcast[:id], broadcast[:status], broadcast[:replayed]

Die Felder eines Broadcasts sind Keyword-Argumente oder ein einzelner Hash und behalten die camelCase-Namen der API (audienceIds:, scheduledAt:). idempotency_key: und api_key: sind Optionen des Aufrufs und werden nie als Felder gesendet. Neben einem Hash übergebene Keywords werden in ihn eingemischt, send(draft, scheduledAt: "P1D") sendet also denselben Entwurf einen Tag später. scheduledAt: nimmt ein Time, ein DateTime, einen ISO-8601-String oder eine Dauer wie PT2H, und ein Time geht als UTC-Zeitpunkt hinaus. preview sendet von Ihren Angaben nur audienceIds und nimmt daher denselben Hash wie send. Eine Antwort ist ein Hash mit Symbol-Schlüsseln, broadcast[:status] liest also den Status.

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 ein gespeichertes Template zu senden, als Hash mit id und optional version, props und slots. Dieselben fünf Werte erreichen es als Props, aber nur die Props, die das Template deklariert, sodass ein Template, das firstName deklariert, ihn bekommt, und eines, das es nicht tut, nie deswegen abgelehnt wird. Alles in seinen 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 audiences.list_contacts zeigt es im unsubscribedAt ihrer Zeile, wie die Seite Audiences beschreibt. 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, löst 422 no_recipients als OpenEmail::ValidationError aus.

get liest counts live aus den Kopien. Fragen Sie es also während des Versands ab, mit sleep zwischen den Aufrufen, wie es das Beispiel oben tut. 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, das Template ließ sich nicht mehr auflösen, der Plan war mittendrin erschöpft, der Versand selbst schlug immer wieder fehl, oder keine einzige Kopie konnte geschrieben werden.

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, löst cancel 409 broadcast_not_cancellable als OpenEmail::ConflictError aus, und das Abbrechen eines abgebrochenen Broadcasts gibt ihn so zurück, wie er ist.

list_recipients gibt eine OpenEmail::Page mit den Personen zurück, an die ein Broadcast ging, eine Zeile pro Kopie, nach Adresse sortiert, mit items, has_more? und next_cursor. list_all_recipients durchläuft alle Seiten in ein einziges Array, und iterate_recipients übergibt eine Kopie nach der anderen an einen Block und holt die nächste Seite erst, wenn die Schleife danach fragt. Ohne Block gibt es einen Enumerator zurück. limit: reicht von 1 bis 200 mit Standardwert 50, und ein cursor: geht mit demselben filter: und q: zurück.

OpenEmail::BROADCAST_RECIPIENT_FILTERS benennt jeden Filter, und q: durchsucht Adresse und Name, ohne Groß- und Kleinschreibung zu beachten. Öffnungen und Klicks lassen Bild-Proxys und Link-Scanner außen vor und bleiben 0, wenn der Broadcast mit ausgeschaltetem Tracking hinausging.

get_recipient(id, email_id) gibt eine Kopie zurück: dieselbe Zeile, dazu subject, html und text genau so, wie diese Person sie erhalten hat, mit ausgefüllten Platzhaltern und ihrem eigenen Abmeldelink. Übergeben Sie die emailId einer Zeile als email_id. Das HTML stammt aus der Zeit, bevor das Öffnungs- und Klick-Tracking hinzugefügt wurde. Eine email_id, die keine Kopie dieses Broadcasts ist, löst 404 recipient_not_found aus, und ein unbekannter Broadcast löst 404 broadcast_not_found aus, beide als OpenEmail::NotFoundError.

stats gibt die Summen und eine Reihe zurück. totals zählt Kopien, die sent, delivered, bounced, complained und failed sind, mit pending für die noch wartenden, und Personen, die opened, clicked und unsubscribed sind, mit opens und clicks als Ereigniszahlen. series ist dünn besetzt und beginnt mit dem ältesten Eintrag, ein Intervall pro grain: (minute, hour oder day, Standardwert hour), in dem etwas geschah, aufgeteilt in der Zone offset_minutes: östlich von UTC. Übergeben Sie Time.now.utc_offset / 60 für die lokale Zone. Die Reihe zählt jede Person einmal, beim ersten Mal, als es ihr widerfuhr, sodass sie sich zu den Summen aufaddiert.

Übergeben Sie days: oder minutes: an stats, um auch zu lesen, was zuletzt geschah. window zählt dann, was darin zugestellt, als Bounce zurückgekommen, als Spam gemeldet, geöffnet, geklickt und abgemeldet wurde, und series behält nur dessen Intervalle, während totals weiterhin den ganzen Broadcast umfasst. Ohne beides ist window nil.

send, get und cancel geben jeweils einen davon zurück, einen Hash mit Symbol-Schlüsseln, und send ergänzt replayed. list gibt eine OpenEmail::Page davon zurück, neueste zuerst, und list_all und iterate durchlaufen alle Seiten. preview gibt einen Hash mit audienceIds, recipients, unsubscribed und suppressed zurück. list_recipients gibt eine OpenEmail::Page mit Empfängerzeilen zurück, get_recipient eine Zeile mit ihrem Inhalt und stats einen Hash mit broadcastId, grain, totals, window und series. analytics gibt einen Hash mit totals, series und einer Zeile pro Broadcast in broadcasts zurück. Zeiten sind Strings nach ISO 8601, die Time.iso8601 parst.

Jede Zeile von list_recipients, list_all_recipients und iterate_recipients, als Hash mit Symbol-Schlüsseln. Der Hash, den get_recipient zurückgibt, ergänzt subject, html und text.