# Preview an email template

`POST /v1/email-templates/{family}/{locale}:preview` · permission `email-templates:write` · Startup plan and above

Renders a saved version, or content you have not saved, with sample data, and returns the full message as recipients would see it: the platform layout, the required security block and the platform mark. Nothing is saved or sent. The sample code and link are random on every call. Validation is the same as for [saving a draft](put.md).

## Path parameters

| Parameter | Description |
|---|---|
| `family` | Email family, for example `verify_email` or `email_otp` (see [List email templates](list.md)). |
| `locale` | Locale tag, for example `en` or `de`. |

## Request

Send either `version` or the content fields, not both.

| Field | Type | Description |
|---|---|---|
| `version` | integer | A saved version to render (1 or more). |
| `subject`, `html`, `text_body`, `from_name` | string | Unsaved content, with the same rules as [save a draft](put.md). |

## Response

`200 OK`

```json
{
  "subject": "Confirm your email for Example App",
  "html": "<!doctype html><html lang=\"en\">…</html>",
  "text": "Confirm your email: https://login.example.com/preview/9f2c…",
  "locale": "en"
}
```

`locale` is the catalog locale used for the platform's own parts.

## Errors

| HTTP | code | When |
|---|---|---|
| 400 | `unknown_field` | The body has an unknown field or is not a JSON object. |
| 404 | `not_found` | The family or locale is unknown, or the version does not exist. |
| 403 | `plan_feature_unavailable` | The environment's plan does not include custom email templates (Startup and above; `required_plan` says which). |
| 413 | `payload_too_large` | The body is larger than 2 MiB. |
| 422 | `validation_failed` | Both `version` and content were sent (`conflicts_with_content`), or the content fails validation. |
| 422 | `template_forbidden_construct` | The template uses a Liquid construct outside the sandbox. |
| 401 | `unauthenticated` | The credential is missing, invalid or revoked. |
| 403 | `insufficient_permissions` | The credential lacks the required permission. |
| 429 | `rate_limited` | The rate limit was exceeded; retry after the `Retry-After` period. |
| 503 | `service_unavailable` | A dependency is temporarily unavailable; retry after the `Retry-After` period. |

## Example

```bash
curl -X POST https://api.eu.keenauth.com/v1/email-templates/verify_email/en:preview \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version":3}'
```

CLI: `keenauth email-templates preview verify_email en --version 3`