# API リファレンス：除外リスト

> https://okaeri.tech/developers/reference/suppressions/ の Markdown 版。

除外リスト（`suppressions`）の操作です。共通の決まり（認証・レート制限・エラーの形）は[概要](https://okaeri.tech/developers/index.md)を、型の詳細は[スキーマ](https://okaeri.tech/developers/reference/schemas.md)を参照してください。

- [GET /api/v1/suppressions](https://okaeri.tech/developers/reference/suppressions.md#listSuppressions)　除外リストの一覧（`listSuppressions`）
- [POST /api/v1/suppressions](https://okaeri.tech/developers/reference/suppressions.md#createSuppression)　除外リストへの登録（1件）（`createSuppression`）
- [DELETE /api/v1/suppressions/{suppression_id}](https://okaeri.tech/developers/reference/suppressions.md#deleteSuppression)　除外リストからの削除（`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](https://okaeri.tech/developers/reference/schemas.md#SuppressionListOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## POST /api/v1/suppressions

**除外リストへの登録（1件）**

operationId：`createSuppression`　必要なスコープ：`suppressions:write`

### リクエストの本文（JSON）

型：[SuppressionIn](https://okaeri.tech/developers/reference/schemas.md#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](https://okaeri.tech/developers/reference/schemas.md#SuppressionCreatedOut) |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | `campaign_id` のキャンペーンが見つからない（`not_found`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`suppression_exists`（同じ範囲の有効な除外がある）／`idempotency_key_in_progress`（同じ `Idempotency-Key` の要求が処理中） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |

## DELETE /api/v1/suppressions/{suppression_id}

**除外リストからの削除**

operationId：`deleteSuppression`　必要なスコープ：`suppressions:write`

### パラメータ

| 名前 | 場所 | 型 | 必須 | 説明 |
| --- | --- | --- | --- | --- |
| `suppression_id` | パス | `string`（uuid） | 必須 | — |

### 応答

| ステータス | 説明 | 型 |
| --- | --- | --- |
| 204 | 成功（本文なし） | — |
| 401 | APIキーが無効・失効（`authentication_error`） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 403 | スコープ不足（`permission_error` / `scope_insufficient`）・プランの上限（`plan_limit_exceeded`）・APIキーではできない操作（`session_required` 等） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 404 | 対象が見つからない（`not_found`）。他のテナントの ID を指した時も同じ 404 | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 409 | 状態の衝突（`invalid_request`）。`suppression_not_deletable`（本人の配信停止 `opt_out`・苦情 `complaint` 由来の除外） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 422 | パラメータ不正（`invalid_request`）。`param` に対象の項目名、`message` に理由（日本語） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 429 | レート制限の超過（`rate_limit_error`）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ `X-RateLimit-Limit` の値が正。`Retry-After`（秒）の後に再試行する | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |
| 5XX | サーバ側の失敗（`api_error`）。`request_id` を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ `Idempotency-Key` を付けて再試行する） | [Error](https://okaeri.tech/developers/reference/schemas.md#Error) |