Customizing specific system email templates

[Discourse]

This is a guide about customizing specific system email templates in Discourse.

Required user level: Administrator

Discourse allows you to customize both the outer email template that is used as a wrapper around all HTML emails, and the individual email templates that are used to create the inner content of emails. This topic deals with customizing the inner templates. For details about customizing the outer email template, see Customize and style the Discourse outer email template.

Select an email template

To start customizing an email template, navigate to the “Email Settings” → “Preview Summary” page from the sidebar, and then click “Templates”.

You will see is a list of email templates that correspond to email actions on your site.

Clicking an entry from the dropdown will open an editor that lets you edit the email’s subject line and body:

Customize the subject

Available formatting options are:

%{optional_re}[%{site_name}] %{optional_pm}%{optional_cat}%{topic_title}

• %{optional_re} → Re: (applicable if the post is a Reply)
• %{site_name} → Community Title
• %{optional_pm} → [PM] (applicable if the post is a Personal Message)
• %{optional_cat} → [category] / [category/subcategory] {not applicable for uncategorized topics and PM)
• %{optional_tags} → [tag1] [tag2] [tag3] (shows up to 3 tags)
• %{topic_title} → Topic title

Complied subject for typical email notification:

[Community Title] [category] Topic title

Please note that a trailing whitespace will automatically be appended to %{optional_re}, %{optional_pm} and %{optional_cat}.

Customize the body

The templates are made up of markdown and placeholder. The placeholders are used by Discourse to substitute content into the email. For example, The body of the default Signup template is the following:

Welcome to %{site_name}!

Click the following link to confirm and activate your new account:
%{base_url}/u/activate-account/%{email_token}

If the above link is not clickable, try copying and pasting it into the address bar of your web browser.

Your site’s name (set by the title site setting) will be substituted for the%{site_name} placeholder. Your site’s URL and a special email token will be substituted for the %{base_url} and %{email_token} placeholders.

You should not remove placeholders from the email templates unless you are certain about how they are used. In the Signup template example, it would be possible to remove the %{site_name} placeholder, but the link that is created with the %{base_url} and %{email_token} placeholders is required for the Signup email to work.

After having edited a template, you can always revert to the default template by clicking the “Revert Changes” button.

Available email templates

The trickiest part of editing the email templates is knowing which template to edit. Here are select templates and what they get used for:

Account Related

• Account Created
  Sent to a user when an account is created on the user’s behalf with the rake admin:invite task so the user can set a password.
• Admin Login
  Sent when an admin requests a special login link via email from /u/admin-login.
• Confirm New Email
  Sent to a user with a link to confirm a request to change their email address.
• Forgot Password
  Sent when a user requests a password reset. A Forgot Password email is also sent when using the Password Reset API call.
• Log in via link
  Sent when a user requests a one-time email login link.
• New Login Alert
  Sent to a user when a user logs in from a new device or location.
• Notify Old Email
  Sent with a link to confirm the request to change their email.
• Set Password
  Sent in response to a request to add a password to a user’s account.
• Signup
  Sent to a user as a confirmation when a user signs up for a community site.
• Signup After Approval
  Sent to a user after an admin approves a request to join a community site.

Admin Notifications

• Backup Failed
  Sent to an admin when an attempt to create a backup file has failed.
• Backup Succeeded
  Sent to an admin when a backup file has been successfully created.
• Bulk Invite Failed
  Sent to an admin when there are any errors in processing a bulk invite file.
• Bulk Invite Succeeded
  Sent to a staff member when a bulk invite file has been successfully processed.
• CSV Export Failed
  Sent when a user’s requests to download their data fails.
• CSV Export Succeeded
  Sent when a user’s request to download their data succeeds. Includes a link to download the file.
• Download Remote Images Disabled
  Sent to admins when downloading remote images setting is disabled due to space threshold reached.
• Email Error Notification
  Sent to admins when the site’s POP mail server throws an error.
• New Version Mailer
  Sent to admins when a new version of Discourse is available.
• New Version Mailer with Notes
  Sent to admins when a new version of Discourse is available with notes.
• Pending Users Reminder
  Sent to staff when users are waiting for approval to join the community.
• Queued Post Reminder
  Sent to site moderators when posts by users are held in a moderation queue for longer than a designated time frame in Settings.
• Restore Failed
  Sent to admins when a restore fails.
• Restore Succeeded
  Sent to admins when a restore succeeds.
• Test Mailer
  Used for testing email delivery. Sent from the Admin / Emails / Settings page.

Email Errors

• Email Reject Auto Generated
  Sent when an account is registered with an auto-generated email.
• Email Reject Empty
  Sent when the body of the email is empty, or can’t be found due to formatting issues.
• Email Reject Invalid Access
  Sent when the sender doesn’t have permission to post in the category.
