一斉配信

const 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' },} const reach = await openemail.broadcasts.preview(draft)console.log(reach.recipients, reach.unsubscribed, reach.suppressed) const broadcast = await openemail.broadcasts.send(draft) let latest = await openemail.broadcasts.get(broadcast.id)while (['scheduled', 'queued', 'sending'].includes(latest.status)) {  await new Promise((resolve) => setTimeout(resolve, 5_000))  latest = await openemail.broadcasts.get(broadcast.id)} for await (const copy of openemail.emails.iterate({ broadcastId: broadcast.id })) {  console.log(copy.id, copy.status)} const later = await openemail.broadcasts.send({ ...draft, scheduledAt: 'P1D' })await openemail.broadcasts.cancel(later.id) const history = await openemail.broadcasts.list({ audienceId: draft.audienceIds[0] })console.log(latest.status, latest.counts.sent, history.items.length)

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

send はすぐに queued の一斉配信で解決し、scheduledAt を渡した場合は scheduled で解決します。送信はバックグラウンドで続きます。send には emails:send と audiences:read、preview には audiences:read、list、listAll、iterate、get には 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.listContacts でそれを示します。その人はオーディエンスとアドレス帳に残り、他のオーディエンスには影響せず、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 を投げ、キャンセル済みの一斉配信をキャンセルするとその時点の状態で解決します。

send、get、cancel はそれぞれこれを 1 つ返して解決します。list はこれを並べたページ { items, hasMore, nextCursor } を新しい順に返し、listAll と iterate はすべてのページをたどります。preview は audienceIds、recipients、unsubscribed、suppressed を持つ BroadcastPreviewResource で解決します。