This guide explains how to customize and style the outer HTML template for all emails sent from your Discourse site.
Required user level: Administrator
All emails sent from your site are wrapped in an HTML template that can be customized.
This guide covers:
- Accessing the email style customization section
- Modifying the HTML template
- Adding custom CSS
- Testing email templates
- Reverting changes
- A custom template example
- Interaction with digest emails
- Changing email fonts
Accessing the email style customization
- Navigate to Admin / Customize / Email Style in your Discourse site.
- You’ll see an editor where you can modify the HTML and CSS for your email template.
Modifying the HTML template
The default markup in the editor contains an %{email_content} placeholder in the body section. This placeholder is where the content of each email will be inserted. You can make any changes to the template as long as you don’t remove this placeholder.
For information on customizing the content that replaces the %{email_content} placeholder, see how to customize specific email templates.
Adding custom CSS
You can use the CSS section of the Email Style editor to inject inline styles into your template. Here’s an example:
-
Add a CSS class to an HTML element in the template:
<td class="my-outer-td"> </td> -
Create a rule for the class in the CSS editor:
.my-outer-td { padding: 30px 0 30px 0; }
Discourse will replace the CSS class with the actual CSS rule before sending the email. You can add any CSS rules you like here.
Testing email templates
It’s crucial to test your email template changes across various email clients, as they may interpret HTML differently. Use an email testing service to preview how your emails will appear on different clients, especially for significant changes.
Reverting changes
To revert your template customization:
- Scroll to the bottom of the template editor.
- Click the “Reset to default” button.
This action will replace your changes with the default Discourse email template.
Custom template example
Here’s a basic email template that constrains the width of emails to a maximum of 600px and adds a logo to the top:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<title></title>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
</head>
<body style="margin: 0; padding: 0;">
<!--[if mso]>
<style type="text/css">
body, table, td, th, h1, h2, h3 { font-family: Helvetica, Arial, sans-serif !important; }
</style>
<![endif]-->
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td style="padding: 10px 0 30px 0;">
<!--[if gte mso 9]>
<table width="600" align="center" cellpadding="0" cellspacing="0">
<tr>
<td>
<![endif]-->
<table align="center" border="0" cellpadding="0" cellspacing="0" width="100%" style="max-width: 600px;border-collapse: collapse;">
<tr>
<td style="padding: 20px 15px 20px 15px;">
<table align="center" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="center">
<a href="https://forum.example.com">
<img src="https://your-site-logo-url" alt="Your site name" width="150" height="40" style="display: block;"/>
</a>
</td>
</tr>
</table>
</td>
</tr>
<tr>
<td style="padding: 0 15px 0 15px;">
<hr style="background-color: #ddd; height: 1px; border: 1px;">
</td>
</tr>
<tr>
<td style="padding: 20px 15px 30px 15px; color: #153643; font-family: Helvetica, Arial, sans-serif; font-size: 16px; line-height: 20px;">
%{email_content}
</td>
</tr>
</table>
<!--[if gte mso 9]>
</td>
</tr>
</table>
<![endif]-->
</td>
</tr>
</table>
</body>
</html>
Remember to replace the image src, alt, and href attributes with your site’s specific information.
Here's how it looks on different screen sizes
iPad Pro (10.5 inch) (iOS 13.1):
Gmail (Chrome):
iPhone 11 Pro Max (iOS 13.1):
Outlook 2019 (Windows 10)
Interaction with digest emails
If your custom template adds a logo to all emails, you have two options for digest emails:
-
To use the default digest email styling:
- Disable the
apply custom styles to digestsite setting.
- Disable the
-
To maintain consistent styling across all notification emails:
- Remove any images set as the
digest logosite setting. - Add
<span></span>to the text customization at.../admin/customize/site_texts/user_notifications.digest.custom.html.header.
- Remove any images set as the
Changing email fonts
To change fonts in your emails:
-
Use web-safe fonts for maximum compatibility. Refer to CSS Font Stack for a list of available fonts on Windows and Mac.
-
Add CSS rules for the fonts to your Discourse email template.
-
You can set fonts directly in HTML elements, for example:
<td style="font-family: Helvetica, Arial, sans-serif; font-size: 16px; line-height: 20px;"> %{email_content} </td>
Note that web fonts from external services are not supported by many email clients.
Additional resources
For more information on creating HTML emails, you can refer to this comprehensive guide on building an HTML email template from scratch.
Last edited by @hugh 2024-07-30T01:58:08Z
Last checked by @hugh 2024-07-30T01:58:15Z
Check document
Perform check on document:
