オーディエンス
`audiences->list`、`get`、`create`、`update`、`delete`、`empty`、`growth`、`listContacts`、`addContact`、`addContacts`、`importContacts`、`removeContact`、`removeContacts`。
すべてのメソッド
$everyone = null; foreach ($client->audiences->listAll() as $audience) { if ($audience['builtin'] === 'default') { $everyone = $audience; }} $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->addContact($list['id'], ['email' => '[email protected]']); $bulk = $client->audiences->addContacts($list['id'], ['emails' => ['[email protected]', '[email protected]']]); $imported = $client->audiences->importContacts($list['id'], [ 'contacts' => [['email' => '[email protected]', 'name' => 'Katherine Johnson']],]); $members = $client->audiences->listAllContacts($list['id'], q: 'grace', sort: 'added-newest', limit: 200); $growth = $client->audiences->growth(audienceIds: [$list['id']], days: 30); $client->audiences->update($list['id'], ['name' => 'Release notes']);$client->audiences->removeContact($list['id'], '[email protected]');$client->audiences->removeContacts($list['id'], ['emails' => ['[email protected]']]);$client->audiences->empty($list['id']);$client->audiences->delete($list['id']); echo $everyone['contactCount'] ?? 0, ' contacts in all', PHP_EOL;echo implode(', ', $bulk['missing']), ' ', $imported['created'], ' ', count($members), ' ', $growth['totals']['added'], PHP_EOL;オーディエンスは、このワークスペースの連絡先に名前を付けたリストです。すべての連絡先は、作られた瞬間から組み込みの既定のオーディエンスに入っており、その行を示すのが builtin です。それ以外は自由に作成し、連絡先を入れ、削除できます。誰でも変更できる名前ではなく、builtin で分岐してください。
1 つのオーディエンスに対する呼び出しは、その id を第 1 引数に取り、removeContact はアドレスを第 2 引数に取ります。フィルターとオプションは camelCase の名前付き引数（audienceIds:、offsetMinutes:）ですが、リクエストボディは API の名前をそのままキーにした 1 つの配列です（emails、contacts）。レスポンスは API の camelCase のキーを持つ配列なので、$audience['contactCount'] で件数を読めます。
1 つ以上のオーディエンスに送信するには $client->broadcasts->send を使います。一斉配信のページで説明しています。連絡先をオーディエンスに入れるのは、連絡先ではなくオーディエンスへの書き込みなので、確認されるスコープは audiences:write だけです。例外は importContacts です。連絡先を作成するため、contacts:write も必要です。
addContact はすでに連絡先であるアドレスを受け取り、そうでないアドレスは 422 contact_not_found で拒否し、ValidationException としてスローされます。先に $client->contacts->create で保存してください。同じ人を 2 回追加すると、元の addedAt を持つ既存のメンバーシップが返るため、この呼び出しは安全にリトライでき、クライアントはネットワーク障害の後にリトライします。
既定のオーディエンスは、他と同じように名前や説明を変えられますが、削除することも、連絡先を減らすこともできません。どちらも 409 audience_immutable で拒否され、isConflict() が true の ConflictException としてスローされます。連絡先そのものを消したいときは、連絡先を削除してください。
レスポンス：オーディエンス
list はこれらの 1 ページを、items、hasMore、nextCursor を持つ OpenEmail\Result\Page として返します。既定のオーディエンスが最初で、残りは新しい順です。1 ページは 25 件で、limit: で最大 100 件まで指定できます。listAll はすべてのオーディエンスを 1 つの配列で返し、iterate はオーディエンスを 1 つずつ yield する Generator を返します。get、create、update はそれぞれ 1 つのオーディエンスを返します。listContacts は代わりに連絡先のページを返します。メンバーシップのレコードではなく、それぞれが加わった日付付きの連絡先そのもので、隣に listAllContacts と iterateContacts があります。
idstring- 永続的なハンドル。`aud_` に続く 24 文字の 16 進数です。名前は一意ではないので、設定に保存すべきなのはこちらです。
namestring- 書き込み時にトリムされ、1〜120 文字です。オーディエンスは id で指定されるため、2 つのオーディエンスが同じ名前を持っても構いません。
descriptionstring or null- 後でリストを読む人のための自由記述のテキスト。誰も何も書いていない場合は null で、`update` で `'description' => null` を渡すと消去されます。
builtinstring or null- ワークスペースごとにちょうど 1 行、すべての連絡先を含むオーディエンスでは `default`、誰かが作成したすべてのオーディエンスでは null です。後から追加される組み込みのオーディエンスを既定のものと取り違えないよう、null かどうかを調べるのではなく `'default'` と比較してください。
contactCountint- そのオーディエンスに何件の連絡先があるか。キャッシュではなく読み取りの瞬間に数えます。`contacts->create` を挟んだ 2 回の読み取りは 1 件ずれます。
lastContactAtstring or null- ISO 8601 の UTC で、最も最近加わった連絡先がこのオーディエンスに加わった時刻です。オーディエンスが空の間は null です。
createdAtstring- ISO 8601 の UTC で、オーディエンスが作られた時刻です。既定のオーディエンスより後の一覧の順序はこれで決まります。
updatedAtstring- ISO 8601 の UTC で、名前や説明を変更すると更新されます。メンバーシップの変更では変わりません。
パラメーター：audiences->listContacts
limitint- 1 ページあたりの連絡先の数で、1〜200 の整数、既定値は 50 です。
cursorstring- 前のページの `nextCursor` で、同じ `q:`、`source:`、`sort:`、`statuses:` と一緒に送ります。このオーディエンスにない連絡先を指すカーソルは 400 `invalid_cursor` になり、`InvalidRequestException` としてスローされます。
qstring- 名前とアドレスを最大 200 文字で検索します。最初のページで完全に一致するものがなければ、代わりに近い綴りが返り、続くページも同じ方法で一致を続けます。
sourcestring- 誰かが意図して保存した連絡先は `manual`、アプリのコンポーザーが記録したものは `auto`。オーディエンスの全員を対象にするには省略します。
sortstring- `last-heard-newest`（既定値）と `last-heard-oldest` は `lastSeenAt` で並べ、一度もメールを送っていない連絡先は前者では最後、後者では最初に来ます。`added-newest` と `added-oldest` は各連絡先がこのオーディエンスに加わった時刻で並べ、`name` は大文字小文字を無視し、名前のない連絡先はアドレスで並べます。
statusesstring or array- `['subscribed']` は配信停止していないメンバーを、`['unsubscribed']` は配信停止したメンバーを残します。オーディエンスの全員を対象にするには、省略するか、空の配列を渡すか、両方を指定します。`OpenEmail\Constants\AudienceMemberStatuses` が値を保持し、クライアントはそれらをカンマで結合して `status` クエリパラメーターとして送ります。
レスポンス：オーディエンス内の連絡先
listContacts は連絡先の配列の OpenEmail\Result\Page を返し、listAllContacts と iterateContacts は同じ名前付き引数ですべてのページをたどります。各行は contacts->list が返すのと同じ形の連絡先（フィールドは連絡先のページで説明しています）に、2 つのフィールドを加えたものです。オーディエンスをエクスポートするには、すべてのページをたどります。
addedAtstring- ISO 8601 の UTC で、連絡先がこのオーディエンスに加わった時刻です。連絡先を外して再び追加すると、新たに始まります。
unsubscribedAtstring or null- ISO 8601 の UTC で、連絡先がこのオーディエンスに送られた一斉配信から配信停止した時刻です。購読中は null です。配信停止した連絡先はオーディエンスに残り、このオーディエンスへの一斉配信ではスキップされます。外して再び追加すると、改めて購読中になります。
一括での追加と削除
addContacts と removeContacts は、emails が 1〜200 個のアドレスのリストである配列を受け取り、1 回のリクエストで 1 つのオーディエンスを変更します。addContacts が連絡先を作成することはありません。連絡先でないアドレスは missing で返り、それらを作成するのは importContacts です。どちらも繰り返して安全なので、クライアントはネットワーク障害の後にリトライし、リトライは失敗するのではなく、同じ人を処理済みとして報告します。
既定のオーディエンスに追加すると、すべての連絡先がすでに入っているため added は 0 になり、そこへの removeContacts は 409 audience_immutable で拒否されます。オーディエンスから外しても、その人はアドレス帳、既定のオーディエンス、その他のオーディエンスに残ります。
audienceIdstring- 呼び出しが変更したオーディエンス。どちらの結果にも含まれます。
addedint- `addContacts` の結果：この呼び出しで新たに作られたメンバーシップ。
unchangedint- `addContacts` の結果：すでにオーディエンスに入っていた連絡先。それらについては何も書き込まれていません。
removedint- `removeContacts` の結果：この呼び出しで取り除かれたメンバーシップ。
notInAudiencearray- `removeContacts` の結果：オーディエンスに入っていなかったため、何も起きなかった連絡先。
missingarray- 両方。このワークスペースで連絡先でないアドレスを、小文字で重複なく。
インポート
importContacts はオーディエンスのページにある CSV インポートです。contacts が 1〜500 個の配列のリストである配列を受け取り、それぞれ email と省略可能な name を持ちます。正しい形式の各アドレスは、まだ連絡先でなければ連絡先になり、すべてがオーディエンスに入ります。それより長いリストは複数回の呼び出しに分けて送ってください。audiences:write と contacts:write が必要で、どちらかが欠けたキーは 403 insufficient_scope で拒否され、その例外では isScopeMissing() が true です。
すでに連絡先であるアドレスはそのまま使われて名前も保持され、ここでの name は空だった名前を埋めるだけです。新しい連絡先は manual として保存され、既定のオーディエンスにも加わります。アドレス帳から削除されたアドレスは復活します。同じ行を再送しても何も二重に作られないため、クライアントはネットワーク障害の後にこの呼び出しをリトライします。
audienceIdstring- 行が入ったオーディエンス。
createdint- この呼び出しで保存された新しい連絡先。
addedint- このオーディエンスでの新しいメンバーシップ。すでに存在していて、まだ入っていなかった連絡先も数えます。
skippedint- アドレスの形式が正しくなかったためにインポートされなかった行。
invalidarray- 形式の正しくないアドレスを、送られたとおりに。
空にする
empty($id) は 1 回のリクエストで 1 つのオーディエンスからすべての連絡先を外し、contactCount が 0 になった現在のオーディエンスに、取り除いたメンバーシップの数 removed を加えて返します。オーディエンスの id、名前、説明は保持され、すべての連絡先はアドレス帳とその他のオーディエンスに残ります。
元に戻すことはできず、誰がリストに入っていたかはどこにも記録されないため、後で戻したくなるかもしれないなら、先に listAllContacts でたどっておいてください。既定のオーディエンスは空にできず、呼び出しは 409 audience_immutable で拒否されます。2 回目の呼び出しは removed が 0 で成功してしまうため、クライアントはネットワーク障害の後に empty をリトライしません。レスポンスが失われた場合は、get でオーディエンスを読んでください。
増加
growth は、現在で終わる期間に各オーディエンスに加わった連絡先の数と、その期間内に配信停止した数を、日、時間、分の単位で読みます。オーディエンスのページにあるグラフです。名前付き引数を受け取り、audiences:read が必要で、1 つの配列を返します。
$growth = $client->audiences->growth( audienceIds: ['aud_9f2c4b7e1a0d63d84c5f2e7b'], days: 90, grain: 'day', offsetMinutes: intdiv((int) date('Z'), 60),); echo $growth['totals']['added'], ' joins since ', $growth['since'], PHP_EOL; foreach ($growth['series'] as $series) { echo $series['name'], ': ', $series['before'], ' before the window, ', $series['total'], ' now', PHP_EOL;}オーディエンスは誰かが参加した日時を記録し、抜けた日時は記録しないため、どの数値も今日もリストにいる人を参加日で数えたものになり、線が下がることはありません。参加したあとで抜けた連絡先は、どの数値にも含まれません。
パラメーター
audienceIdsstring or array- オーディエンス id を最大 50 個、リストまたはカンマ区切りの 1 つの文字列で指定し、カンマでつないで送ります。すべてのオーディエンスを対象にするには、省略するか空の配列を渡します。このワークスペースのオーディエンスでない id は 404 `audience_not_found` になり、50 個を超えると 422 になります。
daysint- 期間をどこまでさかのぼるか。1〜1095 です。`days:` も `minutes:` も指定しなければ 30 になります。
minutesint- 分単位の期間で、1〜1576800。1 日より短い期間に使います。両方指定すると `days:` より優先されます。
grainstring- 各区切りの大きさ。`day`(既定)、`hour`、`minute` のいずれかです。
offsetMinutesint- 閲覧者の UTC からのずれを分単位で、-840〜840。日と時間の区切りが現地の境目で始まるようにします。既定は 0 です。PHP に設定されたタイムゾーンのずれは `intdiv((int) date('Z'), 60)` で得られます。
レスポンス
sincestring- ISO 8601 の UTC。最初の区切りの始まり。
untilstring- ISO 8601 の UTC。読み取った時点。
totalsarray- `contacts` は何個のリストに入っていても各人を 1 回だけ数え、`memberships` はリストを合計します。そのため、読み取ったリストのうちその人が入っているものの数だけ数えられます。`added` は期間内の参加の合計、`lists` は読み取ったオーディエンスの数、`busiest` は参加が最も多かった区切りで、なければ null です。`subscribed` は、読み取ったオーディエンスの少なくとも 1 つをまだ購読している人を 1 人 1 回ずつ数え、`unsubscribed` は期間内の配信停止を合計します。
seriesarray- オーディエンスごとに 1 項目で、大きい順、次に名前順です。`id`、`name`、`builtin`、現在のメンバー数 `total`、`subscribed`（まだ購読している人）、`before`（`since` より前に参加した人）、`added`（期間内に参加した人）、`unsubscribed`（期間内に配信停止した人）、そして古い順の `buckets` で、それぞれ `bucket`、`added`、`unsubscribed` を持つ配列です。ここでの `builtin` は既定のオーディエンスで `true`、それ以外で `false` で、オーディエンスの配列が持つ文字列ではありません。参加または配信停止があった区切りだけが列挙され、キーはオフセットの現地時刻による `YYYY-MM-DD`、`YYYY-MM-DDTHH`、`YYYY-MM-DDTHH:MM` です。