[![License][badge-license]][license] [![Version][badge-version]][package] [![Downloads][badge-downloads]][package]

keycloakify-emails

> The extension for keycloakify to build your email theme using JS.

Description

This extension allows you to build email themes using modern JavaScript tooling.

$3

- Support theme variants. You can produce different templates using the same sourcecode.
- Support i18n. You can use i18n solution of your choice. The extension simply pass a locale to your template function.
- Support override for messages.properties using javascript and i18n solution of your choice.
- Provide type-safe helpers for available template variables, as well helpers to create Freemarker expressions.
- Produce both plain text and html version of email

Framework-agnostic, the extension works with any JS email library. jsx-email is recommended, with dedicated bindings and helpers provided.

$3

This library generates Freemarker templates using JavaScript, leaving expression placeholders in place.
The JavaScript code is executed ahead of time during static generation, not by Keycloak.
Therefore, JavaScript functions do not have access to Keycloak variables like userName or realmName during rendering.

Keycloak replaces the Freemarker expressions with their actual values during email rendering

The library includes a set of React components and utilities designed to simplify the process of writing these expressions.

Installation

Requires keycloakify v11.8.1 or higher.

``bash
npm install --save-dev keycloakify-emails


yarn add --dev keycloakify-emails


`

Usage

$3

Add the extension to your vite.config.ts:

`ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { keycloakify } from "keycloakify/vite-plugin";
import themes from "./themes";
import { buildEmailTheme } from "keycloakify-emails";
import path from "node:path";

export default defineConfig({
plugins: [
react(),
keycloakify({
themeName: ["vanilla", "chocolate"],
// See: https://docs.keycloakify.dev/features/environment-variables
environmentVariables: [
{ name: "MY_ENV", default: "Default Value of MY_ENV" },
],
accountThemeImplementation: "none",
postBuild: async (buildContext) => {
await buildEmailTheme({
templatesSrcDirPath: path.join(
buildContext.themeSrcDirPath,
"email",
"templates",
),
i18nSourceFile: path.join(
buildContext.themeSrcDirPath,
"email",
"i18n.ts",
),
themeNames: buildContext.themeNames,
keycloakifyBuildDirPath: buildContext.keycloakifyBuildDirPath,
locales: ["en", "pl"],
cwd: import.meta.dirname,
environmentVariables: buildContext.environmentVariables,
esbuild: {}, // optional esbuild options
});
},
}),
],
});
`

$3

To create a custom template, place the template files in the directory specified by templatesSrcDirPath (usually src/email/templates).
Any templates you do not define will fall back to the default Keycloak theme.

Example Template:

`tsx
// emails/templates/email-test.tsx
import { GetSubject, GetTemplate } from "keycloakify-emails";

export const getTemplate: GetTemplate = async (props) => {
return "

This is a test message

";
};

export const getSubject: GetSubject = async (props) => {
return "[KEYCLOAK] - SMTP test message";
};
`

For more details on the parameters and return types, refer to the GetTemplate and GetSubject type definitions.

#### Producing Plain Text and HTML version of template

Keycloak sends multipart emails containing both HTML and plain text versions to ensure compatibility with a wide range of email clients. Your theme must provide both versions for every template.

To do so keycloakify-emails will call getTemplate function 2 times, with {plainText: true} and {plainText: false}. You need to return corresponding version accordingly.

When using the jsx-email integration, the plain text version is automatically derived from the JSX component used for the HTML version. This eliminates the need to maintain two separate versions manually. However, ensure that the plain text version is tested and finalized before release.

Check full example in the ./example folder in this repo.

$3

You can skip this step if you are satisfied with the default translations for requiredAction or linkExpirationFormatter.

However, if you want to customize these messages or implement additional integrations based on a message bundle (messages_x.properties, you can define your own translations by creating an /emails/i18n.ts file with the following content:

`ts
import { GetMessages } from "keycloakify-emails";

export const getMessages: GetMessages = (props) => {
// All properties are optional. If you omit them, they will fall back to the base theme defaults.
if (props.locale === "en") {
return {
"requiredAction.CONFIGURE_TOTP": "Configure OTP",
"requiredAction.TERMS_AND_CONDITIONS": "Terms and Conditions",
"linkExpirationFormatter.timePeriodUnit.minutes":
"{0,choice,0#minutes|1#minute|1 };
} else {
return {};
}
};
`

Once you have defined your translations, include the file in the configuration:

`js
await buildEmailTheme({
// Other configurations
i18nSourceFile: import.meta.dirname + "/emails/i18n.ts",
});
`

$3

Below is a reference implementation showcasing all available messages that can be customized.

Click to expand

`ts
import { GetMessages } from "keycloakify-emails";

export const getMessages: GetMessages = (props) => {
// Default properties are optional. If omitted, they will fall back to the base theme defaults.
return {
"requiredAction.CONFIGURE_TOTP": "Configure OTP",
"requiredAction.TERMS_AND_CONDITIONS": "Terms and Conditions",
"requiredAction.UPDATE_PASSWORD": "Update Password",
"requiredAction.UPDATE_PROFILE": "Update Profile",
"requiredAction.VERIFY_EMAIL": "Verify Email",
"requiredAction.CONFIGURE_RECOVERY_AUTHN_CODES": "Generate Recovery Codes",

// Units for link expiration timeout formatting
// For languages with plural forms based on the value (e.g., Czech), use the Java choice format.
// Documentation:
// https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/MessageFormat.html
// https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/ChoiceFormat.html
"linkExpirationFormatter.timePeriodUnit.seconds":
"{0,choice,0#seconds|1#second|1 "linkExpirationFormatter.timePeriodUnit.minutes":
"{0,choice,0#minutes|1#minute|1 "linkExpirationFormatter.timePeriodUnit.hours":
"{0,choice,0#hours|1#hour|1 "linkExpirationFormatter.timePeriodUnit.days":
"{0,choice,0#days|1#day|1 };
};
`

The library will use this file to generate resource message bundle for specified locales.

Integrating with jsx-email

Follow their quick-start guide to set up jsx-email in your project.

Then you will be able to create templates using jsx-email components:

`tsx
import { GetSubject, GetTemplate, GetTemplateProps } from "keycloakify-emails";
import { createVariablesHelper } from "keycloakify-emails/variables";
import {
Text,
Body,
Container,
Section,
Preview,
Html,
Head,
render,
} from "jsx-email";

interface TemplateProps extends Omit {}

const main = {
backgroundColor: "#f6f9fc",
fontFamily:
'-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Ubuntu,sans-serif',
};

const container = {
backgroundColor: "#ffffff",
margin: "0 auto",
marginBottom: "64px",
padding: "20px 0 48px",
};

const box = {
padding: "0 48px",
};
const paragraph = {
color: "#777",
fontSize: "16px",
lineHeight: "24px",
textAlign: "left" as const,
};

// used by Preview App of jsx-email
export const previewProps: TemplateProps = {
locale: "en",
themeName: "vanilla",
};

export const templateName = "Email Verification";

const { exp } = createVariablesHelper("email-verification.ftl");

export const Template = ({ locale }: TemplateProps) => (


Verification link from {exp("realmName")}






Someone has created a {exp("realmName")} account with this email
address. If this was you, click the link below to verify your email
address


Link to e-mail address verification


This link will expire within{" "}
{exp("linkExpirationFormatter(linkExpiration)")}.


If you didn't create this account, just ignore this message.



);

export const getTemplate: GetTemplate = async (props) => {
return await render(