一斉配信

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)puts reach[:recipients], reach[:unsubscribed], reach[:suppressed] broadcast = client.broadcasts.send(draft) latest = client.broadcasts.get(broadcast[:id])while %w[scheduled queued sending].include?(latest[:status])  sleep 5  latest = client.broadcasts.get(broadcast[:id])end client.broadcasts.iterate_recipients(broadcast[:id]) do |copy|  puts copy[:email], copy[:status], copy[:opens], copy[:clicks]end bounced = client.broadcasts.list_recipients(broadcast[:id], filter: "bounced")bounced.items.each { |row| puts "#{row[:emailId]} #{row[:email]}" } copy = client.broadcasts.get_recipient(broadcast[:id], "msg_01dad25067bc4dac966d515d")puts copy[:subject], copy[:bouncedAt] stats = client.broadcasts.stats(broadcast[:id], grain: "day")puts stats.dig(:totals, :opened), stats.dig(:totals, :clicked), stats.dig(:totals, :unsubscribed) lately = client.broadcasts.stats(broadcast[:id], days: 1)puts lately.dig(:window, :opened) later = client.broadcasts.send(draft, scheduledAt: "P1D")client.broadcasts.cancel(later[:id]) history = client.broadcasts.list(audience_id: draft[:audienceIds].first)puts latest[:status], latest.dig(:counts, :sent), history.items.size month = client.broadcasts.analytics(days: 30)month[:broadcasts].each do |row|  puts row[:subject], row[:sent], row[:opened]end

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

send はすぐに queued の一斉配信を返し、scheduledAt: を渡した場合は scheduled で返します。送信はバックグラウンドで続きます。send には emails:send と audiences:read、preview には audiences:read が必要です。list、list_all、iterate、get、list_recipients、list_all_recipients、iterate_recipients、get_recipient、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: Time.now + 3600,  idempotency_key: "doors-open-2026-10") puts broadcast[:id], broadcast[:status], broadcast[:replayed]

一斉配信のフィールドはキーワード引数または 1 つの Hash で、API の camelCase の名前のままです（audienceIds:、scheduledAt:）。idempotency_key: と api_key: は呼び出しのオプションで、フィールドとして送られることはありません。Hash と並べて渡したキーワード引数はその Hash にマージされるため、send(draft, scheduledAt: "P1D") は同じ下書きを 1 日後に送ります。scheduledAt: は Time、DateTime、ISO 8601 の文字列、または PT2H のような期間を受け取り、Time は UTC の時刻として送られます。preview は渡されたものから audienceIds だけを送るため、send と同じ Hash を受け取れます。レスポンスは Symbol キーの Hash なので、broadcast[:status] でステータスを読めます。

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

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

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

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

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

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

preview は何も送らずに同じ数、recipients、unsubscribed、suppressed を返します。誰にも届かない send は 422 no_recipients を OpenEmail::ValidationError として送出します。

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

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

list_recipients は、一斉配信の宛先となった人たちを、コピーごとに 1 行、アドレス順に並べた OpenEmail::Page を 1 つ、items、has_more?、next_cursor 付きで返します。list_all_recipients はすべてのページをたどって 1 つの Array にまとめ、iterate_recipients はコピーを 1 通ずつブロックに yield し、ループが求めたときにだけ次のページを取得します。ブロックがなければ Enumerator を返します。limit: は 1〜200 で既定は 50、cursor: は同じ filter: と q: とともに渡し返します。

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

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

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

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

send、get、cancel はそれぞれこれを Symbol キーの Hash として 1 つ返し、send は replayed を加えます。list はこれらの OpenEmail::Page を新しい順で返し、list_all と iterate はすべてのページをたどります。preview は audienceIds、recipients、unsubscribed、suppressed を持つ Hash を返します。list_recipients は受信者の行の OpenEmail::Page を返し、get_recipient は内容付きの行を 1 つ返し、stats は broadcastId、grain、totals、window、series を持つ Hash を返します。analytics は totals、series と、broadcasts に一斉配信ごとに 1 行を持つ Hash を返します。時刻は ISO 8601 の文字列で、Time.iso8601 でパースできます。

list_recipients、list_all_recipients、iterate_recipients の各行で、Symbol キーの Hash です。get_recipient が返す Hash は subject、html、text を加えたものです。