Audiences
`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` und `remove_contacts`.
Jede Methode
from openemail import openemail audiences = openemail.audiences.list_all()everyone = next((audience for audience in audiences if audience['builtin'] == 'default'), None) created = openemail.audiences.create({ 'name': 'Product updates', 'description': 'Customers who asked to hear about releases',})audience_id = created['id'] openemail.contacts.create({'email': '[email protected]', 'name': 'Grace Hopper'})openemail.audiences.add_contact(audience_id, {'email': '[email protected]'}) bulk = openemail.audiences.add_contacts(audience_id, { 'emails': ['[email protected]', '[email protected]'],}) imported = openemail.audiences.import_contacts(audience_id, { 'contacts': [{'email': '[email protected]', 'name': 'Katherine Johnson'}],}) members = openemail.audiences.list_all_contacts( audience_id, q='grace', sort='added-newest', limit=200,) growth = openemail.audiences.growth(audience_ids=[audience_id], days=30) openemail.audiences.update(audience_id, {'name': 'Release notes'})openemail.audiences.remove_contact(audience_id, '[email protected]')openemail.audiences.remove_contacts(audience_id, {'emails': ['[email protected]']})openemail.audiences.empty(audience_id)openemail.audiences.delete(audience_id) print(everyone['contactCount'] if everyone else None, bulk['missing'], imported['created'])print(len(members), growth['totals']['added'])Eine Audience ist eine benannte Kontaktliste in diesem Workspace. Jeder Kontakt gehört ab dem Moment seiner Existenz zur eingebauten Standard-Audience, und builtin ist das, was diese Zeile benennt; die übrigen legen Sie an, füllen Sie und löschen Sie selbst. Verzweigen Sie auf builtin statt auf den Namen, den jeder ändern kann.
Senden Sie an eine oder mehrere Audiences mit openemail.broadcasts.send, auf der Seite Broadcasts. Einen Kontakt in eine Audience zu stellen ist ein Schreibvorgang an der Audience, nicht am Kontakt, deshalb wird nur audiences:write geprüft. import_contacts ist die Ausnahme: Es legt Kontakte an und braucht daher auch contacts:write.
add_contact nimmt eine Adresse, die bereits ein Kontakt ist, und lehnt eine ab, die es nicht ist, mit 422 contact_not_found. Speichern Sie sie zuerst mit openemail.contacts.create. Wer jemanden zweimal hinzufügt, erhält die bereits bestehende Mitgliedschaft samt ihrem ursprünglichen addedAt zurück; der Aufruf lässt sich also gefahrlos wiederholen.
Die Standard-Audience lässt sich wie jede andere umbenennen und beschreiben, aber sie lässt sich nicht löschen und nicht ausdünnen. Beides wird mit 409 audience_immutable abgelehnt. Löschen Sie den Kontakt, wenn der Kontakt gehen soll.
Antwort: AudienceResource
list gibt eine Seite davon zurück, ein dict mit items, hasMore und nextCursor, die Standard-Audience zuerst und die übrigen neueste zuerst, und list_all und iterate durchlaufen alle Seiten. get, create und update geben jeweils eine zurück. list_contacts gibt stattdessen eine Seite AudienceContactResource zurück, die Kontakte selbst mit dem Datum, an dem jeder beigetreten ist, statt Mitgliedschaftsdatensätzen, mit list_all_contacts und iterate_contacts daneben.
idstr- Der dauerhafte Bezeichner, `aud_` gefolgt von 24 Hexzeichen. Namen sind nicht eindeutig, das hier gehört also in eine gespeicherte Konfiguration.
namestr- Beim Schreiben getrimmt, 1 bis 120 Zeichen. Zwei Audiences dürfen sich einen Namen teilen, denn eine Audience wird über ihre id adressiert.
descriptionstr | None- Freier Text für alle, die die Liste später lesen. `None`, wenn niemand etwas geschrieben hat, und ein ausdrückliches `None` bei `update` löscht ihn.
builtinAudienceBuiltin | str | None- `default` bei genau einer Zeile pro Workspace, der Audience, die jeden Kontakt enthält, und `None` bei jeder Audience, die jemand angelegt hat. Der Typ bleibt offen, mit `str` neben dem Literal, damit eine später hinzugefügte eingebaute Audience keinen Code bricht, der gegen diesen Typ typisiert ist.
contactCountint- Wie viele Kontakte in der Audience sind, gezählt im Moment des Lesens und nicht gecacht. Zwei Lesevorgänge beiderseits eines `contacts.create` weichen um eins voneinander ab.
lastContactAtstr | None- ISO-8601 UTC, wann der zuletzt beigetretene Kontakt dieser Audience beigetreten ist. `None`, solange die Audience leer ist.
createdAtstr- ISO-8601 UTC, wann die Audience angelegt wurde. Bestimmt die Listenreihenfolge nach der Standard-Audience.
updatedAtstr- ISO-8601 UTC, angehoben durch eine Umbenennung oder eine Beschreibungsänderung. Mitgliedschaftsänderungen rühren es nicht an.
Parameter: audiences.list_contacts
limitint- Wie viele Kontakte pro Seite: eine ganze Zahl von 1 bis 200, Standardwert 50.
cursorstr- Der `nextCursor` der vorigen Seite, gesendet mit denselben `q`, `source` und `sort`. Ein Cursor, der einen Kontakt nennt, der nicht in dieser Audience ist, ergibt ein 400 `invalid_cursor`.
qstr- Durchsucht Name und Adresse, bis zu 200 Zeichen. Passt auf der ersten Seite nichts genau, kommen stattdessen ähnliche Schreibweisen zurück, und die folgenden Seiten suchen auf dieselbe Weise weiter.
sourceContactSource- `'manual'` für die Kontakte, die jemand bewusst gespeichert hat, `'auto'` für die, die der Composer der App erfasst hat. Lassen Sie es weg für alle in der Audience.
sortAudienceMemberSort- `'last-heard-newest'` (Standard) und `'last-heard-oldest'` richten sich nach `lastSeenAt`, und Kontakte, an die nie Mail ging, stehen im ersten Fall am Ende und im zweiten am Anfang. `'added-newest'` und `'added-oldest'` richten sich danach, wann jeder Kontakt dieser Audience beigetreten ist, und `'name'` ignoriert Groß- und Kleinschreibung und sortiert einen Kontakt ohne Namen nach seiner Adresse.
statusesSequence[AudienceMemberStatus]- `['subscribed']` behält die Mitglieder, die sich nicht abgemeldet haben, und `['unsubscribed']` die, die es getan haben. Lass es weg, oder nenne beide, für alle in der Audience. `AUDIENCE_MEMBER_STATUSES` enthält die Werte.
Antwort: AudienceContactResource
list_contacts gibt eine Page[AudienceContactResource] zurück, und list_all_contacts und iterate_contacts gehen mit denselben Optionen alle Seiten durch. Jede Zeile ist eine ContactResource, deren Felder auf der Seite Kontakte stehen, mit zwei Feldern mehr. Alle Seiten durchzugehen ist der Weg, eine Audience zu exportieren.
addedAtstr- ISO-8601 UTC, wann der Kontakt dieser Audience beigetreten ist. Einen Kontakt herauszunehmen und wieder hinzuzufügen, lässt ihn neu beginnen.
unsubscribedAtstr | None- ISO-8601 UTC, wann sich der Kontakt von einem Broadcast an diese Audience abgemeldet hat, oder `None`, solange er angemeldet ist. Ein abgemeldeter Kontakt bleibt in der Audience, und Broadcasts an sie überspringen ihn. Wenn Sie ihn herausnehmen und wieder hinzufügen, ist er neu angemeldet.
Hinzufügen und Entfernen in Massen
add_contacts und remove_contacts nehmen {'emails': [...]}, 1 bis 200 Adressen, und ändern eine Audience in einer Anfrage. add_contacts legt nie einen Kontakt an: Eine Adresse, die keiner ist, kommt in missing zurück, und import_contacts ist der Aufruf, der sie anlegt. Beide lassen sich sicher wiederholen, ein erneuter Versuch nach einem Timeout meldet dieselben Personen also als bereits erledigt, statt zu scheitern.
Hinzufügen zur Standard-Audience ergibt 'added': 0, weil jeder Kontakt schon darin ist, und remove_contacts darauf wird mit 409 audience_immutable abgelehnt. Wer aus einer Audience genommen wird, bleibt im Adressbuch, in der Standard-Audience und in seinen anderen Audiences.
audienceIdstr- Die Audience, die der Aufruf geändert hat, in beiden Ergebnissen.
addedint- Bei `AudienceBatchAddResource`: die neuen Mitgliedschaften aus diesem Aufruf.
unchangedint- Bei `AudienceBatchAddResource`: Kontakte, die schon in der Audience waren. Für sie wurde nichts geschrieben.
removedint- Bei `AudienceBatchRemoveResource`: die Mitgliedschaften, die dieser Aufruf entfernt hat.
notInAudiencelist[str]- Bei `AudienceBatchRemoveResource`: Kontakte, die nicht in der Audience waren, sodass mit ihnen nichts geschehen ist.
missinglist[str]- Bei beiden: die Adressen, die in diesem Workspace keine Kontakte sind, kleingeschrieben und ohne Wiederholungen.
Importieren
import_contacts ist der CSV-Import der Audience-Seite. Es nimmt {'contacts': [...]} entgegen, 1 bis 500 Zeilen, jede mit einer email und einem optionalen name: Jede wohlgeformte Adresse wird zum Kontakt, falls sie noch keiner ist, und jede landet in der Audience. Senden Sie eine längere Liste in mehreren Aufrufen. Es erfordert audiences:write und contacts:write.
Eine Adresse, die schon ein Kontakt ist, wird wiederverwendet und behält ihren Namen, und ein name hier füllt nur einen leeren. Ein neuer Kontakt wird als manual gespeichert und tritt auch der Standard-Audience bei, und eine Adresse, die aus dem Adressbuch gelöscht wurde, kommt zurück. Dieselben Zeilen erneut zu senden legt nichts doppelt an.
audienceIdstr- Die Audience, in die die Zeilen gegangen sind.
createdint- Neue Kontakte, die dieser Aufruf gespeichert hat.
addedint- Neue Mitgliedschaften in dieser Audience, einschließlich Kontakten, die schon existierten und noch nicht darin waren.
skippedint- Zeilen, die nicht importiert wurden, weil die Adresse fehlerhaft war.
invalidlist[str]- Die fehlerhaften Adressen, genau so, wie sie gesendet wurden.
Leeren
empty(id) nimmt in einer Anfrage jeden Kontakt aus einer Audience und gibt eine EmptiedAudienceResource zurück: die Audience in ihrem jetzigen Zustand, mit contactCount bei 0, plus removed, der Zahl der entfernten Mitgliedschaften. Die Audience behält ihre ID, ihren Namen und ihre Beschreibung, und jeder Kontakt bleibt im Adressbuch und in seinen anderen Audiences.
Das lässt sich nicht rückgängig machen, und nichts hält fest, wer in der Liste war; gehen Sie daher zuerst list_all_contacts durch, wenn Sie sie vielleicht zurückhaben wollen. Die Standard-Audience kann nicht geleert werden, und der Aufruf wird mit 409 audience_immutable abgelehnt.
Wachstum
growth() liest, wie viele Kontakte jeder Audience in einem Zeitraum bis jetzt beigetreten sind, nach Tag, Stunde oder Minute, das Diagramm auf der Audiences-Seite. Es erfordert audiences:read und gibt eine AudienceGrowthResource zurück.
Eine Audience hält fest, wann jemand beigetreten ist, nie, wann er gegangen ist; jede Beitrittszahl zählt also die Personen, die heute noch in der Liste sind, nach ihrem Beitrittsdatum, und eine Linie fällt nie. Ein Kontakt, der beigetreten ist und später gegangen ist, steckt in keiner der Zahlen.
Parameter
audience_idsSequence[str]- Bis zu 50 Audience-IDs, mit Kommas verbunden gesendet. Lassen Sie es für alle Audiences weg. Eine ID, die keine Audience in diesem Workspace ist, ergibt ein 404 `audience_not_found`.
daysint- Wie weit der Zeitraum zurückreicht, 1 bis 1095. Es sind 30, wenn weder `days` noch `minutes` angegeben ist.
minutesint- Der Zeitraum in Minuten, 1 bis 1576800, für einen Zeitraum unter einem Tag. Hat Vorrang vor `days`, wenn beide angegeben sind.
grainTrackingGrain- Die Größe jedes Buckets: `day` (Standard), `hour` oder `minute`.
offset_minutesint- Der Abstand des Betrachters zu UTC in Minuten, -840 bis 840, damit Tages- und Stunden-Buckets an seiner lokalen Grenze beginnen. Standardmäßig 0.
Antwort
sincestr- ISO-8601 UTC, der Beginn des ersten Buckets.
untilstr- ISO-8601 UTC, der Zeitpunkt der Abfrage.
totalsAudienceGrowthTotals- `contacts` zählt jede Person einmal, egal in wie vielen Listen sie ist, und `memberships` addiert die Listen, eine Person zählt also einmal für jede gelesene Liste, die sie enthält. `subscribed` zählt, jeweils einmal, die Personen, die noch mindestens eine der gelesenen Listen abonniert haben. `added` summiert die Beitritte im Zeitraum, `unsubscribed` die Abmeldungen darin, `lists` gibt an, wie viele Audiences gelesen wurden, und `busiest` ist das Intervall mit den meisten Beitritten, oder `None`.
serieslist[AudienceGrowthSeries]- Ein Eintrag pro Audience, größte zuerst: `id`, `name`, `builtin` (`True` bei der Standard-Audience), `total` Mitglieder jetzt, `subscribed` (diejenigen davon, die sich nicht abgemeldet haben), `before` (die vor `since` beigetreten sind), `added` (die innerhalb des Zeitraums beigetreten sind), `unsubscribed` (die sich darin abgemeldet haben) und `buckets`, jeweils ein dict aus `bucket`, `added` und `unsubscribed`. Aufgeführt werden nur Intervalle mit einem Beitritt oder einer Abmeldung, mit Schlüsseln `YYYY-MM-DD`, `YYYY-MM-DDTHH` oder `YYYY-MM-DDTHH:MM` in der Ortszeit des Offsets.
Referenz
audiences.list()Vollständige Referenzaudiences.list_all()Vollständige Referenzaudiences.iterate()Vollständige Referenzaudiences.get()Vollständige Referenzaudiences.create()Vollständige Referenzaudiences.update()Vollständige Referenzaudiences.delete()Vollständige Referenzaudiences.empty()Vollständige Referenzaudiences.growth()Vollständige Referenzaudiences.list_contacts()Vollständige Referenzaudiences.list_all_contacts()Vollständige Referenzaudiences.iterate_contacts()Vollständige Referenzaudiences.add_contact()Vollständige Referenzaudiences.add_contacts()Vollständige Referenzaudiences.import_contacts()Vollständige Referenzaudiences.remove_contact()Vollständige Referenzaudiences.remove_contacts()Vollständige Referenz