Skip to content

Email templates

Quite often, Fief needs to send emails to your users. More precisely, it will send the following emails:

  • The Welcome email, after a successful user registration;
  • The Forgot password email, when a user asks to reset its password.

By default, your workspace is created with basic templates. While they can do the job for getting started, you'll likely want to customize them so it matches your branding.

Fief comes with a built-in mechanism to customize email templates, based on Jinja templating language.

Base template

Fief defines a Base template from which every emails will inherit from. It's useful to define common CSS and blocks that will be reused in every emails.

The default template is based on the Mailmason template from Postmark. It comes with a set of CSS rules that plays well with email clients. You can use it as a base or start from scratch, it's up-to-you! The default template comes with the following blocks:

eyJ2ZXJzaW9uIjoiMSIsImVuY29kaW5nIjoiYnN0cmluZyIsImNvbXByZXNzZWQiOnRydWUsImVuY29kZWQiOiJ4nM1YWVPjOFx1MDAxMH7nV6Qyr+Cxbok3mOHcXHUwMDE5akLY5dja2lx1MDAxMrZcdTAwMTKb+MJWXHUwMDBlhuK/r+xkY+ckQID4IVx1MDAxNbfU7lb7+/S19bhVq9X1Q6Lqu7W6XHUwMDFhODLw3VT269u5vafSzI8jM1x1MDAwNIv7LO6mTjHT0zrJdr9+LT0sJ1x1MDAwZYdeKlChinRm5v1t7mu1x+K3XHUwMDEyJ1WOllE7UIVDMVSGXCI2mraexVFcdTAwMTFcdTAwMTZcdTAwMDFqU1x1MDAwZTFcdTAwMWNP8LPvJpxWrlx1MDAxOW3JIFPlSG6qXHUwMDA33zrMt6/ah/3gsiPd6Fxm3cFK1JZcdTAwMWZcdTAwMDRN/Vx1MDAxMFxm1yRcdTAwMWSvm1ZGM53GXHUwMDFkdem72jPjYMo+9stiU4HSK427bS9SWTbhXHUwMDEzJ9Lx9UNus+2xdViE3VppXHUwMDE5mDtKqcVtTDkjdn6Vyy38ObFMXHUwMDFkXHUwMDAwoZBMpfQtXHUwMDBl4jRP6UvhZ5dJ3Uqn0zaZRe54jk5llCUyNa+qnNdcdTAwMWYtXHUwMDE2I2pcdTAwMDFBXHUwMDEwgFjkXHUwMDE3peMpnvLbns7nXHUwMDEwbjFcdTAwMGXgMElzlXMyVbxcdTAwMTEhbFxiXHRcdTAwMDfl8vJcdTAwMWOSXHUwMDEzt8DGP9NcdTAwMDX1ZJqMXG5Xz/KbSv556lx1MDAwN1x1MDAxNWCVzt3ElUNcdTAwMDBcdTAwMDBKXHUwMDE5R1RcdTAwMDCEYFx1MDAxOTLwo45cdTAwMTmMukFQ2mKnU2KmsD5tv1x1MDAwMqucsUVYXHUwMDA1jDFcZoSAq4P1tvWre1x0fILgyc1R5t6QNDxBa1x1MDAwNqtcdTAwMWLrPIF1olVcdTAwMDDLpjb5XHUwMDFmr2BcdTAwMDKt0Fx1MDAwNlx1MDAxNseC2lx1MDAwMrHFcMWC2IS9XHUwMDFlrogzi3JEJoKMgYrINDCBYIzaXGJcdTAwMDI+XHUwMDE3mSNbvsC7ZpdcdTAwMWVfXHUwMDBmOsfnR9eNM+Jk7Taqj8bfXHUwMDA04HGMx/G/XG7qtFx1MDAxYZTLrECkvdf4KbNcdTAwMWR5r1x1MDAxZtJBPzmFR6eyVVx1MDAxZs97mslsXHUwMDBlO1x1MDAwNCdrY8dEnlx1MDAxNWIwgVx1MDAxN1x1MDAxMYNgXHUwMDFiXG5cdTAwMDbwyrSYv+Y100Jm3nppYUptme1cdTAwMGZhNNzFp2lBP4BcdTAwMTZizq5ccmfIgG0sXHUwMDE45vTTqLBcZq3Q/LxcdTAwMDStJSziSDf936oo9oT1UIZ+8DDxYlx1MDAwYlx1MDAxOJtMk1R5SroqrdY8UyZssaXzXHSHvcBv51ivO2YhVVx1MDAxN1x1MDAwM3jtm75oPCH0XbcqII7JQppnpier7Ptx6rf9SFx1MDAwNlx1MDAxNzNJvoqatIKKXHUwMDE5zVx1MDAwMtjsi1x1MDAwNNKVyfln9O/FtXCyu+B251x1MDAwNlxyXHUwMDBl8EHPXHUwMDBiN5+ckFhcdTAwMTXJmuqwIMFcdTAwMTY1baiw37PFXHUwMDAyQKzCTopcYlx1MDAwM1xmVfbTTaLnS1utt9FTq0hG2opkqF5E0EC19KvpObGaaS5WM3p9XHUwMDFiibFYRElcIkyfXHUwMDBmbbS6XFwm3lVcdTAwMTedO/tO2GiQS929+L3Tut94RlJhL5NLwSxMgNmf+Fx1MDAxMrl8KyNcdTAwMTHnc1x1MDAxOFlp8cfdo0lcdTAwMTRcYrTgu+bzuschXHUwMDAwul5GemnvkDGeuYK0g1x1MDAxZN04nWwmJzSi7Fx1MDAxZbfnP/a5pnR+wJc1pev8ZFukfIjCRTQzqlx1MDAwNyBiwl6ZZsurvKk041x1MDAxNC2hXHUwMDE5huhcdTAwMDNoVjm+WdaVXHUwMDFhdYaYoM/j2OboXmjU6EM70mc0ZFpcdTAwMDWL/N4gf3AhL6H5WGVV3j6rfkFcdTAwMTP8sffjOFZhM1xm//pxcHl/TjaelsvPUIiAXHUwMDE2JMPjuPdUv5edoWDBKSfVk8FNXHUwMDEyQXDXbWTXNydH+8jvu79cdTAwMGWvZPw9eE9cdTAwMTGcXHUwMDFmcFx1MDAwM0Vwca9cdKiBXHUwMDE4XHUwMDE2YvVec3mVN5VtnEBcdTAwMGIvXHUwMDE0QWJ6zfdnXHUwMDFincOxWVx1MDAxMVx1MDAxNDDfXHUwMDE0XHUwMDEw2cSPP9MkXHUwMDEwVDkpeG9cdTAwMTFsxbH+4IOZZ8RkWlx1MDAwNkdcdTAwMTlcdTAwMGVpuTUqfF0mSVObyplcdTAwMTlDktZ7vurvz+LlS6u4cv+C1Dl9VP5cdTAwMTJcdTAwMWWftp7+XHUwMDAzwqT10SJ9 preheadertenant.namemainfooter
  • preheader: this block allows you to add content that won't be shown in the email body. It's used to finely control the email preview in the inbox list.
  • main: this block will bear the actual content of the email.
  • footer: this block will appear at the end of the email and can be used to put legal terms or social networks links.

