一斉配信

use OpenEmail\Constants\BroadcastRecipientFilters;use OpenEmail\Constants\BroadcastStatuses; $draft = [    'audienceIds' => ['aud_4c1b8e2a7d9f05c36b4e8a71'],    'from' => 'Acme <[email protected]>',    'subject' => '{{firstName|Hello}}, the September release is out',    'html' => '<p>Hi {{firstName|there}},</p><p>Here is what changed this month.</p>',    'text' => 'Hi {{firstName|there}}, here is what changed this month. Unsubscribe: {{unsubscribeUrl}}',    'tags' => ['campaign' => 'release-2026-09'],]; $reach = $client->broadcasts->preview($draft);echo $reach['recipients'], ' ', $reach['unsubscribed'], ' ', $reach['suppressed'], PHP_EOL; $broadcast = $client->broadcasts->send($draft); $latest = $client->broadcasts->get($broadcast['id']); while (in_array($latest['status'], [BroadcastStatuses::SCHEDULED, BroadcastStatuses::QUEUED, BroadcastStatuses::SENDING], true)) {    sleep(5);    $latest = $client->broadcasts->get($broadcast['id']);} foreach ($client->broadcasts->iterateRecipients($broadcast['id']) as $copy) {    echo $copy['email'], ' ', $copy['status'], ' ', $copy['opens'], ' ', $copy['clicks'], PHP_EOL;} $bounced = $client->broadcasts->listRecipients($broadcast['id'], filter: BroadcastRecipientFilters::BOUNCED); foreach ($bounced as $row) {    echo $row['emailId'], ' ', $row['email'], PHP_EOL;} $copy = $client->broadcasts->getRecipient($broadcast['id'], 'msg_01dad25067bc4dac966d515d');echo $copy['subject'], ' ', $copy['bouncedAt'] ?? 'not bounced', PHP_EOL; $stats = $client->broadcasts->stats($broadcast['id'], grain: 'day');echo $stats['totals']['opened'], ' ', $stats['totals']['clicked'], ' ', $stats['totals']['unsubscribed'], PHP_EOL; $lately = $client->broadcasts->stats($broadcast['id'], days: 1);echo $lately['window']['opened'] ?? 0, PHP_EOL; $later = $client->broadcasts->send([...$draft, 'scheduledAt' => 'P1D']);$client->broadcasts->cancel($later['id']); $history = $client->broadcasts->list(audienceId: $draft['audienceIds'][0]);echo $latest['status'], ' ', $latest['counts']['sent'], ' ', count($history), PHP_EOL; $month = $client->broadcasts->analytics(days: 30); foreach ($month['broadcasts'] as $row) {    echo $row['subject'], ' ', $row['sent'], ' ', $row['opened'], PHP_EOL;}

一斉配信は、1 つ以上のオーディエンス内の全員に 1 通のメッセージを、一人ずつ別のコピーとして送ります。各コピーの受信者はちょうど一人で cc も bcc もないため、他に誰に送られたかは誰にも見えず、各コピーは独自の msg_ ID、イベント、トラッキング、Webhook を持つ普通のメールです。listRecipients で、それぞれがどうなったかとあわせて一覧できます。一斉配信そのものが記録なので、コピーは「送信済み」フォルダに保存されません。

send はすぐに queued の一斉配信を返し、ボディに scheduledAt がある場合は scheduled で返します。送信はバックグラウンドで続きます。send には emails:send と audiences:read、preview には audiences:read が必要です。list、listAll、iterate、get、listRecipients、listAllRecipients、iterateRecipients、getRecipient、stats、analytics には emails:read、cancel には emails:send が必要です。

$broadcast = $client->broadcasts->send([    'audienceIds' => ['aud_4c1b8e2a7d9f05c36b4e8a71'],    'from' => 'Acme <[email protected]>',    'subject' => 'Doors open on Friday',    'text' => 'Hi {{firstName|there}}, doors open at nine. Unsubscribe: {{unsubscribeUrl}}',    'scheduledAt' => new \DateTimeImmutable('+1 hour'),], idempotencyKey: 'doors-open-2026-10'); echo $broadcast['id'], ' ', $broadcast['status'], ' ', $broadcast['replayed'] ? 'replayed' : 'new', PHP_EOL;

一斉配信のフィールドは、API の camelCase の名前（audienceIds、scheduledAt）をキーとする 1 つの配列です。idempotencyKey: と apiKey: は呼び出しの名前付き引数で、フィールドとして送られることはありません。下書きをフィールドと並べて新しい配列に展開すると、その 1 か所だけを変えた同じ下書きが送られます。そのため send([...$draft, 'scheduledAt' => 'P1D']) は 1 日後に送ります。scheduledAt は DateTimeInterface、ISO 8601 の文字列、または PT2H のような期間を受け取り、DateTimeInterface は UTC の時刻として送られます。preview は渡されたものから audienceIds だけを送るため、send と同じ配列を受け取れます。レスポンスは camelCase のキーを持つ配列なので、$broadcast['status'] でステータスを読めます。

subject、html、text は一人ひとりの連絡先から埋められます。{{firstName}} は連絡先の名前の最初の語、{{lastName}} は残り、{{name}} は名前全体、{{email}} はコピーの送り先アドレス、{{unsubscribeUrl}} はその人を配信停止にするリンクです。

各項目はバーの後に代替値を取り、連絡先に値がないときに使われるので、名前なしで保存された連絡先では {{firstName|there}} が "there" になります。html では値がエスケープされ、他の {{…}} は書かれたとおりに残ります。

