オーディエンス
`audiences.list`、`get`、`create`、`update`、`delete`、`empty`、`growth`、`list_contacts`、`add_contact`、`add_contacts`、`import_contacts`、`remove_contact`、`remove_contacts`。
すべてのメソッド
audiences = client.audiences.list_alleveryone = audiences.find { |audience| audience[:builtin] == "default" } list = client.audiences.create( name: "Product updates", description: "Customers who asked to hear about releases") client.contacts.create(email: "[email protected]", name: "Grace Hopper")client.audiences.add_contact(list[:id], email: "[email protected]") bulk = client.audiences.add_contacts(list[:id], emails: ["[email protected]", "[email protected]"]) imported = client.audiences.import_contacts( list[:id], contacts: [{email: "[email protected]", name: "Katherine Johnson"}]) members = client.audiences.list_all_contacts(list[:id], q: "grace", sort: "added-newest", limit: 200) growth = client.audiences.growth(audience_ids: [list[:id]], days: 30) client.audiences.update(list[:id], name: "Release notes")client.audiences.remove_contact(list[:id], "[email protected]")client.audiences.remove_contacts(list[:id], emails: ["[email protected]"])client.audiences.empty(list[:id])client.audiences.delete(list[:id]) puts everyone[:contactCount] if everyoneputs bulk[:missing], imported[:created], members.size, growth.dig(:totals, :added)オーディエンスは、このワークスペースの連絡先に名前を付けたリストです。すべての連絡先は、作られた瞬間から組み込みの既定のオーディエンスに入っており、その行を示すのが builtin です。それ以外は自由に作成し、連絡先を入れ、削除できます。誰でも変更できる名前ではなく、builtin で分岐してください。
1 つのオーディエンスに対する呼び出しは、その id を第 1 引数に取り、remove_contact はアドレスを第 2 引数に取ります。それ以外はすべて Ruby のキーワード引数で、リクエストボディは 1 つの Hash として渡すこともできます。growth と list_contacts のオプションは snake_case（audience_ids:、offset_minutes:）ですが、ボディのフィールドは API の名前のままです（emails:、contacts:）。レスポンスは API の camelCase の Symbol キーを持つ Hash なので、audience[:contactCount] で件数を読めます。
1 つ以上のオーディエンスに送信するには client.broadcasts.send を使います。一斉配信のページで説明しています。連絡先をオーディエンスに入れるのは、連絡先ではなくオーディエンスへの書き込みなので、確認されるスコープは audiences:write だけです。例外は import_contacts です。連絡先を作成するため、contacts:write も必要です。
add_contact はすでに連絡先であるアドレスを受け取り、そうでないアドレスは 422 contact_not_found で拒否し、OpenEmail::ValidationError として送出されます。先に client.contacts.create で保存してください。同じ人を 2 回追加すると、元の addedAt を持つ既存のメンバーシップが返るため、この呼び出しは安全にリトライでき、gem はネットワーク障害の後にリトライします。
既定のオーディエンスは、他と同じように名前や説明を変えられますが、削除することも、連絡先を減らすこともできません。どちらも 409 audience_immutable で拒否され、conflict? が true の OpenEmail::ConflictError として送出されます。連絡先そのものを消したいときは、連絡先を削除してください。
レスポンス：オーディエンス
list はこれらの 1 ページを、items、has_more?、next_cursor を持つ OpenEmail::Page として返します。既定のオーディエンスが最初で、残りは新しい順です。1 ページは 25 件で、limit: で最大 100 件まで指定できます。list_all はすべてのページを 1 つの Array で返し、iterate はオーディエンスを 1 つずつブロックに yield するか、ブロックがなければ Enumerator を返します。get、create、update はそれぞれ 1 つのオーディエンスを返します。list_contacts は代わりに連絡先のページを返します。メンバーシップのレコードではなく、それぞれが加わった日付付きの連絡先そのもので、隣に list_all_contacts と iterate_contacts があります。
idString- 永続的なハンドル。`aud_` に続く 24 文字の 16 進数です。名前は一意ではないので、設定に保存すべきなのはこちらです。
nameString- 書き込み時にトリムされ、1〜120 文字です。オーディエンスは id で指定されるため、2 つのオーディエンスが同じ名前を持っても構いません。
descriptionString or nil- 後でリストを読む人のための自由記述のテキスト。誰も何も書いていない場合は nil で、`update` で `description: nil` を渡すと消去されます。
builtinString or nil- ワークスペースごとにちょうど 1 行、すべての連絡先を含むオーディエンスでは `default`、誰かが作成したすべてのオーディエンスでは nil です。後から追加される組み込みのオーディエンスを既定のものと取り違えないよう、nil かどうかを調べるのではなく `"default"` と比較してください。
contactCountInteger- そのオーディエンスに何件の連絡先があるか。キャッシュではなく読み取りの瞬間に数えます。`contacts.create` を挟んだ 2 回の読み取りは 1 件ずれます。
lastContactAtString or nil- ISO 8601 の UTC で、最も最近加わった連絡先がこのオーディエンスに加わった時刻です。オーディエンスが空の間は nil です。
createdAtString- ISO 8601 の UTC で、オーディエンスが作られた時刻です。既定のオーディエンスより後の一覧の順序はこれで決まります。
updatedAtString- ISO 8601 の UTC で、名前や説明を変更すると更新されます。メンバーシップの変更では変わりません。
パラメーター：audiences.list_contacts
limitInteger- 1 ページあたりの連絡先の数で、1〜200 の整数、既定値は 50 です。
cursorString- 前のページの `next_cursor` で、同じ `q:`、`source:`、`sort:`、`statuses:` と一緒に送ります。このオーディエンスにない連絡先を指すカーソルは 400 `invalid_cursor` になり、`OpenEmail::InvalidRequestError` として送出されます。
qString- 名前とアドレスを最大 200 文字で検索します。最初のページで完全に一致するものがなければ、代わりに近い綴りが返り、続くページも同じ方法で一致を続けます。
sourceString- 誰かが意図して保存した連絡先は `manual`、アプリのコンポーザーが記録したものは `auto`。オーディエンスの全員を対象にするには省略します。
sortString- `last-heard-newest`（既定値）と `last-heard-oldest` は `lastSeenAt` で並べ、一度もメールを送っていない連絡先は前者では最後、後者では最初に来ます。`added-newest` と `added-oldest` は各連絡先がこのオーディエンスに加わった時刻で並べ、`name` は大文字小文字を無視し、名前のない連絡先はアドレスで並べます。
statusesArray<String>- `["subscribed"]` は配信停止していないメンバーを、`["unsubscribed"]` は配信停止したメンバーを残します。オーディエンスの全員を対象にするには、省略するか、空の Array を渡すか、両方を指定します。`OpenEmail::AUDIENCE_MEMBER_STATUSES` が値を保持し、gem はそれらをカンマで結合して `status` クエリパラメーターとして送ります。
レスポンス：オーディエンス内の連絡先
list_contacts は連絡先の Hash の OpenEmail::Page を返し、list_all_contacts と iterate_contacts は同じキーワード引数ですべてのページをたどります。各行は contacts.list が返すのと同じ形の連絡先（フィールドは連絡先のページで説明しています）に、2 つのフィールドを加えたものです。オーディエンスをエクスポートするには、すべてのページをたどります。
addedAtString- ISO 8601 の UTC で、連絡先がこのオーディエンスに加わった時刻です。連絡先を外して再び追加すると、新たに始まります。
unsubscribedAtString or nil- ISO 8601 の UTC で、連絡先がこのオーディエンスに送られた一斉配信から配信停止した時刻です。購読中は nil です。配信停止した連絡先はオーディエンスに残り、このオーディエンスへの一斉配信ではスキップされます。外して再び追加すると、改めて購読中になります。
一括での追加と削除
add_contacts と remove_contacts は、1〜200 個のアドレスの Array である emails: を受け取り、1 回のリクエストで 1 つのオーディエンスを変更します。add_contacts が連絡先を作成することはありません。連絡先でないアドレスは missing で返り、それらを作成するのは import_contacts です。どちらも繰り返して安全なので、gem はネットワーク障害の後にリトライし、リトライは失敗するのではなく、同じ人を処理済みとして報告します。
既定のオーディエンスに追加すると、すべての連絡先がすでに入っているため added: 0 が返り、そこへの remove_contacts は 409 audience_immutable で拒否されます。オーディエンスから外しても、その人はアドレス帳、既定のオーディエンス、その他のオーディエンスに残ります。
audienceIdString- 呼び出しが変更したオーディエンス。どちらの結果にも含まれます。
addedInteger- `add_contacts` の結果：この呼び出しで新たに作られたメンバーシップ。
unchangedInteger- `add_contacts` の結果：すでにオーディエンスに入っていた連絡先。それらについては何も書き込まれていません。
removedInteger- `remove_contacts` の結果：この呼び出しで取り除かれたメンバーシップ。
notInAudienceArray<String>- `remove_contacts` の結果：オーディエンスに入っていなかったため、何も起きなかった連絡先。
missingArray<String>- 両方。このワークスペースで連絡先でないアドレスを、小文字で重複なく。
インポート
import_contacts はオーディエンスのページにある CSV インポートです。contacts: として 1〜500 個の Hash の Array を受け取り、それぞれ email と省略可能な name を持ちます。正しい形式の各アドレスは、まだ連絡先でなければ連絡先になり、すべてがオーディエンスに入ります。それより長いリストは複数回の呼び出しに分けて送ってください。audiences:write と contacts:write が必要で、どちらかが欠けたキーは 403 insufficient_scope で拒否され、そのエラーでは scope_missing? が true です。
すでに連絡先であるアドレスはそのまま使われて名前も保持され、ここでの name は空だった名前を埋めるだけです。新しい連絡先は manual として保存され、既定のオーディエンスにも加わります。アドレス帳から削除されたアドレスは復活します。同じ行を再送しても何も二重に作られないため、gem はネットワーク障害の後にこの呼び出しをリトライします。
audienceIdString- 行が入ったオーディエンス。
createdInteger- この呼び出しで保存された新しい連絡先。
addedInteger- このオーディエンスでの新しいメンバーシップ。すでに存在していて、まだ入っていなかった連絡先も数えます。
skippedInteger- アドレスの形式が正しくなかったためにインポートされなかった行。
invalidArray<String>- 形式の正しくないアドレスを、送られたとおりに。
空にする
empty(id) は 1 回のリクエストで 1 つのオーディエンスからすべての連絡先を外し、contactCount が 0 になった現在のオーディエンスに、取り除いたメンバーシップの数 removed を加えて返します。オーディエンスの id、名前、説明は保持され、すべての連絡先はアドレス帳とその他のオーディエンスに残ります。
元に戻すことはできず、誰がリストに入っていたかはどこにも記録されないため、後で戻したくなるかもしれないなら、先に list_all_contacts でたどっておいてください。既定のオーディエンスは空にできず、呼び出しは 409 audience_immutable で拒否されます。2 回目の呼び出しは removed: 0 で成功してしまうため、gem はネットワーク障害の後に empty をリトライしません。レスポンスが失われた場合は、get でオーディエンスを読んでください。
増加
growth は、現在で終わる期間に各オーディエンスに加わった連絡先の数と、その期間内に配信停止した数を、日、時間、分の単位で読みます。オーディエンスのページにあるグラフです。キーワード引数を受け取り、audiences:read が必要で、1 つの Hash を返します。
growth = client.audiences.growth( audience_ids: ["aud_9f2c4b7e1a0d63d84c5f2e7b"], days: 90, grain: "day", offset_minutes: Time.now.utc_offset / 60) puts "#{growth.dig(:totals, :added)} joins since #{growth[:since]}" growth[:series].each do |series| puts "#{series[:name]}: #{series[:before]} before the window, #{series[:total]} now"endオーディエンスは誰かが参加した日時を記録し、抜けた日時は記録しないため、どの数値も今日もリストにいる人を参加日で数えたものになり、線が下がることはありません。参加したあとで抜けた連絡先は、どの数値にも含まれません。
パラメーター
audience_idsArray<String>- オーディエンス id を最大 50 個、カンマでつないで送ります。すべてのオーディエンスを対象にするには、省略するか空の Array を渡します。このワークスペースのオーディエンスでない id は 404 `audience_not_found` になり、50 個を超えると 422 になります。
daysInteger- 期間をどこまでさかのぼるか。1〜1095 です。`days:` も `minutes:` も指定しなければ 30 になります。
minutesInteger- 分単位の期間で、1〜1576800。1 日より短い期間に使います。両方指定すると `days:` より優先されます。
grainString- 各区切りの大きさ。`day`(既定)、`hour`、`minute` のいずれかです。
offset_minutesInteger- 閲覧者の UTC からのずれを分単位で、-840〜840。日と時間の区切りが現地の境目で始まるようにします。既定は 0 です。コードが動いているマシンのずれは `Time.now.utc_offset / 60` で得られます。
レスポンス
sinceString- ISO 8601 の UTC。最初の区切りの始まり。
untilString- ISO 8601 の UTC。読み取った時点。
totalsHash- `contacts` は何個のリストに入っていても各人を 1 回だけ数え、`memberships` はリストを合計します。そのため、読み取ったリストのうちその人が入っているものの数だけ数えられます。`added` は期間内の参加の合計、`lists` は読み取ったオーディエンスの数、`busiest` は参加が最も多かった区切りで、なければ nil です。`subscribed` は、読み取ったオーディエンスの少なくとも 1 つをまだ購読している人を 1 人 1 回ずつ数え、`unsubscribed` は期間内の配信停止を合計します。
seriesArray<Hash>- オーディエンスごとに 1 項目で、大きい順、次に名前順です：`id`、`name`、`builtin`、現在のメンバー数 `total`、`subscribed`（まだ購読している人）、`before`（`since` より前に参加した人）、`added`（期間内に参加した人）、`unsubscribed`（期間内に配信停止した人）、そして古い順の `buckets` で、それぞれ `bucket`、`added`、`unsubscribed` を持つ Hash です。ここでの `builtin` は既定のオーディエンスで `true`、それ以外で `false` で、オーディエンスの Hash が持つ String ではありません。参加または配信停止があった区切りだけが列挙され、キーはオフセットの現地時刻による `YYYY-MM-DD`、`YYYY-MM-DDTHH`、`YYYY-MM-DDTHH:MM` です。