Docs

You are viewing an archived version of the docs.Go to latest version

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:

NameDescription
template nameUser-friendly name of the template. This will be visible on the template listing page.
variablesAlso known as merge tags in the context of email marketing, these are placeholders that are replaced with dynamic data when the actual email or SMS is being sent to the recipient.
WYSIWYGStands for 'What You See Is What You Get.' This term is used for editors and design tools that allow you to create content or layouts in a visual manner (without requiring you to edit the underlying markup) so that you can instantly see how the result is going to display to your users.
blocksEmail WYSIWYG editors enable you to use blocks, rows, and columns in order to control the layout of their content. This is then transpiled to table-based HTML.

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, please consult the corresponding documentation page.

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. It is a well established language, especially popular in the Javascript ecosystem, which has been adopted by leading Email Service Providers (ESPs) for templating as well.

The most core Handlebars concept you should bear in mind is that 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.

For further information on Handlebars, we recommend you take a look at the official guides.

Note

In order to unescape special characters, you may need to wrap variables in triple curly braces. For example: {{{app.name}}}. This will allow special characters (e.g. ', &) to appear as displayed and not as escaped HTML entities (e.g. ', &).

Template operations

Please consult the following sub-sections to see which operations are available in the template editor.

Note

Depending on the state of the template and the current application subscription plan, one or more operations may not not available.

Edit

Editing templates allows you to customize existing Clerk-sent emails and SMS messages to make them more inline with your own branding.

Templates are editable:

  • On the development instance of applications on any subscription plan (free or paid)
  • On the staging and production instances of paid plans

This allows you freely test the templating feature on your development environment to see if it fits your individual use case before deciding on a plan upgrade.

To learn more about editing email templates, refer to the Edit email templates section.

To learn more about editing SMS templates, refer to the Edit SMS templates section.

Preview

The Preview operation 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.

To trigger a preview of a template, select the Preview button at the bottom left of the dashboard.

In email templates, the app_logo and copyright sections (if present) will be replaced with their actual markup in this view. For both emails & SMS, the template variables will be replaced with sample values.

Previewing is available for all templates.

Reset

While editing a template, you can undo all changes since the last save by selecting the Reset button at the bottom right of the dashboard.

Template reset is applicable to editable templates.

Revert

If you override a Clerk-provided template with your own customizations, you can always roll back to the system default template version by selecting the Revert button at the bottom left of the dashboard.

This can be useful if you want to start over from scratch.

Note

Your current changes will be lost, so make sure you mean to discard them prior to reverting. You will be asked to confirm your choice to prevent an unintentional action.

Copy to another instance of the same application

If your application has more than one instance, you can copy 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.

To copy to another instance, you will need to first select the Copy button in the bottom left of the dashboard. Then, from the sub-menu, select the target instance.

Warning

The copy icon will not appear if there are no other instances available on your application.

Since this change will override the current state of the template on the target instance, you will be asked to confirm your choice.

Edit email templates

To access the email templates:

  1. Navigate to the Clerk Dashboard.
  2. In the navigation sidebar, select Customization > Emails.
  3. Select a template to edit. The following templates are available for customization:
  4. Once you have selected a template, you will be presented with the template settings & the WYSIWYG editor.

Email template settings

The following settings can be changed for an email template:

Delivered by Clerk

Out of the box, 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 Delivered by Clerk 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.

Note

Remember, this is a per-template setting and will not be applied to other templates.

Name

Name is the template name and represents a human-friendly name for identifying the template on the template listing page. It does not affect the outgoing email in any way.

Send from

Clerk will populate the From email address with:

<local part>@<your-domain>

The local part depends on the type of email sent ('verification code', 'invitation', etc).

If you wish to override the local part with your own value, such as 'accounting', 'sales', etc., then set that value in the provided input.

Email WYSIWYG editor

The email WYSIWYG editor is split into two parts:

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 element 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. Navigate to the Clerk Dashboard.
  2. In the navigation sidebar, select Customization > SMS.
  3. Select a template to edit. The following templates are available for customization:
    • Invitation - SMS sent to invite a user to join your application
    • Password changed - SMS notifying the user that their password has been changed
    • Password removed - SMS notifying the user that their password has been removed
    • Reset password - SMS containing an OTP (One Time Password) code that allows the user to reset their password
    • Verification code - SMS containing an OTP (One Time Password) code for verifying account access
  4. Once you have selected a template, you will be presented with the template settings & the text area.

SMS template settings

The following settings can be changed for an SMS template:

Delivered by Clerk

Out of the box, Clerk will deliver your SMS messagess using its own SMS Gateway. However, if you wish to handle SMS delivery on your own, then you can toggle Delivery 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.

Note

Remember, this is a per-template setting and will not be applied to other templates.

Name

Name is the template name and represents a human-friendly name for identifying the template on the template listing page. It does not affect the outgoing SMS message in any way.

SMS text area

The text area is where you can author the content of the SMS message.

Insert variables

To insert a variable at the current cursor position, select the corresponding variable badge adjacent to the text area.

Note

The Invitation template supports public invitation metadata, whereas the Verification code template supports public user metadata (in the case that a user already exists).

You can interpolate a particular metadata key as follows:

{{invitation.public_metadata.foo.bar}}

Feedback

What did you think of this content?

Last updated on