Customize and style the Discourse outer email template

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 How to 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)

Preventing custom template from being used with the Digest email

If your email template adds a logo to all emails sent from Discourse, you need to disable the apply custom styles to digest site 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 have made changes to the template and would like to use the custom 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.

12 Likes

Thank @simon!

Could you be so kind to provide a full text of template? I would be happy to try it.

2 Likes

Thanks for pointing that out. It must have been a copy/paste error when I created the topic. I’ve added the full template to the post now.

2 Likes

How can we get the logo_url from Discourse in this template? is this possible?

The easiest way might be to open your browser’s web inspector on your DIscourse site and copy the value of the logo’s src attribute into the template. You could also get the logo URL from the rails console by looking at the value of the url property that is returned for SiteSetting.logo

2 Likes

Ok cool, this is how I’m doing it right now, thanks!

1 Like

Very nice. I think this should be the default. Most sites use a centered column 600px wide.

Seems like there should be a separate wrapper to edit for digest emails.

1 Like