Templates

Paperboy separates individual campaign content from the common layouts that you can use across many emails. The layout may have common formatting

Organization

As you may know, emails can be text-only or contain multiple parts (i.e. HTML, text, and image attachments). Paperboy supports both text-only and multipart emails based on which templates are present. These templates are stored in the layouts directory of your project:

.
└── layouts
    └── _default.text
    └── _default.html
    └── _default.css

Based on the presence of each of these files, Paperboy will decide how to compose the campaign into the final email.

Templating

Both HTML and text parts of the email are rendered using Go’s corresponding HTML and text templating libraries. They mostly offer the same functionality, except for escaping HTML/JS/URL in the former.

For each part, the content of the campaign will be rendered into the layout template using the {{ .Content }} variable. The following variables are also available to your layout:

Variable Description
.Recipient.Email Destination email for recipient
.Recipient.Params Other metadata from recipient list
.Campaign.Subject Campaign subject from front matter
.Campaign.From Campaign sender from front matter
.Address Physical address from your configuration
.UnsubscribeURL Unsubscribe link from your configuration

These variables can be inserted into your layout, and be part of simple logic operations.

Text part

The plain text portion of the email will always be included with your campaign, be it text-only or multipart. The presence of _default.text will dictate whether your campaign content will be sent directly, or if it will be decorated by the layout.

For the text part, we will not render the markup as we believe that it is the best way to present Markdown as plain text. Please file an issue if you know of a better Markdown to text renderer.

HTML part

The presence of _default.html will dictate whether Paperboy generates a multipart email. As we mentioned above, the text part will always be included as part of the email, but with _default.html you will make it a modern HTML/text multipart one.

Stylesheets

You may know that many email readers do not support <link> and <style> tags for stylesheets. Paperboy bridges that support by inlining stylesheetgs directly in to the style attribute of your HTML elements.

This inlining will be applied to both the layout and the generated campaign content.

Using <style> for inline styles

To use inline styles, add a <style> tag to the <head> seciton of your HTML template, and Paperboy will automatically map and populate CSS rules into each element’s style attribute. This inlining will be applied to both the layout and the generated campaign content.

If you’d like to use external stylesheets, you similarly insert the corresponding stylesheet tag into the <head> of your HTML template, and Paperboy will auto-inline those into your template.

<link rel="stylesheet" href="_default.css" />

The href attribute specifies the filename of the stylesheet whose path is relative to the directory of the calling template. For consistency and performance, we do not support (nor recommend) using remote stylesheets via HTTP URLs.

Preprocessing stylesheets (SASS, SCSS, etc)

Generating the CSS (via SASS or any other tooling) is outside of the scope of this tool, but we would love to figure out a better way to integrate better with CSS generation and validation tools.

Example

_default.text

{{ .Content }}
---
This email was sent to {{ .Recipient.Email }}.  If you no longer want to
receive these emails, you can unsubscribe any time: http://example.com

_default.html

<html><head>
  <link rel="stylesheet" href="_default.css" />
  <style> .footer { background: #DDD; } </style>
</head><body>
  <div class="body">
    {{ .Content }}
  </div>
  <div class="footer">
    This email was sent to {{ .Recipient.Email }}.  If you no longer want to
    receive these emails, you can <a href="http://example.com">unsubscribe</a>
    any time.
  </div>
</body></html>

_default.css

.body {
  font-size: 14px;
}
.footer {
  font-size: 11px;
}