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.
Using <link> to include CSS files
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;
}