Email & Templates

FerrisKey sends transactional emails for password resets, magic link authentication, and email verification. Delivery is configured per realm through a dedicated SMTP setup, and each email type can be customized with your own HTML template.

Configure SMTP

SMTP is stored in the database at the realm level — not as a global environment variable. Each realm can use a different mail provider independently.

SMTP Fields

Encryption modes:

SMTP API Endpoints

All endpoints are scoped to a realm and require authentication.

Required permissions: reading SMTP config requires view access to the realm. Creating, updating, or deleting requires ManageRealm. There are no dedicated SMTP permissions beyond the realm permission gates.

Configure SMTP in the Console

Transactional Emails

FerrisKey sends exactly three types of transactional email. Each is tied to a realm feature toggle.

Enabling these toggles in Realm Settings activates the corresponding flow. FerrisKey will use the default built-in template unless you assign a custom one.

Customizing Templates

Template Engine

FerrisKey uses a lightweight custom interpolation engine — not Handlebars or Tera. Placeholders use double-brace syntax:

{{variable_name}}

All interpolated values are HTML-escaped before insertion (&, <, >, ", '), which prevents injection attacks in the rendered email.

Templates are stored as a JSON structure that FerrisKey renders to MJML and then to HTML before sending.

Available Variables

These variables are available in every template:

Each email type also provides one link variable:

You can query the available variables for any type without authentication:

GET /email-templates/variables/{email_type}

email_type must be one of: reset_password, magic_link, email_verification.

Example response for reset_password:

{
  "data": [
    { "name": "user.first_name", "description": "User's first name" },
    { "name": "user.last_name", "description": "User's last name" },
    { "name": "user.email", "description": "User's email address" },
    { "name": "expiration", "description": "Expiration time" },
    { "name": "reset_link", "description": "Password reset link" }
  ]
}

Template API Endpoints

Request body for POST: name, email_type, structure.

Request body for PUT: name, structure (email_type cannot be changed after creation).

Required permissions: ViewEmailTemplates to read. ManageEmailTemplates to create, update, or delete. ManageRealm also grants both.

Linking a Template to an Email Type

Creating a template does not activate it automatically. You must link it to the realm by updating the realm settings:

Set the field to the template UUID to activate it. Set it to null (or leave it unset) to fall back to the built-in default.

Example

Template snippet

A minimal password-reset template body using placeholder syntax:

<p>Hi {{user.first_name}},</p>

<p>
  Someone requested a password reset for your account (<strong>{{user.email}}</strong>).
  This link expires in {{expiration}}.
</p>

<p>
  <a href="{{reset_link}}">Reset your password</a>
</p>

<p>If you did not request this, you can safely ignore this email.</p>

Variables response

{
  "data": [
    { "name": "user.first_name", "description": "User's first name" },
    { "name": "user.last_name", "description": "User's last name" },
    { "name": "user.email", "description": "User's email address" },
    { "name": "expiration", "description": "Expiration time" },
    { "name": "magic_link", "description": "Magic link URL" }
  ]
}