How to customize specific email templates

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.

To start customizing an email template, go to the Admin / Customize / Email section of your site and click the dropdown menu:

What you will see is a list of email templates that correspond to 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:

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.

What each template gets used for

The trickiest part of editing the email templates is knowing which template to edit. Here’s the full list of templates and what each template gets used for:

  • 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.

  • 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.

  • Confirm New Email: Sent to a user with a link to confirm a request to change their email address.

  • 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.

  • 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.

  • 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.

  • 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 misformed. (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.

  • Forgot Password: Sent when a user requests a password reset.

  • 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.

  • 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.

  • 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.

  • Notify Old Email: Sent with a link to confirm the request to change their email.

  • Pending Users Reminder: Sent to staff when users are waiting for approval to join the community.

  • 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.

  • 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.

  • 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.

  • 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.

  • Test Mailer: Used for testing email delivery. Sent from the Admin / Emails / Settings page.

  • 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 their is automatically silenced due to community members flagging their posts.

  • 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 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 confirm joining a community site.

16 Likes