Customizing specific system email templates

Documentation Site Management
,
1

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

:person_raising_hand: 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”.

image
image2463×487 55.3 KB

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:

image
image1885×1378 116 KB

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 documentPerform check on document:
31 Likes