Audiências
`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` e `remove_contacts`.
Todos os métodos
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'])Uma audiência é uma lista de contactos com nome neste espaço de trabalho. Todos os contactos estão na audiência predefinida incorporada desde o momento em que existem, e builtin é o que identifica essa linha; as restantes são suas para criar, preencher e apagar. Ramifique com base em builtin e não no nome, que qualquer pessoa pode alterar.
Envie para uma ou mais audiências com openemail.broadcasts.send, na página Broadcasts. Pôr um contacto numa audiência é uma escrita na audiência e não no contacto, por isso audiences:write é o único scope verificado. import_contacts é a exceção: cria contactos, por isso também precisa de contacts:write.
add_contact aceita um endereço que já é um contacto e recusa um que não o seja, com 422 contact_not_found. Guarde-o primeiro com openemail.contacts.create. Adicionar alguém duas vezes responde com a associação que já existe, com o seu addedAt original, pelo que é seguro repetir a chamada.
A audiência predefinida pode ser renomeada e descrita como qualquer outra, mas não pode ser eliminada nem perder membros. Ambas as operações são recusadas com 409 audience_immutable. Elimine o contacto quando a intenção é que o contacto desapareça.
Resposta: AudienceResource
list devolve uma página destes objetos, um dicionário com items, hasMore e nextCursor, com a audiência predefinida primeiro e as restantes da mais recente para a mais antiga, e list_all e iterate percorrem todas as páginas. get, create e update devolvem um cada. list_contacts devolve, em vez disso, uma página de AudienceContactResource: os próprios contactos com a data em que cada um entrou, e não registos de pertença, com list_all_contacts e iterate_contacts ao lado.
idstr- O identificador duradouro: `aud_` seguido de 24 caracteres hexadecimais. Os nomes não são únicos, pelo que é este o valor a guardar na configuração armazenada.
namestr- Os espaços nas extremidades são removidos na escrita; de 1 a 120 caracteres. Duas audiências podem ter o mesmo nome, porque uma audiência é referenciada pelo seu id.
descriptionstr | None- Texto livre para quem ler a lista mais tarde. É `None` quando ninguém escreveu nada, e um `None` explícito em `update` limpa-o.
builtinAudienceBuiltin | str | None- `default` em exatamente uma linha por espaço de trabalho, a audiência que contém todos os contactos, e `None` em todas as audiências criadas por alguém. O tipo permanece aberto, com `str` ao lado do literal, para que um valor integrado adicionado mais tarde não quebre o código tipado com base neste.
contactCountint- Quantos contactos existem na audiência, contados no momento da leitura em vez de guardados em cache. Duas leituras, uma antes e outra depois de um `contacts.create`, diferem em um.
lastContactAtstr | None- ISO-8601 UTC, quando o contacto que entrou mais recentemente entrou nesta audiência. `None` enquanto a audiência estiver vazia.
createdAtstr- ISO-8601 UTC, quando a audiência foi criada. Determina a ordem da lista a seguir à predefinida.
updatedAtstr- ISO-8601 UTC, atualizado por uma mudança de nome ou de descrição. As alterações de membros não o afetam.
Parâmetros: audiences.list_contacts
limitint- Quantos contactos por página: um inteiro de 1 a 200, 50 por omissão.
cursorstr- O `nextCursor` da página anterior, enviado com os mesmos `q`, `source` e `sort`. Um cursor que designa um contacto que não está nesta audiência dá um 400 `invalid_cursor`.
qstr- Pesquisa o nome e o endereço, até 200 caracteres. Quando nada coincide exatamente na primeira página, são devolvidas grafias próximas, e as páginas seguintes continuam a pesquisar da mesma forma.
sourceContactSource- `'manual'` para os contactos que alguém guardou de propósito, `'auto'` para os que o editor da aplicação registou. Omita-o para toda a audiência.
sortAudienceMemberSort- `'last-heard-newest'` (por omissão) e `'last-heard-oldest'` seguem `lastSeenAt`, e os contactos a quem nunca foi enviado correio ficam no fim no primeiro e no início no segundo. `'added-newest'` e `'added-oldest'` seguem a data em que cada contacto entrou nesta audiência, e `'name'` ignora maiúsculas e ordena um contacto sem nome pelo endereço.
statusesSequence[AudienceMemberStatus]- `['subscribed']` mantém os membros que não cancelaram a inscrição e `['unsubscribed']` os que cancelaram. Omita-o, ou indique os dois, para todos na audiência. `AUDIENCE_MEMBER_STATUSES` contém os valores.
Resposta: AudienceContactResource
list_contacts devolve um Page[AudienceContactResource], e list_all_contacts e iterate_contacts percorrem todas as páginas com as mesmas opções. Cada linha é um ContactResource, cujos campos estão na página Contactos, com mais dois. Percorrer todas as páginas é a forma de exportar uma audiência.
addedAtstr- ISO-8601 UTC, quando o contacto entrou nesta audiência. Retirar um contacto e voltar a adicioná-lo recomeça a contagem.
unsubscribedAtstr | None- ISO-8601 UTC, quando o contacto cancelou a subscrição de uma difusão enviada para esta audiência, ou `None` enquanto tem subscrição. Um contacto sem subscrição continua na audiência, e as difusões para ela ignoram-no. Retirá-lo e voltar a adicioná-lo dá-lhe subscrição de novo.
Adicionar e remover em massa
add_contacts e remove_contacts recebem {'emails': [...]}, de 1 a 200 endereços, e alteram uma audiência num só pedido. add_contacts nunca cria um contacto: um endereço que não o é volta em missing, e import_contacts é a chamada que os cria. Ambas são seguras de repetir, pelo que uma nova tentativa após um tempo esgotado indica as mesmas pessoas como já tratadas em vez de falhar.
Adicionar à audiência predefinida responde 'added': 0, porque todos os contactos já lá estão, e remove_contacts sobre ela é recusado com 409 audience_immutable. Retirar alguém de uma audiência deixa-o no livro de endereços, na audiência predefinida e nas suas outras audiências.
audienceIdstr- A audiência que a chamada alterou, em ambos os resultados.
addedint- Em `AudienceBatchAddResource`: as novas associações que esta chamada criou.
unchangedint- Em `AudienceBatchAddResource`: contactos que já estavam na audiência. Nada foi escrito para eles.
removedint- Em `AudienceBatchRemoveResource`: as associações que esta chamada retirou.
notInAudiencelist[str]- Em `AudienceBatchRemoveResource`: contactos que não estavam na audiência, pelo que nada lhes aconteceu.
missinglist[str]- Em ambos: os endereços que não são contactos neste espaço de trabalho, em minúsculas e sem repetições.
Importar
import_contacts é a importação CSV da página da audiência. Recebe {'contacts': [...]}, de 1 a 500 linhas, cada uma com um email e um name opcional: cada endereço bem formado torna-se um contacto se ainda não o for, e todos vão parar à audiência. Envie uma lista mais longa em várias chamadas. Requer audiences:write e contacts:write.
Um endereço que já é contacto é reutilizado e mantém o nome, e um name aqui só preenche um que estava vazio. Um contacto novo é guardado como manual e também entra na audiência predefinida, e um endereço que foi apagado do livro volta. Repetir as mesmas linhas não cria nada duas vezes.
audienceIdstr- A audiência para onde foram as linhas.
createdint- Contactos novos que esta chamada guardou.
addedint- Novas associações nesta audiência, contando contactos que já existiam e ainda não estavam nela.
skippedint- Linhas que não foram importadas porque o endereço estava mal formado.
invalidlist[str]- Os endereços mal formados, exatamente como foram enviados.
Esvaziar
empty(id) retira todos os contactos de uma audiência num só pedido e devolve um EmptiedAudienceResource: a audiência tal como ficou, com contactCount a 0, mais removed, o número de associações retiradas. A audiência mantém o id, o nome e a descrição, e cada contacto continua no livro de endereços e nas suas outras audiências.
Não pode ser anulado e nada regista quem estava na lista, por isso percorra primeiro list_all_contacts se a puder querer de volta. A audiência predefinida não pode ser esvaziada, e a chamada é recusada com 409 audience_immutable.
Crescimento
growth() lê quantos contactos entraram em cada audiência num período que termina agora, por dia, hora ou minuto, que é o gráfico da página de audiências. Requer audiences:read e devolve um AudienceGrowthResource.
Uma audiência regista quando alguém entrou e nunca quando saiu, por isso cada valor de entradas conta as pessoas que continuam hoje na lista, pela data em que entraram, e uma linha nunca desce. Um contacto que entrou e depois saiu não está em nenhum dos valores.
Parâmetros
audience_idsSequence[str]- Até 50 ids de audiência, enviados unidos por vírgulas. Omita-o para todas as audiências. Um id que não é uma audiência deste espaço de trabalho dá um 404 `audience_not_found`.
daysint- Até onde o período recua, de 1 a 1095. É 30 quando não é dado nem `days` nem `minutes`.
minutesint- O período em minutos, de 1 a 1576800, para um período inferior a um dia. Prevalece sobre `days` quando ambos são dados.
grainTrackingGrain- O tamanho de cada intervalo: `day` (por omissão), `hour` ou `minute`.
offset_minutesint- O desvio de quem consulta em relação a UTC em minutos, de -840 a 840, para que os intervalos diários e horários comecem no seu limite local. 0 por omissão.
Resposta
sincestr- ISO-8601 UTC, o início do primeiro intervalo.
untilstr- ISO-8601 UTC, o momento da leitura.
totalsAudienceGrowthTotals- `contacts` conta cada pessoa uma vez, em quantas listas estiver, e `memberships` soma as listas, pelo que uma pessoa conta uma vez por cada lista lida que a contém. `subscribed` conta, uma vez cada uma, as pessoas ainda subscritas a pelo menos uma das listas lidas. `added` soma as entradas no período, `unsubscribed` os cancelamentos de subscrição nele, `lists` é quantas audiências foram lidas, e `busiest` é o intervalo com mais entradas, ou `None`.
serieslist[AudienceGrowthSeries]- Uma entrada por audiência, da maior para a menor: `id`, `name`, `builtin` (`True` na audiência predefinida), `total` membros atuais, `subscribed` (os que não cancelaram a subscrição), `before` (os que entraram antes de `since`), `added` (os que entraram dentro do período), `unsubscribed` (os que cancelaram a subscrição dentro dele) e `buckets`, cada um um dicionário com `bucket`, `added` e `unsubscribed`. Só são listados os intervalos com alguma entrada ou cancelamento, com chaves `YYYY-MM-DD`, `YYYY-MM-DDTHH` ou `YYYY-MM-DDTHH:MM` na hora local do desvio.
Referência
audiences.list()Referência completaaudiences.list_all()Referência completaaudiences.iterate()Referência completaaudiences.get()Referência completaaudiences.create()Referência completaaudiences.update()Referência completaaudiences.delete()Referência completaaudiences.empty()Referência completaaudiences.growth()Referência completaaudiences.list_contacts()Referência completaaudiences.list_all_contacts()Referência completaaudiences.iterate_contacts()Referência completaaudiences.add_contact()Referência completaaudiences.add_contacts()Referência completaaudiences.import_contacts()Referência completaaudiences.remove_contact()Referência completaaudiences.remove_contacts()Referência completa