# テストメールを送信する

`POST /v1/email-templates/{family}/{locale}:test-send` · 権限 `email-templates:write` · Startup プラン以上

[プレビュー](preview.md) と同じサンプルデータを使ってメールテンプレートの 1 つのバージョンをレンダリングし、通常の配信経路で 1 つのアドレスに送信します。実際の受信トレイで内容を確認できます。件名の先頭には `[TEST] ` が付きます。送信前にテンプレートが再度検証されます。

ルール:

- 受信者は、ダッシュボードアカウントの `active` なメンバーの確認済みメールアドレスである必要があります。それ以外のアドレスは拒否され、そのアドレスがレスポンスやログに再度出力されることはありません。
- 各環境で送信できるテストメールは UTC の 1 日あたり最大 20 通です。21 通目は、次の UTC の日まで `429` で拒否されます (`Retry-After` に待機秒数が示されます)。
- 抑止リストは引き続き適用されます。受信者が抑止されている場合、メッセージは状態 `suppressed` で記録され、配信されません。それでも 1 日の上限にはカウントされます。
- 環境はカスタムテンプレートを送信できる必要があります。配信モードが `platform_default` である場合、または送信が制限・停止されている場合、テスト送信は拒否されます。
- 受け付けられた各テスト送信は、管理者の監査ログに `email_template.test_sent` として記録されます。記録にはファミリー、ロケール、バージョンが含まれますが、受信者は含まれません。

## パスパラメーター

| パラメーター | 説明 |
|---|---|
| `family` | メールファミリー。例: `verify_email` や `email_otp` ([メールテンプレートの一覧](list.md) を参照)。 |
| `locale` | ロケールタグ。例: `en` や `de`。 |

## ヘッダー

| ヘッダー | 説明 |
|---|---|
| `Idempotency-Key` | 省略可能。16〜64 文字の `A-Z a-z 0-9 _ -`。同じキーでリクエストを繰り返すと、最初のメッセージが返され、再送信やカウントは行われません。SDK と CLI がこの値を自動的に設定します。 |

## リクエスト

| フィールド | 型 | 説明 |
|---|---|---|
| `to` | string | 必須。受信者: 表示名を含まない、`active` なダッシュボードメンバーの確認済みアドレス。大文字と小文字の違いや前後の空白は無視されます。 |
| `version` | integer | 送信する保存済みバージョン (1 以上)。既定値: 最新のバージョン。 |
| `published` | boolean | `true` の場合、公開済みのバージョンを送信します。`version` と同時に指定することはできません。 |

## レスポンス

`200 OK`

```json
{
  "message_id": "0199f3c4-5d6e-7a8b-9c0d-1e2f3a4b5c6d",
  "state": "queued",
  "version": 3,
  "accepted_at": "2026-10-19T09:00:00Z"
}
```

| フィールド | 説明 |
|---|---|
| `message_id` | メッセージの識別子。 |
| `state` | `queued` (まもなく送信されます) または `suppressed` (受信者が抑止リストに含まれています)。同じリクエストを繰り返すと、最初のメッセージの現在の状態が返されます。これは `sent`、`failed`、`expired` の場合もあります。 |
| `version` | 送信されたバージョン。 |
| `accepted_at` | メッセージが受け付けられた日時。 |

## エラー

| HTTP | code | 発生するとき |
|---|---|---|
| 400 | `unknown_field` | ボディに未知のフィールドがあるか、JSON オブジェクトではありません。 |
| 400 | `malformed_request` | ボディが有効な JSON ではないか、`Idempotency-Key` の形式が不正または重複しています。 |
| 401 | `unauthenticated` | 認証情報が見つからない、無効である、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 403 | `plan_feature_unavailable` | 環境のプランにカスタムメールテンプレートが含まれていません (Startup プラン以上。必要なプランは `required_plan` に示されます)。 |
| 404 | `not_found` | ファミリーまたはロケールが不明である、バージョンが存在しない、または `published` が指定されていて公開済みのものがありません。 |
| 409 | `email_template_not_deliverable` | 環境の配信モードまたは送信状態では、カスタムテンプレートを送信できません。 |
| 422 | `validation_failed` | `to` がないか、プレーンなメールアドレスではない、`version` が 1 未満である、`version` と `published` の両方が送信された (`conflicts_with_published`)、またはバージョンが検証に通らなくなっています。 |
| 422 | `template_forbidden_construct` | バージョンがサンドボックスの対象外の Liquid 構文を使用しています。 |
| 422 | `test_recipient_not_allowed` | 受信者が、`active` なダッシュボードメンバーの確認済みアドレスではありません。 |
| 429 | `rate_limited` | 環境で、この UTC の日に既に 20 通のテストメールを送信しています。または API のレート制限を超えました。`Retry-After` の期間を過ぎてから再試行してください。 |
| 503 | `test_recipient_source_unavailable` | 現在、受信者を確認できません。何も送信されていません。`Retry-After` の期間を過ぎてから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の期間を過ぎてから再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/email-templates/verify_email/en:test-send \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-send-verify-email-en-0001" \
  -d '{"to":"you@example.com","version":3}'
```

CLI: `keenauth email-templates test-send verify_email en --to you@example.com --version 3`

## 個人データ

このエンドポイントは個人データを扱います。ダッシュボードのユーザーとアカウントの連絡先が対象です。[KeenAuth API における個人データ](/docs/policies/personal-data) には、保存される内容、保持期間、削除方法が記載されています。どのフィールドにも、特別なカテゴリーの個人データ (健康、生体情報、宗教、政治的意見、性的指向) を送信しないでください。