All emails sent from your site are wrapped in an HTML template that can be customized from the Admin / Customize / Email Style section of your site.
If you look at the default markup that is displayed in the editor, you will see an %{email_content} placeholder in the markup’s body section. When emails are sent from Discourse, the content of the email will be substituted for this placeholder. You can make any changes that you like to the template as long as you do not remove this placeholder.
For details about customizing the content that gets set by the %{email_content} placeholder, see Customize specific email templates.
Using CSS classes to add inline styles to a template
The CSS section of the Email Style editor can be used to inject inline styles into your template. As an example, if you have a td element in the email that you would like to style with padding: 30px 0 30px 0; , you can either add the CSS directly to the element (<td style="padding: 30px 0 30px 0;">) or you can add a CSS class to the element, and then create a rule for the class in the CSS editor:
Editor HTML:
<td class="my-outer-td">
</td>
CSS:
.my-outer-td {
padding: 30px 0 30px 0;
}
Discourse will replace the CSS class you’ve added with the CSS rule before sending the email. The results with either approach will be the same.
Testing emails
The main difficulty with creating HTML emails is that not all email clients will interpret the HTML in the same way. The Outlook email client is notoriously difficult to work with. If you are making anything more than a minor change to the template, you need to test your changes on all email clients that you want to support. The standard approach to this is to use an email testing service that will show you how your emails will look on a variety of clients. It is important to not skip this step.
Reverting your changes
If you ever want to revert your template customization, click the “Reset to default” button that’s displayed at the bottom of the template editor. This will replace your changes with the default Discourse email template.
Custom template example
Here’s a basic email template that I’ve run through an email testing service. It constrains the width of emails sent from Discourse to a maximum of 600px. It also adds a logo to the top of the email.
If you use this template, you’ll need to replace the image src and alt text that is used in the example with your site’s logo URL and site name. You will also need to set the a elements’s href to your site’s URL:
<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>
<!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>
How it looks
iPad Pro (10.5 inch) (iOS 13.1):
Gmail (Chrome):
iPhone 11 Pro Max (iOS 13.1):
Outlook 2019 (Windows 10)
Custom template interaction with the Digest Email
If your email template adds a logo to all emails sent from Discourse, you’ll want to take one of the follow actions:
-
If you want to use the default digest email styling: Disable the
apply custom styles to digestsite setting to avoid having your template used as the outer wrapper for Discourse summary emails. If you don’t do this, summary emails sent from your site will have two logos displayed at the top of the email. -
If you want to keep the same styling across all of your notification emails: You’ll need get rid of the default digest logo since it would clash with the logo you introduce in your custom template and add extra padding/space. To overcome this, remove any images that have been set as the
digest logosite setting to avoid confusion in the future, and then setup a custom digest header HTML by adding<span></span>to the following text customization:.../admin/customize/site_texts/user_notifications.digest.custom.html.header
If you have made changes to the custom template and would like to use the template with the summary email, it would be a good idea to send a preview of the summary email to an email testing service. If the testing service provides you with an email address, you can send the summary email directly to that address from your Admin / Emails / Preview Summary page.
Further reading
The go to reference for creating HTML emails seems to be this post by Nicole Merlin: Build an HTML Email Template From Scratch. The post was written in 2013, but not much has changed since that time. Most of what I know about HTML emails is from reading through that tutorial.
