Nhost Auth sends out transactional emails as part of certain authentication workflows. These emails can be modified using email templates.

Changing email templates is only available starting on the Pro plan

Customize your emails

Email Templates are deployed as part of a Deployment so your project must be connected to a Git repository.

Learn how to connect a Git Repository to your project

File Structure

Email Templates can be found under your project’s ./nhost/emails folder and have the following structure:

Terminal
> tree ./nhost

nhost
├── config.yaml
├── emails
│   ├── en
│   │   ├── email-confirm-change
│   │   │   ├── body.html
│   │   │   └── subject.txt
│   │   ├── email-verify
│   │   │   ├── body.html
│   │   │   └── subject.txt
│   │   ├── password-reset
│   │   │   ├── body.html
│   │   │   └── subject.txt
│   │   ├── signin-passwordless
│   │   │   ├── body.html
│   │   │   └── subject.txt
│   │   └── signin-passwordless-sms
│   │       └── body.txt
│   └── fr
│       ├── email-confirm-change
│       │   ├── body.html
│       │   └── subject.txt
│       ├── email-verify
│       │   ├── body.html
│       │   └── subject.txt
│       ├── password-reset
│       │   ├── body.html
│       │   └── subject.txt
│       ├── signin-passwordless
│       │   ├── body.html
│       │   └── subject.txt
│       └── signin-passwordless-sms
│           └── body.txt
├── metadata
├── migrations
├── nhost.toml
└── seeds

As you can see templates can be defined for various languages and, with the exception of signin-passwordless-sms, they require 2 files for the subject and body.

/{two-letter-language-code}/{email-template}/[subject.txt, body.html]

Languages

A user’s language is stored in the auth.users table in the locale column. This locale column contains a two-letter language code (ISO 639-1) which is used to infer what language and template to use in the email.

The default value of the locale column is en

Template Variables

The following variables are available to all email templates:

VariableDescription
linkThe full URL to the target of the transaction. This should be used in the main call to action.
serverUrlURL of the authentication server
clientUrlURL of your client app
redirectToURL where the user will be redirected to after clicking the link and finishing the action of the email
ticketTicket that is used to authorize the link request
displayNameThe display name of the user
emailThe email of the user
localeLocale of the user as a two-letter language code (e.g. “en”)

Variables can be referenced by enclosing them with ${} as in the following example:

<h2>Verify You Email</h2>

<p>Hi, ${displayName}! Please click the link to verify your email:</p>

<p>
  <a href="${link}">Verify Email</a>
</p>

Postmark Integration

Alternatively, you can use postmark’s native integration and leverage postmark’s templates. To do so, you need to:

  1. Configure SMTP settings like below:
[provider.smtp]
host = 'postmark'
password = '{{ secrets.POSTMARK_API_KEY }}'
sender = 'myapp@mydomain.com'

It is very important that the host is set exactly to postmark.

  1. In postmark you need to create thre templates for each locale with the following alias:
  • $locale.email-change
  • $locale.email-verify
  • $locale.password-reset

For instance:

  • en.email-change
  • en.email-verify
  • en.password-reset
  • se.email-change
  • se.email-verify
  • se.password-reset

After these two steps have been completed, the Auth service will leverage these templates instead of the ones described in the previous section.

Postmark templates should have access to the same variables as described previously