Audiences
`audiences->list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `listContacts`, `addContact`, `addContacts`, `importContacts`, `removeContact` und `removeContacts`.
Jede Methode
$everyone = null; foreach ($client->audiences->listAll() as $audience) { if ($audience['builtin'] === 'default') { $everyone = $audience; }} $list = $client->audiences->create([ 'name' => 'Product updates', 'description' => 'Customers who asked to hear about releases',]); $client->contacts->create(['email' => '[email protected]', 'name' => 'Grace Hopper']);$client->audiences->addContact($list['id'], ['email' => '[email protected]']); $bulk = $client->audiences->addContacts($list['id'], ['emails' => ['[email protected]', '[email protected]']]); $imported = $client->audiences->importContacts($list['id'], [ 'contacts' => [['email' => '[email protected]', 'name' => 'Katherine Johnson']],]); $members = $client->audiences->listAllContacts($list['id'], q: 'grace', sort: 'added-newest', limit: 200); $growth = $client->audiences->growth(audienceIds: [$list['id']], days: 30); $client->audiences->update($list['id'], ['name' => 'Release notes']);$client->audiences->removeContact($list['id'], '[email protected]');$client->audiences->removeContacts($list['id'], ['emails' => ['[email protected]']]);$client->audiences->empty($list['id']);$client->audiences->delete($list['id']); echo $everyone['contactCount'] ?? 0, ' contacts in all', PHP_EOL;echo implode(', ', $bulk['missing']), ' ', $imported['created'], ' ', count($members), ' ', $growth['totals']['added'], PHP_EOL;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 selbst an, füllen und löschen sie. Verzweigen Sie über builtin statt über den Namen, den jeder ändern kann.
Ein Aufruf auf einer Audience nimmt deren id als erstes Argument, und removeContact nimmt die Adresse als zweites. Filter und Optionen sind benannte Argumente in camelCase (audienceIds:, offsetMinutes:), während ein Request-Body ein Array ist, dessen Schlüssel die Namen der API behalten (emails, contacts). Eine Antwort ist ein Array mit Schlüsseln im camelCase der API, $audience['contactCount'] liest also die Anzahl.
Senden Sie an eine oder mehrere Audiences mit $client->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. importContacts ist die Ausnahme. Es legt Kontakte an und braucht daher auch contacts:write.
addContact nimmt eine Adresse, die bereits ein Kontakt ist, und lehnt eine ab, die es nicht ist, mit einem 422 contact_not_found, geworfen als ValidationException. Speichern Sie sie zuerst mit $client->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, und der Client wiederholt ihn nach einem Netzwerkfehler.
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, geworfen als ConflictException mit isConflict() true. Löschen Sie den Kontakt, wenn der Kontakt gehen soll.
Antwort: eine Audience
list gibt eine Seite davon als OpenEmail\Result\Page zurück, mit items, hasMore und nextCursor, die Standard-Audience zuerst und der Rest neueste zuerst. Eine Seite enthält 25, sofern limit: nicht bis zu 100 anfordert. listAll gibt alle Audiences in einem einzigen Array zurück, und iterate gibt einen Generator zurück, der eine Audience nach der anderen liefert. get, create und update geben jeweils eine Audience zurück. listContacts gibt stattdessen eine Seite von Kontakten zurück, also die Kontakte selbst mit dem Datum, an dem jeder beigetreten ist, und keine Mitgliedschaftsdatensätze, mit listAllContacts und iterateContacts daneben.
idstring- Der dauerhafte Bezeichner, `aud_` gefolgt von 24 Hexzeichen. Namen sind nicht eindeutig, das hier gehört also in eine gespeicherte Konfiguration.
namestring- Beim Schreiben getrimmt, 1 bis 120 Zeichen. Zwei Audiences dürfen sich einen Namen teilen, denn eine Audience wird über ihre id adressiert.
descriptionstring or null- Freier Text für alle, die die Liste später lesen. null, wenn niemand etwas geschrieben hat, und `'description' => null` bei `update` löscht ihn.
builtinstring or null- `default` auf genau einer Zeile pro Workspace, der Audience, die jeden Kontakt enthält, und null bei jeder Audience, die jemand angelegt hat. Vergleichen Sie mit `'default'`, statt auf null zu prüfen, damit eine später hinzugefügte eingebaute Audience nicht für die Standard-Audience gehalten wird.
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.
lastContactAtstring or null- ISO 8601 UTC, wann der zuletzt beigetretene Kontakt dieser Audience beigetreten ist. null, solange die Audience leer ist.
createdAtstring- ISO 8601 UTC, wann die Audience angelegt wurde. Bestimmt die Listenreihenfolge nach der Standard-Audience.
updatedAtstring- ISO 8601 UTC, angehoben durch eine Umbenennung oder eine Beschreibungsänderung. Mitgliedschaftsänderungen rühren es nicht an.
Parameter: audiences->listContacts
limitint- Wie viele Kontakte pro Seite, eine ganze Zahl von 1 bis 200, Standard 50.
cursorstring- Der `nextCursor` der vorigen Seite, gesendet mit denselben `q:`, `source:`, `sort:` und `statuses:`. Ein Cursor, der einen Kontakt nennt, der nicht in dieser Audience ist, ergibt einen 400 `invalid_cursor`, geworfen als `InvalidRequestException`.
qstring- 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.
sourcestring- `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, um alle in der Audience zu erhalten.
sortstring- `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.
statusesstring or array- `['subscribed']` behält die Mitglieder, die sich nicht abgemeldet haben, und `['unsubscribed']` die, die es getan haben. Lassen Sie es weg, übergeben Sie ein leeres Array oder nennen Sie beide, um alle in der Audience zu erhalten. `OpenEmail\Constants\AudienceMemberStatuses` enthält die Werte, und der Client sendet sie mit Kommas verbunden als Query-Parameter `status`.
Antwort: ein Kontakt in einer Audience
listContacts gibt eine OpenEmail\Result\Page mit Kontakt-Arrays zurück, und listAllContacts und iterateContacts durchlaufen mit denselben benannten Argumenten alle Seiten. Jede Zeile ist ein Kontakt in der Form, die contacts->list zurückgibt, deren Felder auf der Seite Kontakte stehen, mit zwei Feldern mehr. Alle Seiten zu durchlaufen ist der Weg, eine Audience zu exportieren.
addedAtstring- ISO 8601 UTC, wann der Kontakt dieser Audience beigetreten ist. Einen Kontakt herauszunehmen und wieder hinzuzufügen, lässt ihn neu beginnen.
unsubscribedAtstring or null- ISO 8601 UTC, wann sich der Kontakt von einem Broadcast an diese Audience abgemeldet hat, oder null, 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
addContacts und removeContacts nehmen ein Array, dessen emails eine Liste von 1 bis 200 Adressen ist, und ändern eine Audience in einer Anfrage. addContacts legt nie einen Kontakt an. Eine Adresse, die keiner ist, kommt in missing zurück, und importContacts ist der Aufruf, der sie anlegt. Beide lassen sich gefahrlos wiederholen, der Client wiederholt sie daher nach einem Netzwerkfehler, und eine Wiederholung meldet dieselben Personen als bereits erledigt, statt zu scheitern.
Hinzufügen zur Standard-Audience ergibt added mit 0, weil jeder Kontakt schon darin ist, und removeContacts 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.
audienceIdstring- Die Audience, die der Aufruf geändert hat, in beiden Ergebnissen.
addedint- Im Ergebnis von `addContacts`: die neuen Mitgliedschaften aus diesem Aufruf.
unchangedint- Im Ergebnis von `addContacts`: Kontakte, die schon in der Audience waren. Für sie wurde nichts geschrieben.
removedint- Im Ergebnis von `removeContacts`: die Mitgliedschaften, die dieser Aufruf entfernt hat.
notInAudiencearray- Im Ergebnis von `removeContacts`: Kontakte, die nicht in der Audience waren, sodass mit ihnen nichts geschehen ist.
missingarray- Bei beiden: die Adressen, die in diesem Workspace keine Kontakte sind, kleingeschrieben und ohne Wiederholungen.
Importieren
importContacts ist der CSV-Import der Audience-Seite. Es nimmt ein Array, dessen contacts eine Liste von 1 bis 500 Arrays ist, jeweils 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, und ein Schlüssel, dem eines davon fehlt, wird mit 403 insufficient_scope abgelehnt, wobei isScopeMissing() an der Exception true ist.
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, der Client wiederholt den Aufruf daher nach einem Netzwerkfehler.
audienceIdstring- 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.
invalidarray- Die fehlerhaften Adressen, genau so, wie sie gesendet wurden.
Leeren
empty($id) nimmt in einer Anfrage jeden Kontakt aus einer Audience und gibt die Audience in ihrem jetzigen Zustand zurück, 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. Durchlaufen Sie daher zuerst listAllContacts, wenn Sie sie vielleicht zurückhaben wollen. Die Standard-Audience kann nicht geleert werden, und der Aufruf wird mit 409 audience_immutable abgelehnt. Der Client wiederholt empty nach einem Netzwerkfehler nicht, weil ein zweiter Aufruf mit removed gleich 0 gelingt. Ging eine Antwort verloren, lesen Sie die Audience mit get.
Wachstum
growth liest, wie viele Kontakte jeder Audience in einem Zeitraum bis jetzt beigetreten sind und wie viele sich darin abgemeldet haben, nach Tag, Stunde oder Minute. Es ist das Diagramm auf der Audiences-Seite. Es nimmt benannte Argumente, erfordert audiences:read und gibt ein Array zurück.
$growth = $client->audiences->growth( audienceIds: ['aud_9f2c4b7e1a0d63d84c5f2e7b'], days: 90, grain: 'day', offsetMinutes: intdiv((int) date('Z'), 60),); echo $growth['totals']['added'], ' joins since ', $growth['since'], PHP_EOL; foreach ($growth['series'] as $series) { echo $series['name'], ': ', $series['before'], ' before the window, ', $series['total'], ' now', PHP_EOL;}Eine Audience hält fest, wann jemand beigetreten ist, nie, wann er gegangen ist; jede Zahl 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
audienceIdsstring or array- Bis zu 50 Audience-ids, als Liste oder als ein kommagetrennter String, mit Kommas verbunden gesendet. Lassen Sie es weg oder übergeben Sie ein leeres Array, um alle Audiences zu erhalten. Eine id, die keine Audience in diesem Workspace ist, ergibt einen 404 `audience_not_found`, und mehr als 50 ergeben einen 422.
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.
grainstring- Die Größe jedes Buckets: `day` (Standard), `hour` oder `minute`.
offsetMinutesint- Der Abstand des Betrachters zu UTC in Minuten, -840 bis 840, damit Tages- und Stunden-Buckets an ihrer lokalen Grenze beginnen. Standardmäßig 0. `intdiv((int) date('Z'), 60)` ist der Offset der Zeitzone, auf die PHP eingestellt ist.
Antwort
sincestring- ISO 8601 UTC, der Beginn des ersten Buckets.
untilstring- ISO 8601 UTC, der Zeitpunkt der Abfrage.
totalsarray- `contacts` zählt jede Person einmal, egal in wie vielen Listen sie ist, und `memberships` addiert die Listen auf, sodass eine Person für jede gelesene Liste, in der sie ist, einmal zählt. `added` summiert die Beitritte im Zeitraum, `lists` ist die Zahl der gelesenen Audiences, und `busiest` ist der Bucket mit den meisten Beitritten oder null. `subscribed` zählt jede Person, die noch für mindestens eine der gelesenen Audiences angemeldet ist, und `unsubscribed` addiert die Abmeldungen innerhalb des Zeitraums.
seriesarray- Ein Eintrag pro Audience, größte zuerst und dann nach Namen: `id`, `name`, `builtin`, `total` Mitglieder jetzt, `subscribed` (die noch angemeldet sind), `before` (die vor `since` beigetreten sind), `added` (die innerhalb des Zeitraums beigetreten sind), `unsubscribed` (die sich darin abgemeldet haben) und `buckets`, älteste zuerst, jeweils ein Array mit `bucket`, `added` und `unsubscribed`. Hier ist `builtin` bei der Standard-Audience `true` und bei den übrigen `false`, nicht der String, den ein Audience-Array trägt. Aufgeführt werden nur Buckets 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.