Before the main block, notice that we show the name of the tenant.

Customize

You can customize the Base template from admin dashboard. On the left menu, click on Customization and Email templates. You'll see the list of all available templates.

Email templates from admin dashboard

Click on the Update button in the front of the Base template row. An editor will open, with the HTML code on the left and a preview on the right.

Update email templates from admin dashboard

Context

The context defines the available variables you can use in the template. The Base template gives you access to the following context:

The tenant of the user, tenant, with the following properties

  • id (uuid.UUID): ID of the tenant.
  • created_at (datetime): Creation date of the tenant.
  • updated_at (datetime): Last update date of the tenant.
  • name (str): Name of the tenant.
  • default (bool): Whether it is the default tenant.
  • slug (str): Slug of the tenant, i.e. the part of the base URL after the domain.
  • registration_allowed (str): Whether registration are allowed or not for this tenant.

The recipient user, user, with the following properties:

  • id (uuid.UUID): ID of the user.
  • created_at (datetime): Creation date of the user.
  • updated_at (datetime): Last update date of the user.
  • email (str): Email address of the user.
  • tenant_id (uuid.UUID): ID of the associated tenant.
  • fields (dict[str, Any]): Dictionary giving you the user fields values for this user, indexed by their slug.

Examples

<h1>{{ tenant.name }}</h1>
<p>Hello, {{ user.fields.first_name }} 👋</p>

Welcome template

The Welcome template is used to send an email when a new user registers. It's the ideal message to welcome them, show them the basics of your application or give them relevant information.

The default template looks like this:

{% extends "BASE" %}

{% block preheader %}Welcome to {{ tenant.name }}! We're thrilled to have you on board.{% endblock %}

{% block main %}
<h1>Welcome!</h1>
<p>Welcome to {{ tenant.name }}! We're thrilled to have you on board.</p>
{% endblock %}

You can see it's very lightweight: all we need to do is to define the content of each block. The magic happens thanks to the {% extends "BASE" %} instruction which tells Fief to inherit from the Base template.

Subject

Using the text input above the code editor, you can customize the subject of the email. It accepts the same syntax and has the same context.

Context

The context is the same as for Base template.

Forgot password template

The Forgot password template is used to send an email when a user wants to reset their password. The main purpose is to send them the link allowing them to change their password.

The default template looks like this:

{% extends "BASE" %}

{% block preheader %}Use this link to reset your password. This link is only valid for 1 hour.{% endblock %}

{% block main %}
  <h1>Reset your password</h1>
  <p>You recently requested to reset your password for your {{ tenant.name }} account. Use the button below to reset it. <strong>This password reset link is only valid for the next hour.</strong></p>
  <table class="body-action" align="center" width="100%" cellpadding="0" cellspacing="0" role="presentation">
    <tr>
      <td align="center">
        <!-- Border based button
  https://litmus.com/blog/a-guide-to-bulletproof-buttons-in-email-design -->
        <table width="100%" border="0" cellspacing="0" cellpadding="0" role="presentation">
          <tr>
            <td align="center">
              <a href="{{reset_url}}" class="f-fallback button button--green" target="_blank" rel="noopener noreferrer">Reset your password</a>
            </td>
          </tr>
        </table>
      </td>
    </tr>
  </table>
{% endblock %}

You can see it's very lightweight: all we need to do is to define the content of each block. The magic happens thanks to the {% extends "BASE" %} instruction which tells Fief to inherit from the Base template.

Subject

Using the text input above the code editor, you can customize the subject of the email. It accepts the same syntax and has the same context.

Context

The context is the same as for Base template. It also adds:

  • reset_url (str): The URL where the user can reset their password.

Templating language

The template language is based Jinja templating language, so all constructs accepted by Jinja are supported. In particular, you can insert dynamic values using the {{ }} syntax:

<p>{{ user.email }}</p>

You can also define conditional blocks based on some values:

{% if user.fields.newsletter %}
    <p>Thank you for subscribing to our newsletter 🎉</p>
{% else %}
    <p>You didn't subscribe to our newsletter 🥲</p>
{% endif %}