一斉配信

import time from openemail import openemailfrom openemail.types import BroadcastCreate draft: BroadcastCreate = {    '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 = openemail.broadcasts.preview(draft)print(reach['recipients'], reach['unsubscribed'], reach['suppressed']) broadcast = openemail.broadcasts.send(draft) latest = openemail.broadcasts.get(broadcast['id'])while latest['status'] in ('scheduled', 'queued', 'sending'):    time.sleep(5)    latest = openemail.broadcasts.get(broadcast['id']) for copy in openemail.broadcasts.iterate_recipients(broadcast['id']):    print(copy['email'], copy['status'], copy['opens'], copy['clicks']) bounced = openemail.broadcasts.list_recipients(broadcast['id'], filter='bounced')if bounced['items']:    content = openemail.broadcasts.get_recipient(broadcast['id'], bounced['items'][0]['emailId'])    print(content['subject'], content['bouncedAt']) stats = openemail.broadcasts.stats(broadcast['id'], grain='day')print(stats['totals']['opened'], stats['totals']['clicked'], stats['totals']['unsubscribed']) lately = openemail.broadcasts.stats(broadcast['id'], days=1)print(lately['window']['opened'] if lately['window'] else None) month = openemail.broadcasts.analytics(days=30)for row in month['broadcasts']:    print(row['subject'], row['sent'], row['opened']) later = openemail.broadcasts.send({**draft, 'scheduledAt': 'P1D'})openemail.broadcasts.cancel(later['id']) history = openemail.broadcasts.list(audience_id=draft['audienceIds'][0])print(latest['status'], latest['counts']['sent'], len(history['items']))

一斉配信は、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 が必要です。

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

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

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

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

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

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

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

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

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

list_recipients は、一斉配信の宛先となった人たちを、コピーごとに 1 行、アドレス順に並べた 1 ページを、items、hasMore、nextCursor を持つ dict として返します。list_all_recipients はすべてのページをたどって 1 つのリストにまとめ、iterate_recipients はコピーを 1 通ずつ返し、ループが求めたときにだけ次のページを取得します。limit は 1 から 200 までで既定は 50、cursor は同じ filter と q とともに渡します。

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

get_recipient(id, email_id) はコピーを 1 通返します。同じ行に加え、その人が受け取ったとおりの subject、html、text を、差し込みフィールドを埋め、その人専用の登録解除リンクを付けた状態で含みます。HTML は開封とクリックのトラッキングを追加する前のものです。この一斉配信のコピーではない email_id は 404 recipient_not_found を、存在しない一斉配信は 404 broadcast_not_found を送出します。

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

get と cancel はそれぞれこれを 1 つ返し、send は SentBroadcastResource を返します。これは同じフィールドに replayed を加えたもので、同じ冪等性キーを使った以前の呼び出しが作成した一斉配信が返ってきた場合に True になります。list はこれを並べたページを、items、hasMore、nextCursor を持つ dict として新しい順に返し、list_all と iterate はすべてのページをたどります。preview は audienceIds、recipients、unsubscribed、suppressed を持つ BroadcastPreviewResource を返します。list_recipients は BroadcastRecipientResource 行のページ、get_recipient は BroadcastRecipientContentResource、stats は BroadcastStatsResource を返します。

list_recipients、list_all_recipients、iterate_recipients の各行です。get_recipient が返す BroadcastRecipientContentResource は、これに subject、html、text を加えます。

• broadcasts.preview()完全なリファレンス
• broadcasts.send()完全なリファレンス
• broadcasts.list()完全なリファレンス
• broadcasts.list_all()完全なリファレンス
• broadcasts.iterate()完全なリファレンス
• broadcasts.get()完全なリファレンス
• broadcasts.list_recipients()完全なリファレンス
• broadcasts.list_all_recipients()完全なリファレンス
• broadcasts.iterate_recipients()完全なリファレンス
• broadcasts.get_recipient()完全なリファレンス
• broadcasts.stats()完全なリファレンス
• broadcasts.analytics()完全なリファレンス
• broadcasts.cancel()完全なリファレンス