• Email Reject Parsing
  Sent when the reply cannot be found in the email – usually due to the reply not being at the top of the email.
• Email Reject Reply Key
  Sent when the email’s reply key is missing or malformed. (Reply keys are used to associate emails with Discourse topics.)
• Email Reject Screened Email
  Sent when the email is sent from a blocked email address.
• Email Reject Topic Closed
  Sent when an attempt is made to respond to a closed topic via email.
• Email Reject Topic Not Found
  Sent when an attempt is made to respond to a deleted topic via email.
• Email Reject Unrecognized Error
  A fallback notification – sent when there is an error processing an email, but the error is not caught by any of the specific email error handling methods.
• Email Reject User Not Found
  Sent when the sender doesn’t have an account on the site, and the ‘enable staged users’ site setting is disabled.
• Email Revoked
  Sent when emails from a user are bouncing or rejected.

Invitations

• Custom Invite Forum Mailer
  Sent for individual invites that are triggered by clicking on the “Send Invites” link from the user’s Invites tab. This template is only used when a custom message is added to the invite.
• Custom Invite Mailer
  Sent for invites to new users that are triggered by clicking on the “Share” button at the bottom of a topic. This template is only used when a custom message is added to the invite.
• Invite Forum Mailer
  Sent for individual invites that are triggered by clicking the Send Invites link from the user’s Invites tab and for bulk invites that do not include a topic ID. This template is only used when there is no custom message included with the invite.
• Invite Mailer
  Sent for invites to new users that are triggered by clicking on the “Share” button at the bottom of a topic, and for bulk invites that include a topic_id. This template is only used with there is no custom message added to the invite.
• Invite Password Instructions
  Sent after a user accepts an invitation to join a community if they do not set a password when accepting the invite.
• User Invited Group to PM
  Sent to members of a Group when a user invites a group to a message.
• User Invited to PM
  Send to a user when a user invites another user to a PM.
• User Invited to Topic
  Sent to a user when another member invites them to view a Topic.

User Notifications

• Post Hidden
  Sent to a user when their post is automatically hidden due to flags by community members.
• Post Hidden Again
  Sent to a user when their post is automatically hidden due to flags by community members.
• Silenced by Staff
  Sent to a user when their account is silenced by a staff member.
• Spam Post Blocked
  Sent to a user after posting multiple times with links to domains listed as spam domains.
• Too Many Spam Flags
  Sent to a user when their account is automatically silenced after multiple posts are flagged by community members.
• Unsilenced
  Sent to a user when their account is no longer silenced.
• User Automatically Silenced
  Sent to a user when they are automatically silenced due to community members flagging their posts.
• User Linked
  Sent to a user when another user links to one of their posts within another piece of content.
• User Mentioned
  Sent to a user when another user mentions them in a post.
• User Posted
  Sent to a user when someone replies to a topic they are watching.
• User Posted PM
  Sent to a user when someone replies to their PM.
• User Quoted
  Sent to a user when another user quotes them in a post.
• User Replied
  Sent to a user when another user replies to their post.
• Welcome Invite
  Sent to a user after they accept an invitation to a community site.
• Welcome User
  Sent to a user after they signup and login to the site. (This template is used for generating an on site notification that is seen by users when they first login to the site. The notification will only be created if the discourse narrative bot enabled site setting is enabled and the discourse narrative bot welcome post type setting is set to “Send all new users a welcome message starting with a quick start guide.”)

---

Last Reviewed by @SaraDev on 2022-06-10T21:00:00Z

Last edited by @hugh 2024-07-16T06:10:09Z

Last checked by @hugh 2024-07-16T06:10:18Z

Check document

Perform check on document:

[francis_exalate (Francis Martens (Exalate))]

I’m not sure what I’m doing wrong but I adapt the email template ‘Invite Forum Mailer’ by adding

Hi %{name}

But I’m getting an error

What can be the reason?

[Lilly]

@francis_exalate did you have a look at this topic yet?

Interpolation Keys for Customizing Text and System Email Templates

This guide provides a detailed overview of interpolation keys used for customizing text and system email templates in Discourse. Required user level: Administrator While Customizing text in Discourse or Customizing specific email templates you may have noticed that there are placeholder variables available in some templates. In Discourse we call these Interpolation Keys. Understanding interpolation keys Interpolation keys are placeholders available in cert…

[francis_exalate (Francis Martens (Exalate))]

Yes - there is a section that states that the interpolation key ‘name’ is a generic one available on all templates …

[Moin]

Which name do you expect the placeholder to be replaced with? When you invite a user, they don’t have an account with a username or name.

[francis_exalate (Francis Martens (Exalate))]

I thought that ‘you can use across all email templates’ included the ‘Invite Forum Mailer’ template, but I guess that is an exception.

We changed it to ‘Hi there’, so topic resolved.

Thanks