오디언스
`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으로 분기하세요.
하나 이상의 오디언스로 보내려면 Broadcasts 페이지의 openemail.broadcasts.send를 쓰세요. 연락처를 오디언스에 넣는 것은 연락처가 아니라 오디언스에 대한 쓰기이므로 확인하는 스코프는 audiences:write뿐입니다. 예외는 import_contacts로, 연락처를 만들기 때문에 contacts:write도 필요합니다.
add_contact는 이미 연락처인 주소를 받고, 그렇지 않은 주소는 422 contact_not_found로 거부합니다. 먼저 openemail.contacts.create로 저장하세요. 같은 사람을 두 번 추가하면 이미 존재하는 멤버십이 원래의 addedAt과 함께 반환되므로, 이 호출은 안전하게 재시도할 수 있습니다.
기본 오디언스도 다른 오디언스처럼 이름과 설명을 바꿀 수 있지만, 삭제할 수 없고 구성원을 덜어 낼 수도 없습니다. 둘 다 409 audience_immutable로 거부됩니다. 연락처를 없애려면 연락처를 삭제하세요.
응답: AudienceResource
list는 기본 오디언스를 맨 앞에, 나머지를 최신순으로 담은 한 페이지를 items, hasMore, nextCursor가 있는 dict로 반환하고, list_all과 iterate가 모든 페이지를 훑습니다. get, create, update는 각각 하나를 반환합니다. list_contacts는 대신 AudienceContactResource의 한 페이지, 즉 멤버십 레코드가 아니라 각자 들어온 날짜가 붙은 연락처 자체를 반환하며, 옆에 list_all_contacts와 iterate_contacts가 있습니다.
idstr- 영구적인 핸들로, `aud_` 뒤에 16진수 24자가 붙습니다. 이름은 유일하지 않으므로, 저장된 설정에 들어가야 할 것은 이 값입니다.
namestr- 저장 시 앞뒤 공백이 제거되며 1자에서 120자까지입니다. 오디언스는 id로 지정하므로 두 오디언스가 같은 이름을 가질 수 있습니다.
descriptionstr | None- 나중에 목록을 보는 사람을 위한 자유 텍스트입니다. 아무도 쓰지 않았으면 `None`이고, `update`에서 명시적으로 `None`을 주면 지워집니다.
builtinAudienceBuiltin | str | None- 워크스페이스마다 정확히 한 행에서 `default`이며, 모든 연락처를 담는 오디언스입니다. 누군가 만든 오디언스에서는 `None`입니다. 타입은 리터럴 옆에 `str`을 둔 열린 형태로 유지되므로, 나중에 내장 값이 추가되어도 이 타입에 맞춰 작성한 코드가 깨지지 않습니다.
contactCountint- 오디언스에 속한 연락처 수로, 캐시된 값이 아니라 읽는 시점에 셉니다. `contacts.create` 앞뒤로 두 번 읽으면 값이 1만큼 차이 납니다.
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는 1~200개의 주소를 담은 {'emails': [...]}를 받아 한 번의 요청으로 한 오디언스를 바꿉니다. 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를 더한 것입니다. 오디언스는 ID, 이름, 설명을 유지하고, 각 연락처는 주소록과 다른 오디언스에 그대로 남습니다.
되돌릴 수 없고 누가 목록에 있었는지 어디에도 기록되지 않으므로, 나중에 되돌리고 싶을 수 있다면 먼저 list_all_contacts로 훑어 두세요. 기본 오디언스는 비울 수 없으며, 그 호출은 409 audience_immutable로 거부됩니다.
증가
growth()는 지금 끝나는 기간 동안 각 오디언스에 몇 개의 연락처가 들어왔는지 일, 시간, 분 단위로 읽습니다. 오디언스 페이지의 차트와 같습니다. audiences:read가 필요하며 AudienceGrowthResource를 반환합니다.
오디언스는 누군가 들어온 시점만 기록하고 나간 시점은 기록하지 않으므로, 참여 수치는 모두 오늘도 목록에 있는 사람을 들어온 날짜별로 센 것이며 선은 결코 내려가지 않습니다. 들어왔다가 나중에 나간 연락처는 어떤 수치에도 포함되지 않습니다.
매개변수
audience_idsSequence[str]- 오디언스 ID 최대 50개로, 쉼표로 이어서 보냅니다. 모든 오디언스라면 생략하세요. 이 워크스페이스의 오디언스가 아닌 ID는 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`(기간 안에 구독을 해지한 사람), 그리고 각각 `bucket`, `added`, `unsubscribed`로 된 dict인 `buckets`. 참여나 구독 해지가 있었던 구간만 나열되며, 키는 오프셋의 현지 시각 기준 `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()전체 레퍼런스