Email & Templates

FerrisKey sends transactional email for password resets, magic link sign-in, and email verification. Delivery is configured per realm, and each email type can be pointed at a template of your own.

Configure SMTP

SMTP settings live in the database, on the realm, not in a global environment variable. Two realms in the same deployment can use completely different mail providers.

SMTP fields

Encryption modes:

SMTP API endpoints

All endpoints are scoped to a realm and require authentication.

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

Configure SMTP in the console

Transactional emails

There are three types of transactional email, each gated by a realm toggle.

Turning a toggle on in Realm Settings activates the matching flow. Until you assign a template of your own, FerrisKey uses the built-in default.

Customizing templates

Template engine

Templates are rendered by a small interpolation engine written for the purpose, not Handlebars or Tera. Placeholders use double braces:

{{variable_name}}

Every interpolated value is HTML-escaped before insertion (&, <, >, ", '), so a template cannot be turned into an injection vector.

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. Point the realm at it by updating 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" }
  ]
}