API リファレンス：除外リスト
除外リスト（suppressions）の操作です。共通の決まり（認証・レート制限・エラーの形）は概要を、型の詳細はスキーマを参照してください。
AI・コーディングエージェント向けにこのページの Markdown 版とllms.txtがあります。
- GET /api/v1/suppressions 除外リストの一覧（
listSuppressions） - POST /api/v1/suppressions 除外リストへの登録（1件）（
createSuppression） - DELETE /api/v1/suppressions/{suppression_id} 除外リストからの削除（
deleteSuppression）
GET /api/v1/suppressions
除外リストの一覧
operationId：listSuppressions 必要なスコープ：suppressions:read
パラメータ
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
q | クエリ | string（null 可） | — | — |
kind | クエリ | string（null 可） | — | 値：email・tel（今後増えることがある） |
reason | クエリ | string（null 可） | — | 値：opt_out・manual・bounce・complaint・undeliverable（今後増えることがある） |
scope | クエリ | string（null 可） | — | 値：tenant・campaign（今後増えることがある） |
campaign_id | クエリ | string（uuid）（null 可） | — | — |
limit | クエリ | integer | — | 1〜200・既定値 50 |
cursor | クエリ | string（null 可） | — | — |
応答
| ステータス | 説明 | 型 |
|---|---|---|
| 200 | 成功 | SuppressionListOut |
| 401 | APIキーが無効・失効（authentication_error） | Error |
| 403 | スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等） | Error |
| 422 | パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語） | Error |
| 429 | レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する | Error |
| 5XX | サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する） | Error |
POST /api/v1/suppressions
除外リストへの登録（1件）
operationId：createSuppression 必要なスコープ：suppressions:write
リクエストの本文（JSON）
型：SuppressionIn（必須）
| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
scope | string | — | 値：tenant・campaign（今後増えることがある） 既定値 "tenant" |
campaign_id | string（uuid）（null 可） | — | — |
expires_at | string（date-time）（null 可） | — | — |
memo | string（null 可） | — | — |
value | string（null 可） | — | — |
応答
| ステータス | 説明 | 型 |
|---|---|---|
| 201 | 成功 | SuppressionCreatedOut |
| 401 | APIキーが無効・失効（authentication_error） | Error |
| 403 | スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等） | Error |
| 404 | campaign_id のキャンペーンが見つからない（not_found） | Error |
| 409 | 状態の衝突（invalid_request）。suppression_exists（同じ範囲の有効な除外がある）／idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中） | Error |
| 422 | パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語） | Error |
| 429 | レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する | Error |
| 5XX | サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する） | Error |
DELETE /api/v1/suppressions/{suppression_id}
除外リストからの削除
operationId：deleteSuppression 必要なスコープ：suppressions:write
パラメータ
| 名前 | 場所 | 型 | 必須 | 説明 |
|---|---|---|---|---|
suppression_id | パス | string（uuid） | 必須 | — |
応答
| ステータス | 説明 | 型 |
|---|---|---|
| 204 | 成功（本文なし） | — |
| 401 | APIキーが無効・失効（authentication_error） | Error |
| 403 | スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等） | Error |
| 404 | 対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404 | Error |
| 409 | 状態の衝突（invalid_request）。suppression_not_deletable（本人の配信停止 opt_out・苦情 complaint 由来の除外） | Error |
| 422 | パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語） | Error |
| 429 | レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する | Error |
| 5XX | サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する） | Error |