オーディエンス
`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 で分岐してください。
1 つ以上のオーディエンスに送るには、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 はこれらの 1 ページ分を、items、hasMore、nextCursor を持つ dict として返します。既定オーディエンスが先頭、残りは新しい順で、list_all と iterate がすべてのページをたどります。get、create、update はそれぞれ 1 件を返します。list_contacts は代わりに AudienceContactResource の 1 ページを返し、メンバーシップの記録ではなく、各人の参加日付きで連絡先そのものを返します。隣には list_all_contacts と iterate_contacts があります。
idstr- 永続的なハンドル。`aud_` に続く 24 文字の 16 進数です。名前は一意ではないので、設定に保存すべきなのはこちらです。
namestr- 書き込み時にトリムされ、1〜120 文字です。オーディエンスは id で指定されるため、2 つのオーディエンスが同じ名前を持っても構いません。
descriptionstr | None- 後でこのリストを読む人のための自由記述です。誰も書いていなければ `None` で、`update` で明示的に `None` を渡すとクリアされます。
builtinAudienceBuiltin | str | None- ワークスペースごとにちょうど 1 行だけが `default` で、それがすべての連絡先を保持するオーディエンスです。誰かが作成したオーディエンスでは `None` になります。型はリテラルと並べて `str` を含む開いた形のままなので、後から組み込みが追加されても、この型に対して型付けしたコードは壊れません。
contactCountint- そのオーディエンスに何件の連絡先があるか。キャッシュではなく読み取りの瞬間に数えます。`contacts.create` を挟んだ 2 回の読み取りは 1 件ずれます。
lastContactAtstr | None- ISO-8601 の UTC で、このオーディエンスに最後に参加した連絡先が参加した時刻です。オーディエンスが空のあいだは `None` です。
createdAtstr- ISO-8601 の UTC で、オーディエンスが作られた時刻です。既定オーディエンス以降の並び順を決めます。
updatedAtstr- ISO-8601 の UTC で、名前や説明の変更で更新されます。メンバーシップの変更では動きません。
パラメーター: audiences.list_contacts
limitint- 1 ページあたりの連絡先の数。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 で、そのフィールドは連絡先のページにあり、ここではフィールドが 2 つ増えます。すべてのページをたどることが、オーディエンスをエクスポートする方法です。
addedAtstr- ISO-8601 UTC。連絡先がこのオーディエンスに参加した時点です。連絡先を外してから追加し直すと、新しい時点から数え直します。
unsubscribedAtstr | None- ISO-8601 UTC で、このオーディエンスに送られた一斉配信から連絡先が配信停止した日時。購読中は `None` です。配信停止した連絡先はオーディエンスに残り、そこへの一斉配信ではスキップされます。外して追加し直すと、改めて購読状態になります。
一括での追加と削除
add_contacts と remove_contacts は 1〜200 個のアドレスを入れた {'emails': [...]} を受け取り、1 回のリクエストで 1 つのオーディエンスを変更します。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 として保存されてデフォルトオーディエンスにも参加し、アドレス帳から削除されたアドレスは元に戻ります。同じ行を送り直しても、何も 2 回作成されません。
audienceIdstr- 行が入ったオーディエンス。
createdint- この呼び出しで保存された新しい連絡先。
addedint- このオーディエンスでの新しいメンバーシップ。すでに存在していて、まだ入っていなかった連絡先も数えます。
skippedint- アドレスの形式が正しくなかったためにインポートされなかった行。
invalidlist[str]- 形式の正しくないアドレスを、送られたとおりに。
空にする
empty(id) は 1 回のリクエストで 1 つのオーディエンスからすべての連絡先を外し、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。1 日より短い期間に使います。両方指定すると `days` より優先されます。
grainTrackingGrain- 各区切りの大きさ。`day`(既定)、`hour`、`minute` のいずれかです。
offset_minutesint- 閲覧者の UTC からのずれを分単位で、-840〜840。日と時間の区切りが現地の境目で始まるようにします。既定は 0 です。
レスポンス
sincestr- ISO-8601 UTC。最初の区切りの始まり。
untilstr- ISO-8601 UTC。読み取った時点。
totalsAudienceGrowthTotals- `contacts` は何個のリストに入っていても各人を 1 回だけ数え、`memberships` はリストを合計します。そのため、読み取ったリストのうちその人が入っているものの数だけ数えられます。`subscribed` は、読み取ったリストの少なくとも 1 つをまだ購読している人を 1 人 1 回ずつ数えます。`added` は期間内の参加の合計、`unsubscribed` は期間内の配信停止の合計、`lists` は読み取ったオーディエンスの数、`busiest` は参加が最も多かった区切りで、なければ `None` です。
serieslist[AudienceGrowthSeries]- オーディエンスごとに 1 項目、大きい順です。`id`、`name`、`builtin`（デフォルトオーディエンスで `True`）、現在のメンバー数 `total`、`subscribed`（そのうち配信停止していない人）、`before`（`since` より前に参加した人）、`added`（期間内に参加した人）、`unsubscribed`（期間内に配信停止した人）、そして `buckets`（それぞれ `bucket`、`added`、`unsubscribed` を持つ dict）。参加または配信停止があった区切りだけが列挙され、キーはオフセットの現地時刻による `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()完全なリファレンス