Broadcasts

import time from openemail import openemailfrom openemail.types import BroadcastCreate draft: BroadcastCreate = {    '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 = openemail.broadcasts.preview(draft)print(reach['recipients'], reach['unsubscribed'], reach['suppressed']) broadcast = openemail.broadcasts.send(draft) latest = openemail.broadcasts.get(broadcast['id'])while latest['status'] in ('scheduled', 'queued', 'sending'):    time.sleep(5)    latest = openemail.broadcasts.get(broadcast['id']) for copy in openemail.broadcasts.iterate_recipients(broadcast['id']):    print(copy['email'], copy['status'], copy['opens'], copy['clicks']) bounced = openemail.broadcasts.list_recipients(broadcast['id'], filter='bounced')if bounced['items']:    content = openemail.broadcasts.get_recipient(broadcast['id'], bounced['items'][0]['emailId'])    print(content['subject'], content['bouncedAt']) stats = openemail.broadcasts.stats(broadcast['id'], grain='day')print(stats['totals']['opened'], stats['totals']['clicked'], stats['totals']['unsubscribed']) lately = openemail.broadcasts.stats(broadcast['id'], days=1)print(lately['window']['opened'] if lately['window'] else None) month = openemail.broadcasts.analytics(days=30)for row in month['broadcasts']:    print(row['subject'], row['sent'], row['opened']) later = openemail.broadcasts.send({**draft, 'scheduledAt': 'P1D'})openemail.broadcasts.cancel(later['id']) history = openemail.broadcasts.list(audience_id=draft['audienceIds'][0])print(latest['status'], latest['counts']['sent'], len(history['items']))

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 zurück, mit dem Broadcast als queued, 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, list_all, iterate, get, list_recipients, list_all_recipients, iterate_recipients, get_recipient, stats und analytics 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.list_contacts. 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 aus.

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

list_recipients gibt eine Seite der Personen zurück, an die ein Broadcast ging, eine Zeile pro Kopie, nach Adresse sortiert, als dict mit items, hasMore und nextCursor. list_all_recipients durchläuft alle Seiten und sammelt sie in einer einzigen Liste, und iterate_recipients liefert eine Kopie nach der anderen und holt die nächste Seite erst, wenn die Schleife danach fragt. limit reicht von 1 bis 200 mit Standardwert 50, und ein cursor geht mit demselben filter und q zurück.

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. 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.

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 offset_minutes östlich von UTC. Die Reihe zählt jede Person einmal, beim ersten Mal, als es ihr passierte, und ergibt deshalb in der Summe die Gesamtwerte.

get und cancel geben jeweils eine davon zurück, und send gibt eine SentBroadcastResource zurück, dieselben Felder plus replayed, das True ist, wenn die Antwort der Broadcast ist, den ein früherer Aufruf mit demselben Idempotency-Key angelegt hat. list gibt eine Seite davon zurück, ein dict mit items, hasMore und nextCursor, neueste zuerst, und list_all und iterate durchlaufen alle Seiten. preview gibt eine BroadcastPreviewResource mit audienceIds, recipients, unsubscribed und suppressed zurück. list_recipients gibt eine Seite von BroadcastRecipientResource-Zeilen zurück, get_recipient eine BroadcastRecipientContentResource und stats eine BroadcastStatsResource.

Jede Zeile von list_recipients, list_all_recipients und iterate_recipients. BroadcastRecipientContentResource aus get_recipient ergänzt subject, html und text.

• broadcasts.preview()Vollständige Referenz
• broadcasts.send()Vollständige Referenz
• broadcasts.list()Vollständige Referenz
• broadcasts.list_all()Vollständige Referenz
• broadcasts.iterate()Vollständige Referenz
• broadcasts.get()Vollständige Referenz
• broadcasts.list_recipients()Vollständige Referenz
• broadcasts.list_all_recipients()Vollständige Referenz
• broadcasts.iterate_recipients()Vollständige Referenz
• broadcasts.get_recipient()Vollständige Referenz
• broadcasts.stats()Vollständige Referenz
• broadcasts.analytics()Vollständige Referenz
• broadcasts.cancel()Vollständige Referenz