Remark42
v1.8.1

Email Settings

Overview

This documentation describes how to enable the email-related capabilities of Remark.

  • email authentication for users:

    enabling this will let the user log in using their emails:

    Email authentication

  • email notifications for any users except anonymous:

    GitHub or Google or Twitter or any other kind of user gets the ability to get
    email notifications about new replies to their comments (and any of the replies down the tree):

    Email notifications subscription

Setup email server connection

To enable any of email functionality you need to set up email
(SMTP) server connection using these variables:

SMTP_HOST
SMTP_PORT
SMTP_TLS
SMTP_USERNAME
SMTP_PASSWORD
SMTP_TIMEOUT

Setup email notifications

User notifications

Here is the list of variables which affect user email notifications:

NOTIFY_USERS=email
NOTIFY_EMAIL_FROM=notify@example.com
NOTIFY_EMAIL_VERIFICATION_SUBJ # "Email verification" by default

Admin notifications

Here is the list of variables which affect admin notifications, which will be sent for each new comment on your site:

NOTIFY_ADMINS=email
NOTIFY_EMAIL_FROM=notify@example.com
ADMIN_SHARED_EMAIL=admin@example.com

Mailgun

This is an example of a configuration using Mailgun email service:

- SMTP_HOST=smtp.eu.mailgun.org
- SMTP_PORT=465
- SMTP_TLS=true
- SMTP_USERNAME=postmaster@mg.example.com
- SMTP_PASSWORD=secretpassword
- AUTH_EMAIL_FROM=notify@example.com
- NOTIFY_EMAIL_FROM=notify@example.com

API

When you don't want to expose your IP (which is impossible with any SMTP provider)
and for situations when connecting to external SMTP server is impossible due to firewall
settings is setting up an SMTP-to-API bridge and sending messages through it.

To use any of containers below with in remark42 environment set following two SMTP variables:

- SMTP_HOST=mail
- SMTP_PORT=25

stevenolen/mailgun-smtp-server

Here is docker-compose.yml configuration part spinning up a container for
stevenolen/mailgun-smtp-server:

mailgun:
  image: stevenolen/mailgun-smtp-server
  container_name: "mail"
  hostname: "mail"

  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "5"

  environment:
    - MG_KEY=key-123456789
    - MG_DOMAIN=example.com

Please note that before
stevenolen/mailgun-smtp-server#5
is fixed, Europe domain names are not supported by this tool.

SendGrid

This is an example of a configuration using SendGrid email service:

- SMTP_HOST=smtp.sendgrid.net
- SMTP_PORT=465
- SMTP_TLS=true
- SMTP_USERNAME=apikey
- SMTP_PASSWORD=key-123456789
- AUTH_EMAIL_FROM=notify@example.com
- NOTIFY_EMAIL_FROM=notify@example.com

API

When you don't want to expose your IP (which is impossible with any SMTP provider)
and for situations when connecting to external SMTP server is impossible due to firewall
settings is setting up an SMTP-to-API bridge and sending messages through it.

To use any of containers below with in remark42 environment set following two SMTP variables:

- SMTP_HOST=mail
- SMTP_PORT=25

fgribreau/smtp-to-sendgrid-gateway

Here is docker-compose.yml configuration part spinning up a container for
fgribreau/smtp-to-sendgrid-gateway:

sendgrid:
  image: fgribreau/smtp-to-sendgrid-gateway
  container_name: "mail"
  hostname: "mail"

  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "5"

  environment:
    - SENDGRID_API=key-123456789

Gmail

Configuration example for Gmail:

- SMTP_HOST=smtp.gmail.com
- SMTP_PORT=465
- SMTP_TLS=true
- SMTP_USERNAME=example.user@gmail.com
- SMTP_PASSWORD=secretpassword
- AUTH_EMAIL_FROM=example.user@gmail.com
- NOTIFY_EMAIL_FROM=example.user@gmail.com

Amazon SES

Configuration example for Amazon SES (us-east-1 region):

- SMTP_HOST=email-smtp.us-east-1.amazonaws.com
- SMTP_PORT=465
- SMTP_TLS=true
- SMTP_USERNAME=access_key_id
- SMTP_PASSWORD=secret_access_key
- AUTH_EMAIL_FROM=notify@example.com
- NOTIFY_EMAIL_FROM=notify@example.com

A domain or an email that will be used in AUTH_EMAIL_FROM or NOTIFY_EMAIL_FROM
must first be verified.

SMTP Credentials
must first be obtained from
Amazon SES Console:

Setup email authentication

Here is the list of variables which affect email authentication:

AUTH_EMAIL_ENABLE
AUTH_EMAIL_FROM
AUTH_EMAIL_SUBJ
AUTH_EMAIL_CONTENT_TYPE
AUTH_EMAIL_TEMPLATE

After you set SMTP_ variables, you can allow email authentication by setting these two variables:

- AUTH_EMAIL_ENABLE=true
- AUTH_EMAIL_FROM=notify@example.com

Usually, you don't need to change/set anything else. In case if you want to use a different
email template set AUTH_EMAIL_TEMPLATE, for instance
- AUTH_EMAIL_TEMPLATE="Confirmation email, token: ".
See verified-authentication for more details.

Email messages templates

Remark42 uses golang templates for email templating. Templates are located in backend/templates and embedded into binary by statik

For getting access to the files you can use package templates from backend/app/templates

Now we have following templates:

  • email_confirmation_login.html.tmpl – used for confirmation of login
  • email_confirmation_subscription.html.tmpl – used for confirmation of subscription
    – email_reply.html.tmpl – used for sending replies to user comments (when user subscribed to it) and for noticing admins about new comments on a site
    – email_unsubscribe.html.tmpl – used for notification about successful unsubscribe from replies
    – error_response.html.tmpl – used for ...