Configuration

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"

  1. This material is intended for general information purposes only and does not constitute legal advice. [return]