連絡先、オーディエンス、一斉配信

メールを送る相手は 4 つの名前空間で扱います。連絡先はワークスペースのアドレス帳、オーディエンスは名前付きの連絡先リスト、一斉配信はいくつかのオーディエンスの全員に 1 つのメッセージを送るもの、抑止リストはワークスペースが送信しないアドレスを保持するものです。各コマンドは SDK のメソッドを 1 つ呼び出すので、SDK のページでは同じ呼び出しをさらに詳しく説明しています。

• —連絡先には ID がありません。すべての contacts コマンドはアドレスをキーとして受け取り、前後の空白を除いて小文字にするので、[email protected] と [email protected] は同じ連絡先です。オーディエンスには aud_ の ID、一斉配信には brd_ の ID があり、抑止には suppressions list が表示する ID があります。
• —すべての連絡先は、存在する限り既定のオーディエンスに含まれます。そのオーディエンスは削除することも、空にすることも、連絡先を外すこともできず、builtin は default です。
• —アドレス帳はワークスペースに属するので、すべてのメンバーとすべてのキーが同じアドレス帳を読み書きします。
• —各名前空間は openemail contact get のように単数形でも使え、いつもの別名 ls、show、new、edit、rm も使えます。動詞が add と remove の suppressions では、new は add に、rm は remove になります。

ワークスペースのアドレス帳です。メンバーがアプリの作成画面からメールを送った相手と、手動で保存した人が入ります。届いたメールで誰かが追加されることはなく、API や CLI からの送信でも追加されません。

名前付きの連絡先リストで、1 つのワークスペースに最大 100 個作れます。アドレスはオーディエンスに加わる前に連絡先になっている必要があります。例外は import-contacts で、新しいアドレスを処理しながら保存します。

最大 10 個のオーディエンスの全員に 1 つのメッセージを送ります。一人ひとりに別々のコピーとして、差し込みフィールドを埋め、配信停止リンクを付けて送られます。各コピーは通常のメールで、それぞれ独自の msg_ の ID、イベント、Webhook を持ちます。

このワークスペースが送信しないアドレスです。発生時に記録されるハードバウンスと苦情、そして手動で追加したアドレスが入ります。これらのアドレスへの送信は、何かが送り出される前にその受信者について拒否されます。

ほとんどのコマンドには、その名前空間の読み取りまたは書き込みのスコープが必要です。別のものを読んだり変更したりするため、別のスコープが必要なコマンドもいくつかあります：

• —特定のアドレスやドメインに限定されたキーも、他のすべてのキーと同じアドレス帳を読み書きします。見えるのは自分が持つアドレスやドメインから送られた一斉配信だけで、list-people からは保存された連絡先だけを得ます。また、contacts list-threads、activity、block、unblock、そして suppressions add と remove では 422 capability_unsupported で拒否されます。
• —一部のアドレスにしか届かないメンバーのブラウザでのサインインは、すべての contacts、audiences、broadcasts コマンドで 422 capability_unsupported で拒否されます。suppressions add は、ワークスペースのオーナー以外によるブラウザでのサインインを拒否します。

ファイルからオーディエンスを作り、そこへの一斉配信が誰に届くかを数えます。import-contacts はまだ連絡先でないアドレスを保存し、もう一度実行しても何も二重に作成や追加はされません。

[  { "email": "[email protected]", "name": "Ada Lovelace" },  { "email": "[email protected]", "name": "Grace Hopper" },  { "email": "[email protected]" }]

AUDIENCE=$(openemail audiences create --name 'Product updates' --json | jq -r .id)openemail audiences import-contacts "$AUDIENCE" --contacts @contacts.jsonopenemail broadcasts preview --audience-ids "$AUDIENCE"

リクエストを表示するだけで何も送らない --dry-run で一斉配信を確認してから送信します。一斉配信はすぐに作成され、バックグラウンドで送信されるので、get をポーリングして進み具合を追ってください。この本文には {{unsubscribeUrl}} が置かれていないため、各コピーに 1 行の配信停止フッターが付きます。

{  "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>",  "scheduledAt": "2026-10-01T09:00:00Z"}

openemail broadcasts send --data @broadcast.json --dry-runBROADCAST=$(openemail broadcasts send --data @broadcast.json --yes --json | jq -r .id)openemail broadcasts get "$BROADCAST"openemail broadcasts stats "$BROADCAST" --grain day

一斉配信が誰に届かなかったかを確認します。--ndjson は 1 行に 1 人の受信者を、--all --json はすべてのページを含む 1 つのドキュメントを出力します。

openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter bounced --ndjson | jq -r .emailopenemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter not_opened --all --json | jq ".items | length"openemail suppressions list --reason bounce --all --max 50

あるオーディエンスの購読中のメンバーを別のオーディエンスにコピーします。jq がストリームを add-contacts が受け取る本文に変換し、--data - がそれを stdin から読みます。--max 200 で、1 回の呼び出しが受け付ける 200 件のアドレスに収めます。

openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --statuses subscribed --max 200 --ndjson \  | jq -s '{ emails: map(.email) }' \  | openemail audiences add-contacts aud_1c4e7a9b2d0f36e85a7c1b4d --data -

作成画面が記録した、あるドメインの連絡先をすべて削除します。delete-many は 1 回の呼び出しで最大 200 件のアドレスを受け付けるので、長いリストは xargs -n 200 で分割します。元に戻せないので、先に --dry-run で各バッチを確認してください。

openemail contacts list --source auto --all --ndjson \  | jq -r 'select(.email | endswith("@old-vendor.example")) | .email' > leaving.txtxargs -n 200 openemail contacts delete-many --dry-run < leaving.txtxargs -n 200 openemail contacts delete-many --yes < leaving.txt

アドレスへの送信を止め、別のアドレスを再び許可し、送信者をブロックします。removable は、suppressions remove がどの行を受け付けるかを示します。

openemail suppressions add --email [email protected]openemail suppressions list --q [email protected] --json | jq -r '.items[] | select(.removable) | .id'openemail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --yesopenemail contacts block [email protected]

次のコマンドは、ターミナルで実行する前に確認を求めます：

• —--yes は代わりに確認します。--json や --no-input を付けたとき、CI の中、またはターミナルがないときの無人実行では、確認を求めるはずのコマンドは Refusing to run unattended. Pass --yes to confirm. と終了コード 2 で停止します。
• —--dry-run はコマンドが送るはずのリクエストを表示し、確認も変更もせずに終了コード 0 で終了します。
• —ブラウザでサインインしている場合、audiences delete は、Web アプリと同じようにまず確認コードを求めます。--yes でこれを省略することはできず、無人実行ではコマンドは終了コード 4 で停止します。事前に openemail verify を実行するか、確認コードを求められることのない API キーを使ってください。
• —audiences empty は確認コードを求めないので、--yes を渡す前に ID を確認してください。

一覧を返すコマンドはどれも 1 ページを読みます。続きがある場合は、表示されたカーソルを同じ絞り込み条件とともに --cursor に渡すか、すべて読みます：

• —--all はすべてのページを読んで項目をストリームします。ターミナルでは表として、パイプしたときや --ndjson を付けたときは 1 行に 1 つの JSON オブジェクトとして出力します。
• —--max <n> はその件数で停止し、--all を含意します。
• —--json は、--all の場合も含めて 1 つの { items, hasMore, nextCursor } ドキュメントを出力します。
• —形式が正しくないカーソルや古いカーソルは 400 invalid_cursor になります。カーソルなしで最初からやり直してください。

• —contacts create はすでにアドレス帳にあるアドレスを 409 contact_exists で拒否するので、再試行によって誰かが編集した名前が上書きされることはありません。contacts save は決して拒否せず、アドレスがどの状態でも、保存、維持、または復活させます。
• —contacts delete は、メールに登場しただけのアドレスも受け付け、その人を list-people から外します。メールは残ります。元に戻すことはできず、アドレスを再び保存すると、名前もメモもなく、既定のオーディエンス以外には所属しない連絡先として始まります。
• —アドレスは連絡先の識別子なので、contacts update では変更できません。連絡先を移すには delete と create を行います。
• —contacts set-photo は画像をファイルから、または - で stdin から読みます。image/jpeg のように --content-type を渡してください。付けないと画像が application/octet-stream として送られることがあり、サーバーはそれを 422 invalid_image で拒否します。
• —broadcasts send --scheduled-at は、2026-10-01T09:00:00Z のような ISO 8601 の日時か、PT2H や P1D のような ISO 8601 の期間を、365 日後まで受け付けます。send --at が受け付ける 2h のような短い遅延は、ここでは拒否されます。
• —差し込みフィールドは --subject、--html、--text で使えます。{{firstName}}、{{lastName}}、{{name}}、{{email}}、{{unsubscribeUrl}} で、{{firstName|there}} のように縦棒の後に代替値を書けます。{{unsubscribeUrl}} を置いていない本文には 1 行の配信停止フッターが付きます。テンプレートはそのまま送られるので、リンクはテンプレートに入れてください。
• —一斉配信は、何かが書き込まれる前にプランの月間送信数と照合され、各コピーは 1 回の送信として数えられます。枠で賄えない一斉配信は 429 send_quota_exceeded で拒否され、何も残りません。
• —スクリプトがその手順をもう一度実行する可能性がある場合は、broadcasts send に独自の --idempotency-key を渡してください。同じキーでは、新しく送る代わりに、そのキーで作成された一斉配信が返ります。
• —一斉配信から配信停止した連絡先は、unsubscribedAt が設定された状態でオーディエンスに残り、そのオーディエンスへの以降の一斉配信ではスキップされます。audiences list-contacts --statuses unsubscribed でそれらを一覧表示できます。
• —ハードバウンスは抑止リストに残ります。suppressions remove はそれを 409 suppression_not_removable で拒否し、各行の removable で事前にわかります。