Email and SMS templates

Clerk provides a templating system that allows you to customize the default system email and SMS messages sent during authentication flows.

The template editor enables you to change the wording and styling so that it is more consistent with your own branding.

It is also a useful way to translate the content to another target language in the case that English is not the default locale of your application.

Before you start

Terminology

It will be useful to take a look at the following terms as they will reappear in the rest of the guide:

Revolvapp WYSIWYG email editor plugin

The email editor uses the Revolvapp⁠ email template editor plugin by Imperavi. To acquaint yourself with the template markup syntax, consult Imperavi's docs⁠.

As you will see, the template markup is an HTML-like language and each type of node supports its own set of attributes which control its behavior. A lot of the attributes are borrowed from HTML itself.

Revolvapp allows the user to design the template using blocks and under the hood transpiles its markup to table-based HTML so that the resulting email renders consistently across email clients.

Handlebars templating language

Both the email and SMS editor use the Handlebars⁠ templating language for the interpolation of dynamic values into your content via variables. Variables are wrapped in double curly braces. For example: {{app.name}}. When the message is to be sent, the variable will be replaced with the actual value, which in this example would be the name of the application.

When editing a template in the Clerk Dashboard, you can insert variables at the desired position, so there is no need to write them by hand. Though, you can still do so if you like.

Edit email templates

To access the email templates:

1. In the Clerk Dashboard, navigate to the Emails⁠ page.
2. Select a template to edit.
3. Once you have selected a template, you will be presented with template operations, the template settings, and the WYSIWYG editor.

Template operations

The following operations are available for an email template:

• Preview: enables you to get an idea of how the template will render when sent to the recipient. This is useful for sampling your changes without actually having to commit them first. The app_logo and copyright sections (if present) will be replaced with their actual markup in this view.
• Copy: copies the current state of the editor to another instance. This is especially useful for promoting changes from your development or staging environment to production after you have tested them. The copy icon will not appear if there are no other instances available on your application.
• Revert: reverts to the system default template version. This can be useful if you want to start over from scratch.
• Reset: undo all changes since the last save by selecting the Reset button at the bottom right of the dashboard.

Email template settings

The following settings can be changed per email template:

• Delivered by Clerk: Clerk will deliver your emails using its own Email Service Provider (ESP), which is currently SendGrid⁠. However, if you wish to handle delivery of emails on your own, then you can toggle this setting off. This means that Clerk will no longer be sending this particular email and in order to deliver it yourself, you will need to listen to the emails.created webhook and extract the necessary info from the event payload.
• Name: a name for the template on the template listing page. It does not affect the outgoing email in any way.
• From: the email address that will be used as the From address in the email header. The format is <local part>@<your-domain>. You can change the local part to a custom value. If no value is provided, it defaults noreply.
• Reply-To: the email address that will be used as the Reply-To address in the email header. This is useful if you want to direct replies to a different email address than the one used in the From field. The format is <local part>@<your-domain>. You can change the local part to a custom value. If no value is provided, the Reply-To header will be omitted.
• Subject: the subject line of the email.

Email WYSIWYG editor

The email WYSIWYG editor is split into two parts:

• The toolbar
• The text area

Toolbar controls

The toolbar is located at the top of the editor and contains the following controls, in order from left to right:

• Shortcut button
• Mobile view toggle
• HTML mode toggle - For this tool to appear, you will need to unselect any currently selected block.
• Background button
• Settings button

For the following controls to appear, you will need to select an existing block in the text area. These controls will not be visible otherwise.

• Add block button
• Alignment button
• Link button
• Text color button
• Variable button
• Border button

Text area controls

The email WYSIWYG editor text area is intended mainly for authoring content. Though, if you select a block, a set of tools will also appear. In order from top to bottom, these are:

• Move handle
• Delete
• Clone

Edit SMS templates

To access the SMS templates:

1. In the Clerk Dashboard, navigate to the SMS⁠ page.
2. Select a template to edit. You can also disable certain SMS notifications.
3. A modal will appear that shows you what the template looks like, plus options to toggle the Delivered by Clerk setting or to request a change to the template.

Delivered by Clerk

Clerk will deliver your SMS messages using its own SMS Gateway. However, if you wish to handle SMS delivery on your own, then you can toggle Delivered by Clerk off.

This means that Clerk will no longer be sending this particular SMS and in order to deliver it yourself, you will need to listen to the sms.created webhook and extract the necessary info from the event payload.

Request change

Modifications to an SMS template are subject to approval by Clerk support. Once you submit the desired copywriting for a particular SMS template, a draft will be created for Clerk support to review.

If the change conforms to Clerk content policy, a support agent will approve your draft, and it will become effective from that point on. If the change is rejected, then the draft will be canceled.

You can also cancel a draft yourself if you decide you no longer need the changes or if you wish to submit a new draft.

The following settings can be changed for an SMS template:

• Name: a name for the template on the template listing page. It does not affect the outgoing email in any way.
• Message: a text area where you can author the content of the SMS message. The SMS content should fit within a limit of 160 simple GSM-7 or 140 unicode characters. To insert a variable at the current cursor position, select the corresponding variable badge. You can interpolate a particular metadata key by using the following syntax: {{user.metadata.foo.bar}}.