remark42/site/content/docs/configuration/email/index.md

title

title
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 notifications for any users except anonymous:

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

  

Setup email server connection

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

SMTP_HOST
SMTP_PORT
SMTP_HELO_HOST
SMTP_TLS
SMTP_INSECURE_SKIP_VERIFY
SMTP_STARTTLS
SMTP_USERNAME
SMTP_PASSWORD
SMTP_TIMEOUT

SMTP_HELO_HOST

SMTP_HELO_HOST sets the hostname Remark42 announces in the SMTP greeting. Left unset it stays localhost, which is what Remark42 has always sent, so existing setups need no change.

Set it when the mail server rejects the greeting. Postfix with reject_non_fqdn_helo_hostname or reject_unknown_helo_hostname, which is common on hardened relays, refuses localhost and the message never leaves, typically with a 504 in the log. Give it a fully qualified name that resolves to the sending host, for example:

SMTP_HELO_HOST=comments.example.com

It applies to both paths that send mail: notification emails and the verification emails used by email authentication.

Setup email notifications

User notifications

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

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

Admin notifications

Admin would receive a message for each new comment on your site. Here is the list of variables that affect them:

NOTIFY_ADMINS=email
NOTIFY_EMAIL_FROM="Remark42 notifications"<notify@example.com>
ADMIN_SHARED_EMAIL=admin@example.com

Mailgun

Here is an example of a configuration using the 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="Remark42 login"<notify@example.com>
- NOTIFY_EMAIL_FROM="Remark42 notifications"<notify@example.com>

SendGrid

Here is an example of a configuration using the SendGrid email service:

- SMTP_HOST=smtp.sendgrid.net
- SMTP_PORT=465
- SMTP_TLS=true
- SMTP_USERNAME=apikey
- SMTP_PASSWORD=key-123456789
- AUTH_EMAIL_FROM="Remark42 login"<notify@example.com>
- NOTIFY_EMAIL_FROM="Remark42 notifications"<notify@example.com>

Mailgun or SendGrid without exposing your server's IP

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

To use any of the containers below within the Remark42 environment, set the following two SMTP variables:

- SMTP_HOST=mail
- SMTP_PORT=25

stevenolen/mailgun-smtp-server

Here is the 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 this Docker image is unmaintained and Europe domain names are not supported by this tool.

fgribreau/smtp-to-sendgrid-gateway

Here is the 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

If 2FA is enabled for your account, separate app password has to be generated. Configuration example for Gmail:

- SMTP_HOST=smtp.gmail.com
- SMTP_PORT=465
- SMTP_TLS=true
- SMTP_USERNAME=example.user@gmail.com
- SMTP_PASSWORD=aaaa bbbb cccc dddd
- AUTH_EMAIL_FROM="Remark42 login"<example.user@gmail.com>
- NOTIFY_EMAIL_FROM="Remark42 notifications"<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="Remark42 login"<notify@example.com>
- NOTIFY_EMAIL_FROM="Remark42 notifications"<notify@example.com>

You must first verify a domain or email you will use in AUTH_EMAIL_FROM or NOTIFY_EMAIL_FROM.

Then you should obtain SMTP Credentials from Amazon SES Console.

Setup email authentication

Here is the list of variables that affect email authentication:

AUTH_EMAIL_ENABLE
AUTH_EMAIL_FROM
AUTH_EMAIL_SUBJ ("remark42 confirmation" by default)
AUTH_EMAIL_CONTENT_TYPE ("text/html" by default)

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

- AUTH_EMAIL_ENABLE=true
- AUTH_EMAIL_FROM="Remark42 login"<notify@example.com>

HTML templates for emails and error messages

Remark42 uses golang templates for email templating. Templates are located in backend/app/templates/static and embedded into binary by go:embed directive.

Now we have the 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 the user subscribed to it) and for noticing admins about new comments on a site
• email_unsubscribe.html.tmpl – used for notification about successful unsubscribing from replies
• error_response.html.tmpl – used for HTML errors

