Pryv.io email configuration

This document describes how to configure the settings for the sending of email for 1) account creation and 2) password reset requests.

The prerequisite for this is a running Pryv.io platform (refer to the Pryv.io setup guide).

The email settings are to be set either directly through the platform settings configuration file platform.yml or through the admin panel.

Table of contents

  1. Transport
    1. Sendmail
    2. Your own SMTP server
  2. Email settings
    1. Activation
    2. Sender
      1. Using your Pryv.io domain
    3. Email template default language
  3. Templates
    1. Welcome
    2. Password reset
  4. Previous version

Transport

Emails can be sent using:

Sendmail

Sendmail is useful for development purposes and not recommended for production. To activate it, set EMAIL_SENDMAIL_SETTINGS:

in the platform.yml file:

EMAIL_SENDMAIL_SETTINGS:
  description: "Alternative transport, using sendmail. Will replace SMTP transport if set to true"
  value:
    active: true

or in the admin panel:

{
  "active": true
}

This will override the SMTP settings.

Your own SMTP server

For production purposes, we strongly recommend to setup your own SMTP server. To activate its usage, disable Sendmail as described above and set EMAIL_SMTP_SETTINGS:

in the platform.yml file:

EMAIL_SMTP_SETTINGS:
  description: "If used, Host, port and credentials of the SMTP server"
  value:
    host: your-smtp-server-hostname
    port: your-smtp-server
    auth:
      user: REPLACE_ME
      pass: REPLACE_ME

in the admin panel:

{
  "host": "your-smtp-server-hostname",
  "port": "your-smtp-server",
  "auth": {
    "user": "REPLACE_ME",
    "pass": "REPLACE_ME"
  }
}

Email settings

Activation

You can choose whether to activate or not the welcome and password reset emails setting EMAIL_ACTIVATION:

in the platform.yml file:

EMAIL_ACTIVATION:
  description: "Allows to activate/deactivate sending of welcome and password reset emails"
  value: 
    welcome: true
    resetPassword: true

in the admin panel:

{
  "welcome": true,
  "resetPassword": true
}

Sender

You can define the email sender name and email address setting EMAIL_SENDER:

in the platform.yml file:

EMAIL_SENDER:
  description: "Sender name and email address"
  value: 
    name: REPLACE_ME
    address: REPLACE_ME

in the admin panel:

{
  "name": "Pryv Lab no reply",
  "address": "no-reply@pryv.io"
}

Using your Pryv.io domain

SMTP servers use SPF records to help prevent email spoofing. In order to send an email on behalf of a certain domain, you will need to add the SPF record associated with your SMTP server to your domain’s DNS zone.
If you choose to use the domain associated with your Pryv.io platform, you should add a SPF record similar to this one:

@ 10800 IN TXT "v=spf1 include:spf.mandrillapp.com ~all"

In the SPF record above, we declared that Mandrill can be used to send emails on behalf of the domain of our Pryv.io platform. You can of course replace Mandrill by the SPF address of the SMTP host(s) of your choice.

Please refer to the DNS configuration document on how to set such SPF record in the Pryv.io DNS.

Email template default language

You can set the default language for the template that will be applied if you do not provide a language field in the Create user API method, by setting EMAIL_TEMPLATES_DEFAULT_LANG:

in the platform.yml file:

EMAIL_TEMPLATES_DEFAULT_LANG: 
  value: en
  description: "Default language for email templates eg: en"

in the admin panel:

en

Templates

Pryv.io currently comes with email templates in 3 languages. Other languages can be provided in pug format, a templating language for HTML. These templates can be set in the platform.yml file or through the admin panel:

Welcome

The welcome template accepts the following variables:

<img src="https://pryv.github.io/style/images/logo-256.png" alt="Logo"> 
<h1><span style="color:#bd1026">Hey</span> #{USERNAME},</h1>
<h2><span style="color:#bd1026">Thanks for creating your Pryv account</span></h2>

Password reset

The welcome template accepts the following variables:

p Hi,
p We have received word that you have lost your password. If you have asked for a password request please click on the link below. If you did not please delete this email.
p <a href="#{RESET_URL}?resetToken=#{RESET_TOKEN}" target="_blank">Click here</a> to reset your Pryv password.
p Pryv team

Previous version

The previous guide for email configuration is still available here.