테스트 이메일 보내기

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

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

규칙:

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

경로 매개변수

매개변수	설명
`family`	이메일 계열입니다(예: `verify_email` 또는 `email_otp`). 이메일 템플릿 목록을 참고하십시오.
`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

{
  "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` 기간 이후에 다시 시도하십시오.

예제

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의 개인정보에서 저장되는 항목, 보관 기간, 삭제 방법을 확인할 수 있습니다. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.