Audiences
`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` et `remove_contacts`.
Toutes les méthodes
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'])Une audience est une liste nommée de contacts dans cet espace de travail. Chaque contact appartient à l'audience par défaut intégrée dès l'instant où il existe, et c'est builtin qui désigne cette ligne ; les autres sont à vous de créer, remplir et supprimer. Branchez sur builtin plutôt que sur le nom, que n'importe qui peut changer.
Envoyez à une ou plusieurs audiences avec openemail.broadcasts.send, sur la page Broadcasts. Mettre un contact dans une audience est une écriture sur l'audience plutôt que sur le contact, donc audiences:write est le seul scope vérifié. import_contacts fait exception : il crée des contacts, donc il exige aussi contacts:write.
add_contact prend une adresse qui est déjà un contact et refuse celle qui ne l'est pas, avec un 422 contact_not_found. Enregistrez-la d'abord avec openemail.contacts.create. Ajouter quelqu'un deux fois renvoie l'appartenance déjà présente, avec son addedAt d'origine : l'appel peut donc être retenté sans risque.
L'audience par défaut peut être renommée et décrite comme une autre, mais elle ne peut être ni supprimée ni allégée. Les deux sont refusés par un 409 audience_immutable. Supprimez le contact quand c'est le contact que vous voulez voir partir.
Réponse : AudienceResource
list renvoie une page de ces objets, un dictionnaire avec items, hasMore et nextCursor, l'audience par défaut d'abord et les autres de la plus récente à la plus ancienne, et list_all et iterate parcourent toutes les pages. get, create et update en renvoient chacun un. list_contacts renvoie à la place une page de AudienceContactResource : les contacts eux-mêmes avec la date à laquelle chacun a rejoint, et non des enregistrements d'appartenance, avec list_all_contacts et iterate_contacts à côté.
idstr- La référence durable, `aud_` suivi de 24 caractères hexadécimaux. Les noms ne sont pas uniques : c'est donc elle qui a sa place dans une configuration stockée.
namestr- Nettoyé des espaces à l'écriture, de 1 à 120 caractères. Deux audiences peuvent porter le même nom, puisqu'une audience s'adresse par son id.
descriptionstr | None- Texte libre pour qui lira la liste plus tard. `None` quand personne n'en a écrit, et un `None` explicite sur `update` l'efface.
builtinAudienceBuiltin | str | None- `default` sur exactement une ligne par espace de travail, l'audience qui contient tous les contacts, et `None` sur chaque audience créée par quelqu'un. Le type reste ouvert, avec `str` à côté du littéral, pour qu'une audience intégrée ajoutée plus tard ne casse pas le code typé contre celui-ci.
contactCountint- Combien de contacts compte l'audience, calculé au moment de la lecture plutôt que mis en cache. Deux lectures de part et d'autre d'un `contacts.create` diffèrent de un.
lastContactAtstr | None- ISO-8601 UTC, quand le contact arrivé le plus récemment a rejoint cette audience. `None` tant que l'audience est vide.
createdAtstr- ISO-8601 UTC, quand l'audience a été créée. Fixe l'ordre de la liste après l'audience par défaut.
updatedAtstr- ISO-8601 UTC, avancé par un renommage ou un changement de description. Les changements d'appartenance n'y touchent pas.
Paramètres : audiences.list_contacts
limitint- Combien de contacts par page : un entier de 1 à 200, 50 par défaut.
cursorstr- Le `nextCursor` de la page précédente, envoyé avec les mêmes `q`, `source` et `sort`. Un curseur désignant un contact qui n'est pas dans cette audience donne un 400 `invalid_cursor`.
qstr- Cherche dans le nom et l'adresse, jusqu'à 200 caractères. Si rien ne correspond exactement sur la première page, des orthographes proches sont renvoyées à la place, et les pages suivantes continuent de chercher de la même façon.
sourceContactSource- `'manual'` pour les contacts que quelqu'un a enregistrés exprès, `'auto'` pour ceux que l'éditeur de l'application a enregistrés. Omettez-le pour tous les membres de l'audience.
sortAudienceMemberSort- `'last-heard-newest'` (par défaut) et `'last-heard-oldest'` suivent `lastSeenAt`, et les contacts à qui rien n'a jamais été envoyé arrivent en dernier dans le premier et en premier dans le second. `'added-newest'` et `'added-oldest'` suivent la date à laquelle chaque contact a rejoint cette audience, et `'name'` ignore la casse et trie un contact sans nom par son adresse.
statusesSequence[AudienceMemberStatus]- `['subscribed']` garde les membres qui ne se sont pas désabonnés et `['unsubscribed']` ceux qui l'ont fait. Omettez-le, ou nommez les deux, pour tout le monde dans l'audience. `AUDIENCE_MEMBER_STATUSES` contient les valeurs.
Réponse : AudienceContactResource
list_contacts renvoie un Page[AudienceContactResource], et list_all_contacts et iterate_contacts parcourent toutes les pages avec les mêmes options. Chaque ligne est un ContactResource, dont les champs sont sur la page Contacts, avec deux champs de plus. Parcourir toutes les pages est la façon d'exporter une audience.
addedAtstr- ISO-8601 UTC, le moment où le contact a rejoint cette audience. Retirer un contact puis le rajouter le fait repartir de zéro.
unsubscribedAtstr | None- ISO-8601 UTC, quand le contact s'est désabonné d'une diffusion envoyée à cette audience, ou `None` tant qu'il est abonné. Un contact désabonné reste dans l'audience, et les diffusions à celle-ci l'ignorent. Le retirer puis le rajouter le réabonne.
Ajouter et retirer en masse
add_contacts et remove_contacts prennent {'emails': [...]}, de 1 à 200 adresses, et modifient une audience en une seule requête. add_contacts ne crée jamais de contact : une adresse qui n'en est pas un revient dans missing, et import_contacts est l'appel qui les crée. Les deux peuvent être répétés sans risque, donc une nouvelle tentative après un délai dépassé signale les mêmes personnes comme déjà traitées au lieu d'échouer.
Ajouter à l'audience par défaut répond 'added': 0, car chaque contact y est déjà, et remove_contacts sur elle est refusé avec 409 audience_immutable. Retirer quelqu'un d'une audience le laisse dans le carnet d'adresses, dans l'audience par défaut et dans ses autres audiences.
audienceIdstr- L'audience modifiée par l'appel, sur les deux résultats.
addedint- Sur `AudienceBatchAddResource` : les nouvelles appartenances créées par cet appel.
unchangedint- Sur `AudienceBatchAddResource` : les contacts qui étaient déjà dans l'audience. Rien n'a été écrit pour eux.
removedint- Sur `AudienceBatchRemoveResource` : les appartenances retirées par cet appel.
notInAudiencelist[str]- Sur `AudienceBatchRemoveResource` : les contacts qui n'étaient pas dans l'audience, auxquels rien n'est donc arrivé.
missinglist[str]- Sur les deux : les adresses qui ne sont pas des contacts dans cet espace de travail, en minuscules et sans doublons.
Importer
import_contacts est l'import CSV de la page de l'audience. Il prend {'contacts': [...]}, de 1 à 500 lignes, chacune avec un email et un name facultatif : chaque adresse bien formée devient un contact si elle n'en est pas déjà un, et toutes arrivent dans l'audience. Envoyez une liste plus longue en plusieurs appels. Il nécessite audiences:write et contacts:write.
Une adresse qui est déjà un contact est réutilisée et garde son nom, et un name ici ne remplit qu'un nom vide. Un nouveau contact est enregistré en manual et rejoint aussi l'audience par défaut, et une adresse supprimée du carnet revient. Renvoyer les mêmes lignes ne crée rien deux fois.
audienceIdstr- L'audience dans laquelle les lignes sont allées.
createdint- Les nouveaux contacts enregistrés par cet appel.
addedint- Les nouvelles appartenances à cette audience, y compris les contacts qui existaient déjà et n'y étaient pas encore.
skippedint- Les lignes qui n'ont pas été importées parce que l'adresse était mal formée.
invalidlist[str]- Les adresses mal formées, exactement comme elles ont été envoyées.
Vider
empty(id) retire tous les contacts d'une audience en une seule requête et renvoie un EmptiedAudienceResource : l'audience dans son état actuel, avec contactCount à 0, plus removed, le nombre d'appartenances retirées. L'audience garde son identifiant, son nom et sa description, et chaque contact reste dans le carnet d'adresses et dans ses autres audiences.
C'est irréversible et rien ne garde trace de qui était dans la liste : parcourez donc list_all_contacts d'abord si vous risquez d'en avoir besoin. L'audience par défaut ne peut pas être vidée, et l'appel est refusé avec 409 audience_immutable.
Croissance
growth() lit combien de contacts ont rejoint chaque audience sur une période qui se termine maintenant, par jour, heure ou minute, c'est-à-dire le graphique de la page des audiences. Il nécessite audiences:read et renvoie un AudienceGrowthResource.
Une audience enregistre quand quelqu'un l'a rejointe et jamais quand il l'a quittée : chaque chiffre d'arrivées compte donc les personnes encore dans la liste aujourd'hui, selon leur date d'arrivée, et une courbe ne baisse jamais. Un contact qui a rejoint puis est parti n'apparaît dans aucun des chiffres.
Paramètres
audience_idsSequence[str]- Jusqu'à 50 identifiants d'audience, envoyés joints par des virgules. Omettez-le pour toutes les audiences. Un identifiant qui n'est pas une audience de cet espace de travail donne un 404 `audience_not_found`.
daysint- Jusqu'où la période remonte, de 1 à 1095. Elle vaut 30 quand ni `days` ni `minutes` n'est fourni.
minutesint- La période en minutes, de 1 à 1576800, pour une période de moins d'un jour. Elle l'emporte sur `days` quand les deux sont fournis.
grainTrackingGrain- La taille de chaque tranche : `day` (par défaut), `hour` ou `minute`.
offset_minutesint- Le décalage de la personne qui consulte par rapport à UTC, en minutes, de -840 à 840, pour que les tranches journalières et horaires commencent à sa limite locale. 0 par défaut.
Réponse
sincestr- ISO-8601 UTC, le début de la première tranche.
untilstr- ISO-8601 UTC, le moment de la lecture.
totalsAudienceGrowthTotals- `contacts` compte chaque personne une fois, quel que soit le nombre de listes où elle figure, et `memberships` additionne les listes : une personne compte donc une fois pour chaque liste lue qui la contient. `subscribed` compte, une fois chacune, les personnes encore abonnées à au moins une des listes lues. `added` additionne les arrivées de la période, `unsubscribed` les désabonnements de la période, `lists` indique combien d'audiences ont été lues, et `busiest` est la tranche qui a reçu le plus d'arrivées, ou `None`.
serieslist[AudienceGrowthSeries]- Une entrée par audience, la plus grande d'abord : `id`, `name`, `builtin` (`True` sur l'audience par défaut), `total` membres actuels, `subscribed` (ceux d'entre eux qui ne se sont pas désabonnés), `before` (ceux qui ont rejoint avant `since`), `added` (ceux qui ont rejoint pendant la période), `unsubscribed` (ceux qui se sont désabonnés pendant celle-ci) et `buckets`, chacun un dictionnaire de `bucket`, `added` et `unsubscribed`. Seules les tranches avec au moins une arrivée ou un désabonnement sont listées, avec les clés `YYYY-MM-DD`, `YYYY-MM-DDTHH` ou `YYYY-MM-DDTHH:MM` dans l'heure locale du décalage.
Référence
audiences.list()Référence complèteaudiences.list_all()Référence complèteaudiences.iterate()Référence complèteaudiences.get()Référence complèteaudiences.create()Référence complèteaudiences.update()Référence complèteaudiences.delete()Référence complèteaudiences.empty()Référence complèteaudiences.growth()Référence complèteaudiences.list_contacts()Référence complèteaudiences.list_all_contacts()Référence complèteaudiences.iterate_contacts()Référence complèteaudiences.add_contact()Référence complèteaudiences.add_contacts()Référence complèteaudiences.import_contacts()Référence complèteaudiences.remove_contact()Référence complèteaudiences.remove_contacts()Référence complète