保存済みのテンプレートを送るには、html と text の代わりに template を、id と省略可能な version、props、slots を持つ配列として渡します。同じ 5 つの値がプロパティとして渡されますが、テンプレートが宣言しているものに限られるので、firstName を宣言しているテンプレートはそれを受け取り、宣言していないテンプレートがそのせいで拒否されることはありません。props の内容はすべてのコピーに同じように入ります。

どのコピーにもワンクリック配信停止ヘッダーが付き、メールクライアントが独自の配信停止ボタンを表示できます。これは大手のメールボックス事業者が一括メールに求めているものです。{{unsubscribeUrl}} を自分で置いていない html または text の本文には、リンク付きの 1 行のフッターが付きます。テンプレートはそのまま送られるので、テンプレートに {{unsubscribeUrl}} を入れてください。

配信停止すると、その一斉配信が送られたすべてのオーディエンスでその人が配信停止として記録され、オーディエンスのページで説明しているとおり、audiences->listContacts がその人の行の unsubscribedAt でそれを示します。その人はオーディエンスとアドレス帳に残り、他のオーディエンスには影響せず、1 通ずつ送るメールは引き続き届きます。オーディエンスから外して追加し直すと、改めて購読状態になります。

一斉配信は audienceIds のうち少なくとも 1 つに入っているすべての連絡先に、いくつに入っていても 1 回だけ届きます。スキップされるのは、それらのオーディエンスのうち自分が入っているすべてで配信停止した連絡先と、バウンスや苦情のため、あるいは誰かが追加したために抑止リストにあるアドレスです。send の後、送信が届く前にオーディエンスに追加された連絡先には届きます。

preview は何も送らずに同じ数、recipients、unsubscribed、suppressed を返します。誰にも届かない send は 422 no_recipients を ValidationException としてスローします。

get はコピーから counts を直接読むので、一斉配信の送信中は、上のサンプルのように呼び出しの間に sleep() を挟んでこれをポーリングしてください。status は scheduled または queued から sending に進み、渡したすべてのコピーが送られたか失敗すると sent で落ち着きます。completedAt が最後の人に届いたことを示した後でも、送信待ちのコピーがある間は sending のままです。failed は一斉配信全体が止まったことを意味し、lastError が理由を示します：from アドレスから送信できなくなった、テンプレートが解決できなくなった、途中でプランが尽きた、送信自体が失敗し続けた、またはコピーを 1 通も書き込めなかった、のいずれかです。

cancel は scheduled、queued、sending の一斉配信を止めます。新たに誰も追加されず、送信待ちのコピーはすべてキャンセルされますが、送られたコピーは取り消せません。すべてのコピーが送られた後の cancel は 409 broadcast_not_cancellable を ConflictException としてスローし、キャンセル済みの一斉配信をキャンセルするとその時点の状態で返します。

listRecipients は、一斉配信の宛先となった人たちを、コピーごとに 1 行、アドレス順に並べた OpenEmail\Result\Page を 1 つ、items、hasMore、nextCursor 付きで返します。listAllRecipients はすべてのページをたどって 1 つの配列にまとめ、iterateRecipients はコピーを 1 通ずつ yield し、ループが求めたときにだけ次のページを取得する Generator を返します。limit: は 1〜200 で既定は 50、cursor: は同じ filter: と q: とともに渡し返します。

OpenEmail\Constants\BroadcastRecipientFilters が各フィルターを定義し、q: はアドレスと名前を大文字と小文字を区別せずに検索します。開封とクリックには画像プロキシとリンクスキャナーによるものは含まれず、トラッキングをオフにして送信した一斉配信では 0 のままです。

getRecipient($id, $emailId) はコピーを 1 通返します。同じ行に加え、その人が受け取ったとおりの subject、html、text を、差し込み項目を埋め、その人専用の配信停止リンクを付けた状態で含みます。行の emailId を第 2 引数として渡してください。HTML は開封とクリックのトラッキングを追加する前のものです。この一斉配信のコピーではない emailId は 404 recipient_not_found を、存在しない一斉配信は 404 broadcast_not_found を、どちらも NotFoundException としてスローします。

stats は合計と系列を返します。totals は sent、delivered、bounced、complained、failed のコピー数と、まだ待機中のものを表す pending、そして opened、clicked、unsubscribed した人数を数え、opens と clicks をイベント数として持ちます。series は疎で古い順で、何かが起きた grain:（minute、hour、day、既定は hour）ごとに 1 つのバケットがあり、UTC から東へ offsetMinutes: 分ずらしたタイムゾーンで区切られます。ローカルのタイムゾーンには intdiv((int) date('Z'), 60) を渡してください。各人はそれが初めて起きた時点で 1 回だけ数えられるため、合計と一致します。

最近起きたことも読むには、stats に days: または minutes: を渡します。すると window がその期間内の配信、バウンス、迷惑メール報告、開封、クリック、配信停止を数え、series はその期間のバケットだけを残します。totals は引き続き一斉配信全体を対象とします。どちらも指定しなければ window は null です。

send、get、cancel はそれぞれこれを camelCase のキーを持つ配列として 1 つ返し、send は replayed を加えます。list はこれらの OpenEmail\Result\Page を新しい順で返し、listAll はすべてを 1 つの配列で返し、iterate はそれらをたどる Generator を返します。preview は audienceIds、recipients、unsubscribed、suppressed を持つ配列を返します。listRecipients は受信者の行の Page を返し、getRecipient は内容付きの行を 1 つ返し、stats は broadcastId、grain、totals、window、series を持つ配列を返します。analytics は totals、series と、broadcasts に一斉配信ごとに 1 行を持つ配列を返します。時刻は ISO 8601 の文字列で、new \DateTimeImmutable() で読めます。

listRecipients、listAllRecipients、iterateRecipients の各行で、camelCase のキーを持つ配列です。getRecipient が返す配列は subject、html、text を加えたものです。