Customizing specific system email templates
This guide explains how to customize the individual email templates that Discourse uses for account notifications, invitations, admin alerts, and other system emails.
Required user level: Administrator
Discourse sends a variety of emails — account confirmations, password resets, notification digests, invitation messages, and more. Each of these is built from an individual email template that you can customize. This topic covers editing those inner content templates. For details about customizing the outer HTML wrapper that surrounds all emails, see Customizing the Discourse outer email template.
Selecting an email template
To start customizing an email template:
- Open the admin sidebar and expand the Email section.
- Click Email to open the email settings page.
- Click the Templates sub-page.
You can also navigate directly to https://discourse.example.com/admin/email/templates.
You’ll see a list of email templates that correspond to email actions on your site. Click an entry to open an editor where you can modify the email’s subject line and body:
Editing templates via site texts
Every email template can also be edited through Admin → Appearance → Site Texts (or directly at https://discourse.example.com/admin/customize/site_texts). This approach is useful when you want to search by the template’s internal key name or edit the subject and body independently.
To find a specific template, search for its key. For example:
user_notifications.user_watching_first_post.text_body_templateuser_notifications.user_watching_category_or_tag.subject_template
For more on editing site texts, see Customize text in Discourse.
Customizing the subject
The default email subject site setting format is:
[%{site_name}] %{optional_pm}%{optional_cat}%{topic_title}
The following placeholders are available for use in the subject format:
| Placeholder | Output | Notes |
|---|---|---|
%{optional_re} |
Re: | Included when the post is a reply |
%{site_name} |
Your community title | Uses the email prefix site setting, falling back to title
|
%{optional_pm} |
[PM] | Included when the post is a personal message |
%{optional_cat} |
[category] or [category/subcategory] | Not included for uncategorized topics or PMs |
%{optional_tags} |
tag1 tag2 tag3 | Requires enable max tags per email subject to be enabled; limited by max tags per email subject
|
%{topic_title} |
Topic title | The title of the relevant topic |
A compiled subject for a typical email notification looks like:
[Community Title] [category] Topic title
A trailing whitespace is automatically appended to %{optional_re}, %{optional_pm}, and %{optional_cat}.
To display the group name instead of [PM] in message subjects, enable the group in subject site setting.
Customizing the body
Email template bodies are made up of markdown and placeholders. Discourse substitutes dynamic content into placeholders when sending the email.
For example, the body of the default Signup template:
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.
In this template:
-
%{site_name}is replaced with your site’s name (set by thetitlesite setting). -
%{base_url}is replaced with your site’s URL. -
%{email_token}is replaced with a unique activation token.
You should not remove placeholders from templates unless you’re certain how they’re used. In the Signup template example, removing %{site_name} is safe, but removing the %{base_url} and %{email_token} placeholders would break the activation link.
Common body placeholders
Many notification templates share these placeholders:
| Placeholder | Description |
|---|---|
%{header_instructions} |
Instructional text at the top of the email. Empty by default but customizable via site texts at user_notifications.header_instructions. |
%{message} |
The main content of the post or notification. |
%{context} |
Previous replies or context for the conversation. |
%{respond_instructions} |
Instructions for how to reply (e.g., “Visit Topic or reply to this email”). |
%{email_preview} |
Preview text displayed by email clients in the inbox list. Hidden in the HTML body with display: none, though some email clients render it visibly. |
For a complete reference of which placeholders are available in each template, see Interpolation keys for customizing text and system email templates.
Reverting changes
After editing a template, you can always revert to the default by clicking the Revert Changes button in the template editor.
Verifying which template is used
If you’ve edited a template but the changes don’t appear in outgoing emails, you may have edited the wrong one. For example:
- User Posted — sent when someone replies to a topic the user is watching.
- User Watching First Post — sent when a new topic is created in a category or with a tag the user is watching for first posts.
- User Watching Category or Tag — sent when a new topic is created in a category or with a tag the user is watching.
To confirm which template triggered a particular email, navigate to Admin → Email → Logs → Sent (or go directly to https://discourse.example.com/admin/email/sent). The “Type” column shows the template key used for each sent email.
Available email templates
Below is a reference of all available email templates, organized by function.
Account related
| Template | Description |
|---|---|
| Account Created | Sent when an account is created on a user’s behalf (e.g., via rake admin:invite), allowing the user to set a password. |
| Account Deleted | Sent when a staff member deletes a user’s account. |
| Account Exists | Sent when someone attempts to create an account or change their email to an address that already has an account. |
| Account Second Factor Disabled | Sent when two-factor authentication (2FA) is disabled on a user’s account. |
| Activation Reminder | A reminder sent to users who haven’t yet activated their account. |
| Admin Confirmation | Sent to confirm the addition of a new administrator. |
| Admin Login | Sent when an admin requests a special login link via email from /u/admin-login. |
| Confirm New Email | Sent with a link to confirm a request to change an email address. |
| Confirm New Email via Admin | Sent when an admin initiates an email address change on behalf of a user. |
| Confirm Old Email | Sent to verify the current email address before an email change is applied. |
| Confirm Old Email (Add) | Sent to verify the current email address before an additional email is added. |
| Forgot Password | Sent when a user requests a password reset. Also sent when using the Password Reset API. |
| Log in via Link | Sent when a user requests a one-time email login link. |
| New Login Alert | Sent when a login is detected from a new device or location. |
| Notify Old Email | Sent to a user’s previous email address to notify them that their email has been changed. |
| Notify Old Email (Add) | Sent to notify that a new email address has been added to the account. |
| Post Approved | Sent when a user’s queued post is approved by a staff member. |
| Set Password | Sent in response to a request to add a password to an account. |
| Signup | Sent as a confirmation when a user signs up. |
| Signup After Approval | Sent after an admin approves a request to join the community. |
| Signup After Reject | Sent after an admin rejects a request to join the community. |
Account status
| Template | Description |
|---|---|
| Account Silenced | Sent when a user’s account is silenced until a specified date. |
| Account Silenced Forever | Sent when a user’s account is silenced indefinitely. |
| Account Suspended | Sent when a user’s account is suspended until a specified date. |
| Account Suspended Forever | Sent when a user’s account is suspended indefinitely. |
Admin notifications
| Template | Description |
|---|---|
| Backup Failed | Sent to admins when an attempt to create a backup fails. |
| Backup Succeeded | Sent to admins when a backup is successfully created. |
| Bulk Invite Failed | Sent to admins when there are errors processing a bulk invite file. |
| Bulk Invite Succeeded | Sent to staff when a bulk invite file is successfully processed. |
| CSV Export Failed | Sent when a data export request fails. |
| CSV Export Succeeded | Sent when a data export request succeeds. Includes a download link. |
| Download Backup Mailer | Sent with a link to download a completed backup file. |
| Download Remote Images Disabled | Sent to admins when the download remote images setting is disabled due to storage threshold. |
| Email Error Notification | Sent to admins when the site’s 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, including release notes. |
| Pending Users Reminder | Sent to staff when users are waiting for approval. |
| Queued Posts Reminder | Sent to moderators when posts are held in the review queue longer than the configured time. |
| Restore Failed | Sent to admins when a restore operation fails. |
| Restore Succeeded | Sent to admins when a restore operation succeeds. |
| Reviewables Reminder | Sent to staff as a reminder about pending reviewable items. |
| Test Mailer | Used for testing email delivery from the admin email settings page. |
Email errors
These templates are sent as responses when incoming email processing fails.
| Template | Description |
|---|---|
| Email Reject Attachment | The email contains an unsupported attachment. |
| Email Reject Auto Generated | An auto-generated email was received. |
| Email Reject Bad Destination Address | The destination address is invalid. |
| Email Reject Empty | The email body is empty or can’t be parsed. |
| Email Reject Inactive User | The sender’s account is inactive. |
| Email Reject Insufficient Trust Level | The sender’s trust level is too low. |
| Email Reject Invalid Access | The sender doesn’t have permission to post in the category. |
| Email Reject Invalid Post | The post content is invalid. |
| Email Reject Invalid Post Action | The requested post action is invalid. |
| Email Reject Invalid Post Specified | The specified post can’t be found. |
| Email Reject Not Allowed Email | The sender’s email address is not allowed. |
| Email Reject Old Destination | The email replies to an outdated address. |
| Email Reject Parsing | The reply can’t be found in the email — usually because it wasn’t at the top. |
| Email Reject Post Too Short | The reply content is too short to create a post. |
| Email Reject Reply Key | The email’s reply key is missing or malformed. |
| Email Reject Reply Not Allowed | The user is not allowed to reply. |
| Email Reject Reply to Digest | A user replied to a digest email. |
| Email Reject Reply User Not Matching | The sender doesn’t match the expected reply user. |
| Email Reject Screened Email | The email is from a blocked email address. |
| Email Reject Silenced User | The sender’s account is silenced. |
| Email Reject Strangers Not Allowed | An unknown sender emailed and staged users are not enabled. |
| Email Reject Too Many Recipients | The email has too many recipients. |
| Email Reject Topic Closed | A reply was attempted to a closed topic. |
| Email Reject Topic Not Found | A reply was attempted to a deleted or non-existent topic. |
| Email Reject Unrecognized Error | A fallback sent when the error isn’t caught by a specific handler. |
| Email Reject User Not Found | The sender has no account and enable staged users is disabled. |
| Email Revoked | Emails from a user are bouncing or rejected repeatedly. |
Invitations
| Template | Description |
|---|---|
| Custom Invite Forum Mailer | Sent for individual invites from the user’s Invites tab when a custom message is included. |
| Custom Invite Mailer | Sent for topic-specific invites (via the “Share” button) when a custom message is included. |
| Invite Forum Mailer | Sent for individual invites from the Invites tab and bulk invites without a topic ID, when no custom message is included. |
| Invite Mailer | Sent for topic-specific invites and bulk invites that include a topic ID, when no custom message is included. |
| Invite Password Instructions | Sent after a user accepts an invitation if they didn’t set a password during acceptance. |
User notifications
| Template | Description |
|---|---|
| User Group Mentioned | Sent when a group the user belongs to is @mentionedmentioned in a topic. |
| User Group Mentioned PM | Sent when a group the user belon@mentioneds to is @mentioned in a personal message. |
| User Group Mentioned PM (Group) | Sent to group members @mentionedhen the group is @mentioned in a group PM. |
| User Invited to PM | Sent when a user is invited to a personal message. |
| User Invited to PM (Group) | Sent to group members when a group is invited to a personal message. |
| User Invited to PM (Staged) | Sent to a staged user when invited to a personal message. |
| User Invited to Topic | Sent when another member invites a user to view a topic. |
| User Linked | Sent when another user links to one of the user’s posts. |
| User Mention@mentionsd | Sent when another user @mentions the user in a topic. |
| User Me@mentionstioned PM | Sent when another user @mentions the user in a personal message. |
| User Posted | Sent when someone replies to a topic the user is watching. |
| User Posted PM | Sent when someone replies to a personal message the user is in. |
| User Posted PM (Staged) | Sent to a staged user when someone replies to a PM they’re part of. |
| User Quoted | Sent when another user quotes the user in a post. |
| User Replied | Sent when another user replies directly to the user’s post in a topic. |
| User Replied PM | Sent when another user replies to the user’s post in a personal message. |
| User Watching Category or Tag | Sent when a new topic is created in a category or with a tag the user is watching. |
| User Watching First Post | Sent when a new topic is created in a category or with a tag where the user is watching first posts. |
System messages and moderation
| Template | Description |
|---|---|
| Flags Agreed and Post Deleted | Sent to the user whose post was deleted after flags were agreed with. |
| Flags Agreed and Post Deleted (for Responders) | Sent to users who flagged a post after their flags were agreed with and the post deleted. |
| Flags Disagreed | Sent to users who flagged a post when their flags are disagreed with. |
| Ignored Users Summary | A periodic summary sent to users about interactions from users they’ve ignored. |
| New User of the Month | Sent to the user selected as new user of the month. |
| Post Hidden | Sent when a user’s post is automatically hidden due to community flags. |
| Post Hidden Again | Sent when a user’s post is hidden again after being unhidden. |
| Queued by Staff | Sent when a staff member queues a post for review. |
| Reviewable Queued Post Revise and Reject | Sent when a staff member provides feedback while rejecting a queued reply. |
| Reviewable Queued Post Revise and Reject New Topic | Sent when a staff member provides feedback while rejecting a queued topic. |
| Silenced by Staff | Sent when a user’s account is silenced by a staff member. |
| Spam Post Blocked | Sent after posting multiple times with links to domains listed as spam. |
| TL2 Promotion Message | Sent when a user is promoted to Trust Level 2 (Member). |
| Too Many Spam Flags | Sent when a user is automatically silenced after multiple posts are flagged. |
| Too Many TL3 Flags | Sent when a Trust Level 3 user’s posts receive too many flags. |
| Unsilenced | Sent when a user’s account is no longer silenced. |
| User Added to Group as Member | Sent when a user is added to a group as a member. |
| User Added to Group as Owner | Sent when a user is added to a group as an owner. |
| User Automatically Silenced | Sent when a user is automatically silenced due to community flags. |
| User Automatically Silenced with Reason | Sent when a user is automatically silenced, including the specific reason. |
| User Posts Deleted | Sent when all of a user’s posts are deleted by a staff member. |
Welcome messages
| Template | Description |
|---|---|
| Welcome Invite | Sent after a user accepts an invitation to the community. |
| Welcome Staff | Sent to a new staff member after they are granted staff privileges. |
| Welcome TL1 User | Sent when a user is promoted to Trust Level 1 (Basic). |
| Welcome User | Sent after a user signs up and logs in. This generates an on-site notification if discourse narrative bot enabled is enabled and disable discourse narrative bot welcome post is disabled. |
Other
| Template | Description |
|---|---|
| Unsubscribe Mailer | Sent to confirm that a user wants to unsubscribe from email notifications. |
Last edited by @MarkDoerr 2026-05-01T22:19:27Z
Last checked by @MarkDoerr 2026-05-01T22:20:21Z
Check document
Perform check on document:
