Audiencias
`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` y `remove_contacts`.
Todos los 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'])Una audiencia es una lista de contactos con nombre dentro de este espacio de trabajo. Todo contacto está en la audiencia predeterminada integrada desde el momento en que existe, y builtin es lo que identifica esa fila; las demás son tuyas para crearlas, llenarlas y eliminarlas. Ramifica según builtin y no según el nombre, que cualquiera puede cambiar.
Envía a una o varias audiencias con openemail.broadcasts.send, en la página Broadcasts. Meter un contacto en una audiencia es una escritura sobre la audiencia y no sobre el contacto, así que audiences:write es el único scope que se comprueba. import_contacts es la excepción: crea contactos, así que también necesita contacts:write.
add_contact acepta una dirección que ya es un contacto y rechaza la que no lo es, con 422 contact_not_found. Guárdala antes con openemail.contacts.create. Añadir a alguien dos veces responde con la pertenencia que ya existe, con su addedAt original, así que la llamada se puede reintentar sin riesgo.
La audiencia predeterminada se puede renombrar y describir como cualquier otra, pero no se puede eliminar ni vaciar parcialmente. Ambas cosas se rechazan con 409 audience_immutable. Elimina el contacto cuando lo que quieras es que se vaya el contacto.
Respuesta: AudienceResource
list devuelve una página de estos, un diccionario con items, hasMore y nextCursor, con la audiencia predeterminada primero y el resto de la más reciente a la más antigua, y list_all e iterate recorren todas las páginas. get, create y update devuelven uno cada uno. list_contacts, en cambio, devuelve una página de AudienceContactResource: los contactos en sí con la fecha en que se unió cada uno, no registros de pertenencia, con list_all_contacts e iterate_contacts a su lado.
idstr- El identificador duradero, `aud_` seguido de 24 caracteres hexadecimales. Los nombres no son únicos, así que esto es lo que debe ir en la configuración almacenada.
namestr- Se recortan los espacios al escribir, de 1 a 120 caracteres. Dos audiencias pueden compartir nombre, porque una audiencia se referencia por su id.
descriptionstr | None- Texto libre para quien lea la lista más adelante. `None` cuando nadie escribió nada, y un `None` explícito en `update` lo borra.
builtinAudienceBuiltin | str | None- `default` en exactamente una fila por espacio de trabajo, la audiencia que contiene todos los contactos, y `None` en todas las audiencias creadas por alguien. El tipo se mantiene abierto, con `str` junto al literal, para que una audiencia integrada que se añada más adelante no rompa el código tipado contra este.
contactCountint- Cuántos contactos hay en la audiencia, contados en el momento de la lectura en lugar de almacenarse en caché. Dos lecturas a uno y otro lado de un `contacts.create` difieren en uno.
lastContactAtstr | None- ISO-8601 UTC, cuándo se unió a esta audiencia el contacto que se unió más recientemente. `None` mientras la audiencia está vacía.
createdAtstr- ISO-8601 UTC, cuándo se creó la audiencia. Determina el orden de la lista después de la predeterminada.
updatedAtstr- ISO-8601 UTC, se actualiza al renombrar o al cambiar la descripción. Los cambios de pertenencia no lo tocan.
Parámetros: audiences.list_contacts
limitint- Cuántos contactos por página: un entero de 1 a 200, 50 por defecto.
cursorstr- El `nextCursor` de la página anterior, enviado con los mismos `q`, `source` y `sort`. Un cursor que nombra un contacto que no está en esta audiencia es un 400 `invalid_cursor`.
qstr- Busca en el nombre y la dirección, hasta 200 caracteres. Si nada coincide exactamente en la primera página, se devuelven grafías cercanas, y las páginas siguientes siguen buscando del mismo modo.
sourceContactSource- `'manual'` para los contactos que alguien guardó a propósito, `'auto'` para los que registró el editor de la app. Omítelo para todos los de la audiencia.
sortAudienceMemberSort- `'last-heard-newest'` (por defecto) y `'last-heard-oldest'` van por `lastSeenAt`, y los contactos a los que nunca se ha escrito quedan al final en el primero y al principio en el segundo. `'added-newest'` y `'added-oldest'` van por cuándo se unió cada contacto a esta audiencia, y `'name'` ignora mayúsculas y ordena un contacto sin nombre por su dirección.
statusesSequence[AudienceMemberStatus]- `['subscribed']` deja a los miembros que no se han dado de baja y `['unsubscribed']` a los que sí. Omítelo, o nombra ambos, para ver a todos en la audiencia. `AUDIENCE_MEMBER_STATUSES` contiene los valores.
Respuesta: AudienceContactResource
list_contacts devuelve un Page[AudienceContactResource], y list_all_contacts e iterate_contacts recorren todas las páginas con las mismas opciones. Cada fila es un ContactResource, cuyos campos están en la página Contactos, con dos más. Recorrer todas las páginas es la forma de exportar una audiencia.
addedAtstr- ISO-8601 UTC, cuándo se unió el contacto a esta audiencia. Sacar un contacto y volver a añadirlo lo pone a cero.
unsubscribedAtstr | None- ISO-8601 UTC, cuándo se dio de baja el contacto de un envío masivo a esta audiencia, o `None` mientras está suscrito. Un contacto dado de baja sigue en la audiencia, y los envíos masivos a ella lo omiten. Sacarlo y volver a añadirlo lo deja suscrito de nuevo.
Añadir y quitar en bloque
add_contacts y remove_contacts reciben {'emails': [...]}, de 1 a 200 direcciones, y cambian una audiencia en una sola petición. add_contacts nunca crea un contacto: una dirección que no lo es vuelve en missing, e import_contacts es la llamada que los crea. Ambas se pueden repetir sin riesgo, así que un reintento tras un tiempo de espera agotado devuelve a las mismas personas como ya hechas en lugar de fallar.
Añadir a la audiencia por defecto responde 'added': 0, porque todos los contactos ya están en ella, y remove_contacts sobre ella se rechaza con 409 audience_immutable. Sacar a alguien de una audiencia lo deja en la libreta de direcciones, en la audiencia por defecto y en sus otras audiencias.
audienceIdstr- La audiencia que cambió la llamada, en ambos resultados.
addedint- En `AudienceBatchAddResource`: las membresías nuevas que hizo esta llamada.
unchangedint- En `AudienceBatchAddResource`: contactos que ya estaban en la audiencia. No se escribió nada para ellos.
removedint- En `AudienceBatchRemoveResource`: las membresías que quitó esta llamada.
notInAudiencelist[str]- En `AudienceBatchRemoveResource`: contactos que no estaban en la audiencia, así que no les pasó nada.
missinglist[str]- En ambos: las direcciones que no son contactos en este espacio de trabajo, en minúsculas y sin repeticiones.
Importar
import_contacts es la importación CSV de la página de la audiencia. Recibe {'contacts': [...]}, de 1 a 500 filas, cada una con un email y un name opcional: cada dirección bien formada se convierte en contacto si aún no lo es, y todas acaban en la audiencia. Envía una lista más larga en varias llamadas. Necesita audiences:write y contacts:write.
Una dirección que ya es contacto se reutiliza y conserva su nombre, y un name aquí solo rellena uno vacío. Un contacto nuevo se guarda como manual y también se une a la audiencia por defecto, y una dirección que se eliminó de la libreta vuelve. Repetir las mismas filas no crea nada dos veces.
audienceIdstr- La audiencia a la que fueron las filas.
createdint- Contactos nuevos que guardó esta llamada.
addedint- Membresías nuevas en esta audiencia, contando los contactos que ya existían y aún no estaban en ella.
skippedint- Filas que no se importaron porque la dirección estaba mal formada.
invalidlist[str]- Las direcciones mal formadas, tal como se enviaron.
Vaciar
empty(id) saca todos los contactos de una audiencia en una sola solicitud y devuelve un EmptiedAudienceResource: la audiencia tal como queda, con contactCount a 0, más removed, el número de membresías quitadas. La audiencia conserva su id, su nombre y su descripción, y cada contacto sigue en la libreta de direcciones y en sus otras audiencias.
No se puede deshacer y nada registra quién estaba en la lista, así que recorre list_all_contacts antes si puede que la quieras de vuelta. La audiencia por defecto no se puede vaciar, y la llamada se rechaza con 409 audience_immutable.
Crecimiento
growth() lee cuántos contactos se unieron a cada audiencia en un periodo que termina ahora, por día, hora o minuto, que es el gráfico de la página de audiencias. Necesita audiences:read y devuelve un AudienceGrowthResource.
Una audiencia registra cuándo alguien se unió y nunca cuándo se fue, así que cada cifra de altas cuenta a las personas que siguen hoy en la lista según la fecha en que se unieron, y una línea nunca baja. Un contacto que se unió y luego se fue no está en ninguna de las cifras.
Parámetros
audience_idsSequence[str]- Hasta 50 ids de audiencia, enviados unidos por comas. Omítelo para todas las audiencias. Un id que no es una audiencia de este espacio de trabajo es un 404 `audience_not_found`.
daysint- Hasta dónde llega el periodo hacia atrás, de 1 a 1095. Es 30 cuando no se da ni `days` ni `minutes`.
minutesint- El periodo en minutos, de 1 a 1576800, para un periodo de menos de un día. Manda sobre `days` si se dan ambos.
grainTrackingGrain- El tamaño de cada tramo: `day` (por defecto), `hour` o `minute`.
offset_minutesint- El desfase de quien mira respecto a UTC en minutos, de -840 a 840, para que los tramos diarios y horarios empiecen en su límite local. 0 por defecto.
Respuesta
sincestr- ISO-8601 UTC, el inicio del primer tramo.
untilstr- ISO-8601 UTC, el momento de la lectura.
totalsAudienceGrowthTotals- `contacts` cuenta a cada persona una vez, esté en las listas que esté, y `memberships` suma las listas, así que una persona cuenta una vez por cada lista leída que la contiene. `subscribed` cuenta, una vez cada una, las personas que siguen suscritas a al menos una de las listas leídas. `added` suma las altas del periodo, `unsubscribed` las bajas en él, `lists` es cuántas audiencias se leyeron, y `busiest` es el tramo con más altas, o `None`.
serieslist[AudienceGrowthSeries]- Una entrada por audiencia, de mayor a menor: `id`, `name`, `builtin` (`True` en la audiencia por defecto), `total` miembros actuales, `subscribed` (los que no se han dado de baja), `before` (los que se unieron antes de `since`), `added` (los que se unieron dentro del periodo), `unsubscribed` (los que se dieron de baja dentro de él) y `buckets`, cada uno un diccionario con `bucket`, `added` y `unsubscribed`. Solo se listan los tramos con alguna alta o baja, con claves `YYYY-MM-DD`, `YYYY-MM-DDTHH` o `YYYY-MM-DDTHH:MM` en la hora local del desfase.
Referencia
audiences.list()Referencia completaaudiences.list_all()Referencia completaaudiences.iterate()Referencia completaaudiences.get()Referencia completaaudiences.create()Referencia completaaudiences.update()Referencia completaaudiences.delete()Referencia completaaudiences.empty()Referencia completaaudiences.growth()Referencia completaaudiences.list_contacts()Referencia completaaudiences.list_all_contacts()Referencia completaaudiences.iterate_contacts()Referencia completaaudiences.add_contact()Referencia completaaudiences.add_contacts()Referencia completaaudiences.import_contacts()Referencia completaaudiences.remove_contact()Referencia completaaudiences.remove_contacts()Referencia completa