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 on the user’s Invites tab. 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 user’s Invites tab. 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
What is the difference between custom invite mailer, invite forum mailer and custom invite forum mailer?
(hosna) #2

Is RTL direction still not supported in the templates?


(Simon Cossar) #3

I just tested this. It is possible to wrap text in an email template in <div dir="rtl"></div> tags. The dir attribute is not stripped and the text inside of the <div> tags is displayed correctly in the email. Attempting to add a dir attribute to <p> tags fails.

If your users have selected a RTL locale, emails from Discourse should already have the correct direction. Let us know if this is not the case.


(hosna) #4

I didn’t test all templates. But for example, password reset emails are LTR.


(Carson) #5

Hi,

Could these two use cases be separated:

  • Invite Forum Mailer: used for invites that are sent by clicking on the Send Invites link on the user’s Invites tab. 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.

When I’m changing this template to do bulk invitations to specific groups, I’m taking the risk of my users inviting a friend to the forum at the same time using a VERY weird invitation message.


(Jeff Atwood) #6

(Carson) #7

I can’t help but live on the edge after that! So… seriously, it would be better if the admin interface for bulk invites and the user invite were different. It is inconvenient to change it back and forth. In my context, I do bulk invites on a regular basis, so it is a regular pain point to update the invite mailer format.