To replace any template, add the file with the same name to the directory with the remark42 executable file. In case you run Remark42 inside Docker Compose, you can put customised templates into a directory like customised_templates and then mount it like that:

volumes:
  - ./var:/srv/var
  - ./customised_templates/email_confirmation_login.html.tmpl:/srv/email_confirmation_login.html.tmpl:ro
  - ./customised_templates/email_confirmation_subscription.html.tmpl:/srv/email_confirmation_subscription.html.tmpl:ro
  - ./customised_templates/email_reply.html.tmpl:/srv/email_reply.html.tmpl:ro
  - ./customised_templates/email_unsubscribe.html.tmpl:/srv/email_unsubscribe.html.tmpl:ro
  - ./customised_templates/error_response.html.tmpl:/srv/error_response.html.tmpl:ro

The easiest way to test it is to mount error_response.html.tmpl, and then head to http://127.0.0.1:8080/email/unsubscribe.html, where you are supposed to see the page like the following:

If the file is mounted correctly, the page will render the new file content immediately after hitting the refresh button in your browser once you change the file.

Template variables

Each template has access to different variables. All templates use Go's text/template syntax.

email_reply.html.tmpl — comment notification

Used for notifying users about replies to their comments and for admin notifications about new comments.

Variable	Type	Description
{{.UserName}}	string	Comment author name
{{.UserPicture}}	string	Comment author avatar URL
{{.CommentText}}	string	Comment body (HTML)
{{.CommentLink}}	string	Direct link to the comment
{{.CommentDate}}	time.Time	Comment timestamp, format with {{.CommentDate.Format "02.01.2006 at 15:04"}}
{{.ParentUserName}}	string	Parent comment author name
{{.ParentUserPicture}}	string	Parent comment author avatar URL
{{.ParentCommentText}}	string	Parent comment body (HTML)
{{.ParentCommentLink}}	string	Direct link to parent comment
{{.ParentCommentDate}}	time.Time	Parent comment timestamp
{{.PostTitle}}	string	Title of the post
{{.Email}}	string	Recipient email address
{{.UnsubscribeLink}}	string	Unsubscribe URL
{{.ForAdmin}}	bool	True when this is an admin notification

email_confirmation_subscription.html.tmpl — subscription confirmation

Sent when a user subscribes to email notifications for a comment thread.

Variable	Type	Description
{{.User}}	string	Username
{{.Token}}	string	Confirmation token
{{.Email}}	string	Recipient email address
{{.Site}}	string	Site name
{{.SubscribeURL}}	string	Subscription confirmation base URL

email_confirmation_login.html.tmpl — login confirmation

Sent when a user logs in via email authentication.

Variable	Type	Description
{{.User}}	string	Username
{{.Token}}	string	Login token
{{.Email}}	string	Recipient email address
{{.Site}}	string	Site name
{{.Address}}	string	Recipient address

Plain-text emails

The default templates produce HTML emails. To send plain-text emails instead, set AUTH_EMAIL_CONTENT_TYPE=text/plain (for login confirmation) or NOTIFY_EMAIL_CONTENT_TYPE=text/plain (for notifications), and provide custom templates that output plain text instead of HTML.

Note that {{.CommentText}} and {{.ParentCommentText}} contain HTML markup. There is no built-in HTML-to-text conversion, so for comments with rich formatting the output will include raw HTML tags.

Example plain-text notification template (email_reply.html.tmpl):

New reply from {{.UserName}}{{if .PostTitle}} on "{{.PostTitle}}"{{end}}

{{.CommentText}}
{{.CommentDate.Format "02.01.2006 at 15:04"}}
{{.CommentLink}}
{{- if .ParentCommentText}}

In reply to {{.ParentUserName}}:
{{.ParentCommentText}}
{{.ParentCommentLink}}
{{- end}}

Sent to {{.Email}}
{{- if .UnsubscribeLink}}
Unsubscribe: {{.UnsubscribeLink}}
{{- end}}