# メールプロバイダーをテストする

`POST /v1/email-provider:test` · 権限 `email-provider:write` · すべてのプラン

メッセージを送信せずに、保存された接続を確認します:

- `customer_smtp`: お使いのサーバーに接続し、TLS を設定し、認証してから終了します。
- `customer_api`: 保存されたキーを使って、プロバイダーの読み取り専用エンドポイントを呼び出します。

確認に失敗した場合でも応答は `200 OK` です。`result` には `ok` または固定のエラーコードが入ります。サーバーが返した応答テキストは返されません。結果は [get](get.md) の `last_test_at` と `last_test_result` に保存されます。`ETag` は変わりません。テストを行うたびに監査レコード (`email_provider.tested`) が書き込まれます。

1 つの環境では 1 時間あたり 10 回までテストを実行できます。リクエストボディは省略可能です。送る場合は空の JSON オブジェクトでなければなりません。

## レスポンス

| フィールド | 型 | 説明 |
|---|---|---|
| `result` | string | `ok` または以下のエラーコード。 |
| `tested_at` | string | テストの実行時刻。 |
| `version` | integer | テストされた設定のバージョン。 |

```json
{
  "result": "smtp_auth_failed",
  "tested_at": "2026-10-19T09:30:00Z",
  "version": 4
}
```

主な結果:

| 結果 | 意味 |
|---|---|
| `ok` | 接続と認証が成功しました。 |
| `smtp_auth_failed` | SMTP サーバーがユーザー名またはパスワードを拒否しました。 |
| `smtp_auth_unsupported` | サーバーがサポートされている AUTH メカニズムを提供していません。 |
| `smtp_tls_required` | ポート 587 のサーバーが STARTTLS を提供していません。 |
| `smtp_tls_invalid` | サーバー証明書がホスト名に対して有効ではありません。 |
| `smtp_temporary`, `smtp_rejected` | サーバーが一時的または恒久的なエラーを返しました。 |
| `esp_auth_failed` | プロバイダーがキーを拒否しました。 |
| `esp_access_denied` | プロバイダーがキーを拒否したか、キーに確認対象のエンドポイントへの読み取り権限がありません (例: `ses:GetAccount`、または Mailgun のドメイン送信キー)。送信は引き続き機能する場合があります。 |
| `esp_rate_limited`, `esp_temporary`, `esp_rejected` | プロバイダーのレート制限に達したか、一時的に利用できないか、リクエストを拒否しました。 |
| `egress_dns_failed`, `egress_dns_private`, `egress_ssrf_blocked`, `egress_connect_failed`, `egress_timeout`, `egress_tls_invalid` | ホストが名前解決できないか、プライベートアドレスに解決されるか、ブロックされているか、時間内に到達できなかったか、(API プロバイダーの場合) 無効な証明書を提示しました。 |
| `delivery_credentials_invalid` | 保存された認証情報を使用できません。再度保存してください。 |
| `delivery_mode_unavailable` | このデプロイメントでは送信配信が有効になっていません。 |

## エラー

| HTTP | code | 発生するとき |
|---|---|---|
| 400 | `unknown_field` | ボディが空の JSON オブジェクトではありません。 |
| 409 | `conflict` | モードにテスト対象の接続がないか (`platform_default`、`customer_webhook`、`platform_managed_domain`。Webhook エンドポイントのテストは [Webhook エンドポイントをテストする](../webhook-endpoints/test.md) を、送信元ドメインの確認は [verify](../email-sender-domains/verify.md) を参照してください)、テスト中に設定が変更されました。 |
| 429 | `rate_limited` | 1 時間あたりのテスト上限または API のレート制限に達しました。`Retry-After` の期間を過ぎてから再試行してください。 |
| 401 | `unauthenticated` | 認証情報が見つからない、無効である、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の期間を過ぎてから再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/email-provider:test \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

CLI: `keenauth email-provider test`