---
title: "Create or update email branding"
method: PUT
path: "/clusters/{cluster_id}/realms/{realm}/branding/email"
tags: ["Email Branding"]
---

# Create or update email branding

`PUT /clusters/{cluster_id}/realms/{realm}/branding/email`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/clusters/{cluster_id}/realms/{realm}/branding/email`
- Auth: API key in header `API-Key`

Creates or replaces the email template branding for a realm. Triggers asynchronous theme generation and deployment.

Required scope: `branding:write`

## Path parameters

- `cluster_id` string, uuid, required
- `realm` string, required: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

## Headers

- `API-Version` '2026-06-01.beta', required

## Request body

- UpsertEmailBrandingRequest
  - `primary_color` string: CSS hex color code.
  - `header_logo_light_url` string, uri
  - `header_logo_dark_url` string, uri
  - `company_url` string, uri
  - `footer_company_name` string
  - `footer_text` string
  - `show_powered_by` boolean: Display a 'Powered by Skycloak' line in the email footer. Hiding it requires a plan that allows removing branding; otherwise it stays on. Omitted means unchanged.
  - `internationalization` InternationalizationConfig: Internationalization settings.
    - `enabled` boolean, required
    - `default_locale` string, required: IETF BCP 47 language tag used as the default locale.
    - `supported_locales` string[], required: Locales available to users. Must include `default_locale`.

## Response `200`

The request has succeeded.

- EmailBranding: Email template branding configuration for a Keycloak realm.
  - `cluster_id` string, uuid, required
  - `realm` string, required: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.
  - `primary_color` string: CSS hex color code.
  - `header_logo_light_url` string, uri: Logo URL for light-background email clients.
  - `header_logo_dark_url` string, uri: Logo URL for dark-background email clients.
  - `company_url` string, uri: URL of the company website linked from the email footer.
  - `footer_company_name` string
  - `footer_text` string
  - `show_powered_by` boolean: Display a 'Powered by Skycloak' line in the email footer.
  - `internationalization` InternationalizationConfig: Internationalization settings.
    - `enabled` boolean, required
    - `default_locale` string, required: IETF BCP 47 language tag used as the default locale.
    - `supported_locales` string[], required: Locales available to users. Must include `default_locale`.
  - `status` 'applying' | 'applied' | 'failed', required
  - `applied_at` string, date-time: Timestamp of the most recent successful deployment to Keycloak.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)