How to customize email templates


(Simon Cossar) #1

Most of the email templates that Discourse uses to send notifications can be customized. The templates can be edited in two places, either through Admin/Customize/Text Content, or Admin/Customize/Email Templates. The end result of customizing email templates through either the Text Content section or the Email Templates section is the same. Editing templates through the Email Template section is more straightforward. This tutorial will deal with that approach.

Knowing which template to edit

If you go to Admin/Customize/Email Templates, you will see a list of template names. It can be hard to know which one to edit. Here is a list of the most commonly edited email templates, organized by what the template is used for.

Invites

  • Invite Forum Mailer: used for invites that are sent by clicking on the Send Invites link from the Admin/Users page. This template is used both for individual invites that do not include a custom message, and for bulk invites that do not include a topic_id.

  • Invite Mailer: used for invites to new users that are sent by clicking on the Invite button at the bottom of a topic, and for bulk invites that include a topic_id. When the invite is sent by clicking on the topic’s invite link, this template is only used when the invite does not include a custom message.

  • Custom Invite Forum Mailer: used for individual invites that are sent by clicking on the Send Invites link from the Admin/Users page. This template is only used when a custom message is included with the invite.

  • Custom Invite Mailer: used for invites to new users that are sent by clicking on the Invite button at the bottom of a topic. This template is only used when a custom message is included in the invite.

  • User Invited to Topic: sent when an existing user is invited to a topic.

  • Invite Password Instructions: sent after an invite has been redeemed when the invited user did not supply a password when they first logged into Discourse.

  • Signup: sent after an invite has been redeemed by a user who did supply a password when they redeemed the invite (this same template is used in the regular signup process.)

The ‘Custom Invite’ templates are used when a custom message is included with the invite.

Signup

  • Signup: sent after a user registers on the forum, or logs into Discourse through SSO with an unverified email, or accepts an invite and supplies a password when redeeming the invite.

  • Signup After Approval: sent to the user after their account has been approved on sites that have ‘must approve users’ enabled.

Editing the templates

The email templates are made up of text and tags. Tags look like this: %{tag_key}. When the email is sent, the tag’s key will be substituted with a value by Discourse. For example, the tag %{site_title} will be substituted for your site’s title, %{site_description} will be substituted with your site’s description.

Note: some tags and text in the email templates are very important. In the Invite templates the %{invite_link} tag must be present for the invite to work. In the Invite Password Instructions template, the link that is formed with %{base_url}/u/password-reset/%{email_token} must be present.

To edit an email template, go to Admin/Customize/Email Templates and click on the name of the template you wish to edit. This will open an editor where you can make changes to the Subject and Body of the template. If you wish, you can format the email with markdown or HTML. You can generally get by with just creating paragraphs by including a blank line where you want a paragraph to end. The results of your changes will be displayed next to the editor.

Finding and fixing mistakes

You can revert any changes that you have made by clicking the Revert Changes button at the bottom of the editor. To find which templates on your site have been edited, click through the list of email templates. Any template that has been edited will have a Revert Changes button at the bottom of the editor.


How do I set-up this workflow? Membership form with Payment > Discourse Invite