PHP

Аудитории

`audiences->list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `listContacts`, `addContact`, `addContacts`, `importContacts`, `removeContact` и `removeContacts`.

Все методы

audiences.php

$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;

Аудитория является именованным списком контактов в этом рабочем пространстве. Каждый контакт с момента появления состоит во встроенной аудитории по умолчанию, и именно builtin обозначает эту строку. Остальные вы создаёте, наполняете и удаляете сами. Ветвитесь по builtin, а не по имени, которое может изменить кто угодно.

Вызов для одной аудитории принимает её идентификатор первым аргументом, а removeContact принимает адрес вторым. Фильтры и параметры являются именованными аргументами в camelCase (audienceIds:, offsetMinutes:), а тело запроса представляет собой один массив, ключи которого сохраняют имена из API (emails, contacts). Ответ является массивом с ключами в camelCase из API, поэтому $audience['contactCount'] читает количество.

Отправляйте одной или нескольким аудиториям через $client->broadcasts->send, описанный на странице о рассылках. Добавление контакта в аудиторию является записью в аудиторию, а не в контакт, поэтому проверяется только область audiences:write. Исключение составляет importContacts. Он создаёт контакты, поэтому ему нужна ещё и contacts:write.

addContact принимает адрес, который уже является контактом, и отклоняет тот, что им не является, с 422 contact_not_found, выбрасываемым как ValidationException. Сначала сохраните его через $client->contacts->create. Повторное добавление того же человека отвечает уже существующим членством с исходным addedAt, поэтому вызов безопасно повторять, и клиент повторяет его после сетевого сбоя.

Аудиторию по умолчанию можно переименовать и описать, как любую другую, но её нельзя удалить и из неё нельзя убирать контакты. И то и другое отклоняется с 409 audience_immutable, выбрасываемым как ConflictException с isConflict(), равным true. Если нужно убрать сам контакт, удалите контакт.

Ответ: аудитория

list возвращает одну страницу аудиторий как OpenEmail\Result\Page с items, hasMore и nextCursor: сначала аудиторию по умолчанию, а остальные от новых к старым. Страница содержит 25 аудиторий, если limit: не запросит до 100. listAll возвращает все аудитории одним массивом, а iterate возвращает Generator, который выдаёт аудитории по одной. get, create и update возвращают по одной аудитории. listContacts вместо этого возвращает страницу контактов: сами контакты с датой вступления каждого, а не записи о членстве, а рядом с ним есть listAllContacts и iterateContacts.

idstring: Долговечная ручка: `aud_` и следом 24 шестнадцатеричных символа. Имена не уникальны, так что в сохранённой конфигурации место именно этому.
namestring: Обрезается при записи, от 1 до 120 символов. Две аудитории могут носить одно имя, потому что к аудитории обращаются по её идентификатору.
descriptionstring or null: Произвольный текст для того, кто будет читать список позже. null, если никто ничего не написал, а `'description' => null` в `update` его очищает.
builtinstring or null: `default` ровно у одной строки в каждом рабочем пространстве, у аудитории, в которой состоят все контакты, и null у каждой аудитории, созданной кем-то. Сравнивайте его с `'default'`, а не проверяйте на null, чтобы встроенную аудиторию, добавленную позже, не приняли за аудиторию по умолчанию.
contactCountint: Сколько контактов в аудитории, посчитано в момент чтения, а не взято из кэша. Два чтения по обе стороны от `contacts->create` разойдутся на единицу.
lastContactAtstring or null: ISO 8601 в UTC: когда в эту аудиторию вступил контакт, вступивший последним. null, пока аудитория пуста.
createdAtstring: ISO 8601 в UTC: когда аудитория была создана. Определяет порядок списка после аудитории по умолчанию.
updatedAtstring: ISO 8601 в UTC, обновляется при переименовании или изменении описания. Изменения членства его не затрагивают.

Параметры: audiences->listContacts

limitint: Сколько контактов на странице: целое число от 1 до 200, по умолчанию 50.
cursorstring: `nextCursor` предыдущей страницы, отправляемый с теми же `q:`, `source:`, `sort:` и `statuses:`. Курсор, который называет контакт не из этой аудитории, даёт 400 `invalid_cursor`, выбрасываемый как `InvalidRequestException`.
qstring: Ищет по имени и адресу, до 200 символов. Если на первой странице ничто не совпадает точно, вместо этого возвращаются близкие написания, и следующие страницы продолжают искать так же.
sourcestring: `manual` для контактов, которые кто-то сохранил намеренно, `auto` для тех, что записал композер приложения. Не указывайте, чтобы получить всех в аудитории.
sortstring: `last-heard-newest` (по умолчанию) и `last-heard-oldest` сортируют по `lastSeenAt`, а контакты, которым никогда не писали, идут последними в первом случае и первыми во втором. `added-newest` и `added-oldest` сортируют по времени вступления каждого контакта в эту аудиторию, а `name` не учитывает регистр и сортирует контакт без имени по его адресу.
statusesstring or array: `['subscribed']` оставляет участников, которые не отписались, а `['unsubscribed']` тех, кто отписался. Чтобы получить всех в аудитории, не указывайте параметр, передайте пустой массив или назовите оба значения. `OpenEmail\Constants\AudienceMemberStatuses` содержит значения, и клиент отправляет их через запятую как параметр запроса `status`.

Ответ: контакт в аудитории

listContacts возвращает OpenEmail\Result\Page из массивов контактов, а listAllContacts и iterateContacts обходят все страницы с теми же именованными аргументами. Каждая строка является контактом в той форме, которую возвращает contacts->list (её поля описаны на странице о контактах), плюс ещё два поля. Обход всех страниц и есть способ экспортировать аудиторию.

addedAtstring: ISO 8601 в UTC: когда контакт вступил в эту аудиторию. Если убрать контакт и добавить снова, отсчёт начнётся заново.
unsubscribedAtstring or null: ISO 8601 в UTC: когда контакт отписался от рассылки, отправленной этой аудитории, или null, пока он подписан. Отписавшийся контакт остаётся в аудитории, а рассылки этой аудитории его пропускают. Если убрать его и добавить снова, он снова становится подписанным.

Массовое добавление и удаление

addContacts и removeContacts принимают массив, в котором emails является списком от 1 до 200 адресов, и меняют одну аудиторию одним запросом. addContacts никогда не создаёт контакт. Адрес, который не является контактом, возвращается в missing, а создаёт контакты вызов importContacts. Оба безопасно повторять, поэтому клиент повторяет их после сетевого сбоя, а повтор сообщает о тех же людях как об уже обработанных, а не завершается ошибкой.

Добавление в аудиторию по умолчанию отвечает added, равным 0, потому что все контакты уже в ней, а removeContacts для неё отклоняется с 409 audience_immutable. Человек, которого убрали из аудитории, остаётся в адресной книге, в аудитории по умолчанию и в других своих аудиториях.

audienceIdstring: Аудитория, которую изменил вызов, в обоих результатах.
addedint: В результате `addContacts`: новые членства, созданные этим вызовом.
unchangedint: В результате `addContacts`: контакты, которые уже были в аудитории. Для них ничего не записано.
removedint: В результате `removeContacts`: членства, которые убрал этот вызов.
notInAudiencearray: В результате `removeContacts`: контакты, которых не было в аудитории, поэтому с ними ничего не произошло.
missingarray: В обоих: адреса, которые не являются контактами в этом рабочем пространстве, в нижнем регистре и без повторов.

Импорт

importContacts соответствует импорту CSV на странице аудитории. Принимает массив, в котором contacts является списком от 1 до 500 массивов, каждый с email и необязательным name. Каждый корректный адрес становится контактом, если ещё им не является, и каждый попадает в аудиторию. Длинный список отправляйте несколькими вызовами. Нужны audiences:write и contacts:write, а ключ без любой из них отклоняется с 403 insufficient_scope, при этом у исключения isScopeMissing() равно true.

Адрес, который уже является контактом, используется повторно и сохраняет своё имя, а name здесь лишь заполняет пустое имя. Новый контакт сохраняется как manual и тоже вступает в аудиторию по умолчанию, а адрес, удалённый из книги, возвращается. Повторная передача тех же строк ничего не создаёт дважды, поэтому клиент повторяет вызов после сетевого сбоя.

audienceIdstring: Аудитория, в которую попали строки.
createdint: Новые контакты, сохранённые этим вызовом.
addedint: Новые членства в этой аудитории, включая контакты, которые уже существовали и ещё не были в ней.
skippedint: Строки, которые не были импортированы, потому что адрес был некорректным.
invalidarray: Некорректные адреса ровно в том виде, в каком они были отправлены.

Очистка

empty($id) одним запросом убирает все контакты из одной аудитории и возвращает аудиторию в её текущем виде с contactCount, равным 0, плюс removed, число убранных членств. Аудитория сохраняет идентификатор, имя и описание, а каждый контакт остаётся в адресной книге и в других своих аудиториях.

Это нельзя отменить, и нигде не записывается, кто был в списке, поэтому, если список может понадобиться снова, сначала обойдите listAllContacts. Аудиторию по умолчанию нельзя очистить, и такой вызов отклоняется с 409 audience_immutable. Клиент не повторяет empty после сетевого сбоя, потому что второй вызов завершится успешно с removed, равным 0. Если ответ потерялся, прочитайте аудиторию через get.

Рост

growth читает, сколько контактов вступило в каждую аудиторию за окно, которое заканчивается сейчас, и сколько отписалось в нём, по дням, часам или минутам. Это график на странице аудиторий. Принимает именованные аргументы, требует audiences:read и возвращает один массив.

audience_growth.php

$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;}

Аудитория записывает, когда человек вступил, и никогда не записывает, когда он вышел, так что каждое число считает людей, которые и сегодня в списке, по дате вступления, и линия никогда не идёт вниз. Контакт, который вступил, а потом вышел, не входит ни в одно из чисел.

Параметры

audienceIdsstring or array: До 50 идентификаторов аудиторий в виде списка или одной строки через запятую, которые отправляются через запятую. Чтобы получить все аудитории, не указывайте параметр или передайте пустой массив. Идентификатор, который не является аудиторией этого рабочего пространства, даёт 404 `audience_not_found`, а больше 50 даёт 422.
daysint: Насколько далеко назад простирается окно, от 1 до 1095. Равно 30, если не задано ни `days:`, ни `minutes:`.
minutesint: Окно в минутах, от 1 до 1576800, для окна короче суток. Если заданы оба, имеет приоритет над `days:`.
grainstring: Размер каждого интервала: `day` (по умолчанию), `hour` или `minute`.
offsetMinutesint: Смещение зрителя относительно UTC в минутах, от -840 до 840, чтобы интервалы по дням и часам начинались на местной границе. По умолчанию 0. `intdiv((int) date('Z'), 60)` даёт смещение часового пояса, настроенного в PHP.

Ответ

sincestring: ISO 8601 в UTC, начало первого интервала.
untilstring: ISO 8601 в UTC, момент чтения.
totalsarray: `contacts` считает каждого человека один раз, в скольких бы списках он ни состоял, а `memberships` суммирует по спискам, так что человек учитывается один раз за каждый прочитанный список, в котором он есть. `added` суммирует вступления в окне, `lists` показывает, сколько аудиторий прочитано, а `busiest` является интервалом с наибольшим числом вступлений или null. `subscribed` считает каждого человека, который всё ещё подписан хотя бы на одну из прочитанных аудиторий, а `unsubscribed` суммирует отписки внутри окна.
seriesarray: По одной записи на аудиторию, сначала крупнейшие, затем по имени: `id`, `name`, `builtin`, `total` (участников сейчас), `subscribed` (всё ещё подписанные), `before` (вступившие до `since`), `added` (вступившие внутри окна), `unsubscribed` (отписавшиеся внутри окна) и `buckets`, от старых к новым, каждый в виде массива с `bucket`, `added` и `unsubscribed`. Здесь `builtin` равен `true` у аудитории по умолчанию и `false` у остальных, а не строка, которую несёт массив аудитории. Перечисляются только интервалы со вступлением или отпиской, с ключами вида `YYYY-MM-DD`, `YYYY-MM-DDTHH` или `YYYY-MM-DDTHH:MM` в местном времени по смещению.