# 테스트 이메일 보내기

`POST /v1/email-templates/{family}/{locale}:test-send` · 권한 `email-templates:write` · Startup 요금제 이상

[미리 보기](preview.md)와 같은 샘플 데이터로 이메일 템플릿의 한 버전을 렌더링하고, 일반 전송 경로를 통해 한 주소로 보내 실제 받은편지함에서 확인할 수 있도록 합니다. 제목은 `[TEST] `로 시작합니다. 템플릿은 보내기 전에 다시 검증됩니다.

규칙:

- 수신자는 대시보드 계정의 `active` 구성원이 확인한 이메일 주소여야 합니다. 그 밖의 주소는 거부되며, 주소는 응답이나 로그에 다시 표시되지 않습니다.
- 각 환경은 UTC 기준 하루에 최대 20건의 테스트 이메일을 보낼 수 있습니다. 21번째 요청은 다음 UTC 날짜까지 `429`로 거부됩니다(`Retry-After`는 초 단위 대기 시간을 알려 줍니다).
- 수신 거부 목록은 계속 적용됩니다. 수신자가 수신 거부 상태이면 메시지는 `suppressed` 상태로 기록되고 전달되지 않지만, 여전히 일일 한도에 포함됩니다.
- 환경은 사용자 지정 템플릿을 보낼 수 있어야 합니다. 전송 모드가 `platform_default`이거나 발송이 제한 또는 일시 중지된 경우 테스트 발송이 거부됩니다.
- 허용된 테스트 발송은 관리 감사 로그에 `email_template.test_sent`로 기록되며, 계열, 로캘 및 버전이 포함되고 수신자는 포함되지 않습니다.

## 경로 매개변수

| 매개변수 | 설명 |
|---|---|
| `family` | 이메일 계열입니다(예: `verify_email` 또는 `email_otp`). [이메일 템플릿 목록](list.md)을 참고하십시오. |
| `locale` | 로캘 태그입니다(예: `en` 또는 `de`). |

## 헤더

| 헤더 | 설명 |
|---|---|
| `Idempotency-Key` | 선택 사항이며, `A-Z a-z 0-9 _ -` 문자 16~64자입니다. 같은 키로 요청을 반복하면 처음 메시지가 반환되며, 다시 보내거나 계산하지 않습니다. 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)에서 저장되는 항목, 보관 기간, 삭제 방법을 확인할 수 있습니다. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.