Аудитории
`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` и `remove_contacts`.
Все методы
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'])Аудитория представляет собой именованный список контактов в этом рабочем пространстве. Каждый контакт с момента появления входит во встроенную аудиторию по умолчанию, и именно её обозначает builtin; остальные вы создаёте, наполняете и удаляете сами. Ветвитесь по builtin, а не по имени, которое может изменить кто угодно.
Отправляйте одной или нескольким аудиториям через openemail.broadcasts.send на странице Broadcasts. Добавление контакта в аудиторию является записью в аудиторию, а не в контакт, поэтому проверяется только audiences:write. Исключение составляет import_contacts: он создаёт контакты, поэтому ему нужен ещё и contacts:write.
add_contact принимает адрес, который уже является контактом, и отклоняет тот, который им не является, с 422 contact_not_found. Сначала сохраните его через openemail.contacts.create. Повторное добавление отвечает уже существующим членством, несущим свой исходный addedAt, так что вызов безопасно повторять.
Аудиторию по умолчанию можно переименовать и описать, как любую другую, но её нельзя удалить и нельзя проредить. И то и другое отклоняется с 409 audience_immutable. Удаляйте контакт, когда имеете в виду именно уход контакта.
Ответ: AudienceResource
list возвращает одну страницу таких объектов, словарь с items, hasMore и nextCursor, где первой идёт аудитория по умолчанию, а остальные от новых к старым, а list_all и iterate проходят все страницы. get, create и update возвращают по одному объекту. list_contacts вместо этого возвращает страницу AudienceContactResource, то есть сами контакты с датой вступления каждого, а не записи о членстве, и рядом с ним стоят list_all_contacts и iterate_contacts.
idstr- Долговечная ручка: `aud_` и следом 24 шестнадцатеричных символа. Имена не уникальны, так что в сохранённой конфигурации место именно этому.
namestr- Обрезается при записи, от 1 до 120 символов. Две аудитории могут носить одно имя, потому что к аудитории обращаются по её идентификатору.
descriptionstr | None- Свободный текст для того, кто будет читать список позже. `None`, когда никто ничего не написал, а явный `None` в `update` очищает его.
builtinAudienceBuiltin | str | None- `default` ровно у одной строки на рабочее пространство, у аудитории, которая содержит все контакты, и `None` у каждой аудитории, созданной кем-то. Тип остаётся открытым, с `str` рядом с литералом, чтобы встроенная аудитория, добавленная позже, не сломала код, типизированный под этот вариант.
contactCountint- Сколько контактов в аудитории, посчитано в момент чтения, а не взято из кэша. Два чтения по обе стороны от `contacts.create` разойдутся на единицу.
lastContactAtstr | None- ISO-8601 UTC, когда в эту аудиторию вступил контакт, вступивший последним. `None`, пока аудитория пуста.
createdAtstr- ISO-8601 UTC, когда аудитория была создана. Задаёт порядок списка после аудитории по умолчанию.
updatedAtstr- ISO-8601 UTC, обновляется при переименовании или смене описания. Изменения состава его не трогают.
Параметры: audiences.list_contacts
limitint- Сколько контактов на странице: целое число от 1 до 200, по умолчанию 50.
cursorstr- `nextCursor` предыдущей страницы, отправленный с теми же `q`, `source` и `sort`. Курсор, указывающий на контакт не из этой аудитории, даёт 400 `invalid_cursor`.
qstr- Ищет по имени и адресу, до 200 символов. Если на первой странице ничто не совпадает точно, вместо этого возвращаются близкие написания, и следующие страницы продолжают искать так же.
sourceContactSource- `'manual'` для контактов, которые кто-то сохранил намеренно, `'auto'` для тех, что записал редактор писем в приложении. Не указывайте, чтобы получить всех в аудитории.
sortAudienceMemberSort- `'last-heard-newest'` (по умолчанию) и `'last-heard-oldest'` идут по `lastSeenAt`, и контакты, которым никогда не писали, оказываются в конце в первом случае и в начале во втором. `'added-newest'` и `'added-oldest'` идут по дате вступления каждого контакта в эту аудиторию, а `'name'` не учитывает регистр и сортирует контакт без имени по его адресу.
statusesSequence[AudienceMemberStatus]- `['subscribed']` оставляет участников, которые не отписались, а `['unsubscribed']` тех, кто отписался. Не указывайте его или укажите оба, чтобы получить всех в аудитории. Значения лежат в `AUDIENCE_MEMBER_STATUSES`.
Ответ: AudienceContactResource
list_contacts возвращает Page[AudienceContactResource], а list_all_contacts и iterate_contacts проходят все страницы с теми же параметрами. Каждая строка является ContactResource, поля которого описаны на странице «Контакты», плюс ещё два. Обход всех страниц и есть способ экспортировать аудиторию.
addedAtstr- ISO-8601 UTC, когда контакт вступил в эту аудиторию. Если убрать контакт и добавить его снова, отсчёт начнётся заново.
unsubscribedAtstr | None- ISO-8601 UTC, когда контакт отписался от рассылки этой аудитории, или `None`, пока он подписан. Отписавшийся контакт остаётся в аудитории, а рассылки ей его пропускают. Если убрать его и добавить снова, он снова будет подписан.
Массовое добавление и удаление
add_contacts и remove_contacts принимают {'emails': [...]}, от 1 до 200 адресов, и меняют одну аудиторию одним запросом. add_contacts никогда не создаёт контакт: адрес, который не является контактом, возвращается в missing, а создаёт их вызов import_contacts. Оба безопасно повторять, так что повторная попытка после тайм-аута сообщает о тех же людях как об уже обработанных, а не завершается ошибкой.
Добавление в аудиторию по умолчанию отвечает 'added': 0, потому что каждый контакт уже в ней, а remove_contacts для неё отклоняется с 409 audience_immutable. Человек, убранный из аудитории, остаётся в адресной книге, в аудитории по умолчанию и в своих других аудиториях.
audienceIdstr- Аудитория, которую изменил вызов, в обоих результатах.
addedint- В `AudienceBatchAddResource`: новые членства, созданные этим вызовом.
unchangedint- В `AudienceBatchAddResource`: контакты, которые уже были в аудитории. Для них ничего не записывалось.
removedint- В `AudienceBatchRemoveResource`: членства, убранные этим вызовом.
notInAudiencelist[str]- В `AudienceBatchRemoveResource`: контакты, которых не было в аудитории, так что с ними ничего не произошло.
missinglist[str]- В обоих: адреса, которые не являются контактами в этом рабочем пространстве, в нижнем регистре и без повторов.
Импорт
import_contacts соответствует импорту CSV со страницы аудитории. Он принимает {'contacts': [...]}, от 1 до 500 строк, каждая с email и необязательным name: каждый корректный адрес становится контактом, если ещё им не является, и все попадают в аудиторию. Более длинный список отправляйте несколькими вызовами. Требует audiences:write и contacts:write.
Адрес, который уже является контактом, используется повторно и сохраняет своё имя, а name здесь заполняет только пустое. Новый контакт сохраняется как manual и тоже вступает в аудиторию по умолчанию, а адрес, удалённый из книги, возвращается. Повторная отправка тех же строк ничего не создаёт дважды.
audienceIdstr- Аудитория, в которую попали строки.
createdint- Новые контакты, сохранённые этим вызовом.
addedint- Новые членства в этой аудитории, включая контакты, которые уже существовали и ещё не были в ней.
skippedint- Строки, которые не были импортированы, потому что адрес был некорректным.
invalidlist[str]- Некорректные адреса ровно в том виде, в каком они были отправлены.
Очистка
empty(id) одним запросом убирает все контакты из одной аудитории и возвращает EmptiedAudienceResource: аудиторию в её нынешнем виде, с contactCount, равным 0, плюс removed, число убранных членств. Аудитория сохраняет свой идентификатор, имя и описание, а каждый контакт остаётся в адресной книге и в своих других аудиториях.
Это нельзя отменить, и нигде не записано, кто был в списке, поэтому сначала пройдите list_all_contacts, если список может понадобиться. Аудиторию по умолчанию очистить нельзя, и такой вызов отклоняется с 409 audience_immutable.
Рост
growth() читает, сколько контактов вступило в каждую аудиторию за период, который заканчивается сейчас, по дням, часам или минутам, то есть график на странице аудиторий. Требует audiences:read и возвращает AudienceGrowthResource.
Аудитория записывает, когда человек вступил, и никогда не записывает, когда он вышел, так что каждое число вступлений считает людей, которые и сегодня в списке, по дате вступления, и линия никогда не идёт вниз. Контакт, который вступил, а потом вышел, не входит ни в одно из чисел.
Параметры
audience_idsSequence[str]- До 50 идентификаторов аудиторий, отправляемых через запятую. Не указывайте, чтобы получить все аудитории. Идентификатор, не являющийся аудиторией этого рабочего пространства, даёт 404 `audience_not_found`.
daysint- Насколько далеко назад уходит период, от 1 до 1095. Если не задано ни `days`, ни `minutes`, это 30.
minutesint- Период в минутах, от 1 до 1576800, для периода короче суток. Имеет приоритет над `days`, если заданы оба.
grainTrackingGrain- Размер каждого интервала: `day` (по умолчанию), `hour` или `minute`.
offset_minutesint- Смещение смотрящего относительно UTC в минутах, от -840 до 840, чтобы дневные и часовые интервалы начинались на его местной границе. По умолчанию 0.
Ответ
sincestr- ISO-8601 UTC, начало первого интервала.
untilstr- ISO-8601 UTC, момент чтения.
totalsAudienceGrowthTotals- `contacts` считает каждого человека один раз, в скольких бы списках он ни был, а `memberships` складывает списки, так что человек считается по разу за каждый прочитанный список, в котором он есть. `subscribed` считает, по одному разу, людей, которые всё ещё подписаны хотя бы на один из прочитанных списков. `added` суммирует вступления за период, `unsubscribed` суммирует отписки за него, `lists` показывает, сколько аудиторий прочитано, а `busiest` является интервалом с наибольшим числом вступлений, или `None`.
serieslist[AudienceGrowthSeries]- По одной записи на аудиторию, от большей к меньшей: `id`, `name`, `builtin` (`True` у аудитории по умолчанию), `total` нынешних участников, `subscribed` (те из них, кто не отписался), `before` (вступившие до `since`), `added` (вступившие внутри периода), `unsubscribed` (отписавшиеся внутри него) и `buckets`, каждый в виде словаря из `bucket`, `added` и `unsubscribed`. Перечисляются только интервалы, в которых кто-то вступил или отписался, с ключами `YYYY-MM-DD`, `YYYY-MM-DDTHH` или `YYYY-MM-DDTHH:MM` в местном времени смещения.
Справочник
audiences.list()Полный справочникaudiences.list_all()Полный справочникaudiences.iterate()Полный справочникaudiences.get()Полный справочникaudiences.create()Полный справочникaudiences.update()Полный справочникaudiences.delete()Полный справочникaudiences.empty()Полный справочникaudiences.growth()Полный справочникaudiences.list_contacts()Полный справочникaudiences.list_all_contacts()Полный справочникaudiences.iterate_contacts()Полный справочникaudiences.add_contact()Полный справочникaudiences.add_contacts()Полный справочникaudiences.import_contacts()Полный справочникaudiences.remove_contact()Полный справочникaudiences.remove_contacts()Полный справочник