Configuration file config.toml
in the top directory of your project is the
gateway between your [project][project] source tre, and emails landing into
inboxes of your eagerly-awaiting recipients. Here, you will configure the
SMTP delivery service, as well as methods to sign and theme your emails.
Basic configuration
Paperboy requires minimal configuration to get started.
Specifying from
field and smtp
section is all you need to send the
initial email.
These are the configuration variables:
Required | Variable | Description |
---|---|---|
✔ | from | Default sender address (can be overriden by campaign front matter) |
theme | Template theme. See theming | |
address | Physical address for your CAN-SPAM footer | |
unsubscribeURL | Unsubscribe URI template (RFC 6570) for your CAN-SPAM footer |
Anti-SPAM compliance 1
Legally, you may be required to include a physical address and an unsubscribe link for
all commerical emails. Paperboy makes that easy by availing address
and unsubscribeURL
configuration keys, which are respectively exposed as
{{ .Address }}
and {{ .UnsubscribeURL }}
in your templates.
Please note that unsubscribeURL
is an RFC 6570 URI template that will
be populated for every recipient using the same context variables available to
your layout templates.
For example, you can use the following for your unsubscribeURL
:
https://example.org/unsubscribe/{Recipient.Email}
https://example.org/dash/{Recipient.Params.username}/email-settings
See templates and lists documentation for more information about template context variables.
Required SMTP configuration
Emails are sent, forwared, and delivered via Standard Mail Transfer Protocol (aka SMTP). You don’t really have to know how it work, just how to connect Paperboy to one of many available SMTP services.
You may configure the delivery server in the smtp
section of your config.toml.
[smtp]
url = "smtp://email.us-east-1.service.com"
user = "smooth-sender"
pass = "shhhhh-secret"
Choosing an SMTP service
Not all services and emails are made equal. If you use a modern mail client, you’ve probably noticed that emails are now often tiered into Important, Bulk, and Junk/Spam. Your goal should be not just to stay out of the Spam folder and get many “engagements” for your campaign, but also to avoid tainting the reputation of your SMTP service for future campaigns.
There are plenty of guides on how to avoid spam filters, comply with anti-spam laws, and choose bulk-email services. These are outside the scope of this documentation.
Validating your email domain
Validating ownership of the domain name used in your “From” email address will give confidence to both your recipients and to Spam filters that your emails are not using a fake or spoofed address. This may be tricky to configure, but many domain registration services have detailed guides on how to set this up. Below, we describe how to integrate this with Paperboy:
Configure DKIM
If you’ve gone through setting up DKIM, you will have a private key file that
you will use to sign emails. Insert the following into your config.toml
to
sign each outgoing email:
[dkim]
# Requied fields
keyFile = "./config/dkim.private"
domain = "paperboy.email"
selector: "paperboy"
# Optional fields
canonicalization = "relaxed/relaxed"
signatureExpireIn = 3600
Configure SPF
Not yet supported
Example
paperboy init
will generate a basic configuration file for you
that will look a bit like this:
from = "Example <example@example.org>"
address = "Paperboy Inc, 123 Main St. New York, NY 10010, USA"
unsubscribeURL = "https://example.org/unsubscribe/{Recipient.Email}"
[smtp]
url = "smtp://smtp.example.org"
- This material is intended for general information purposes only and does not constitute legal advice. [return]