Setup Email Configuration for Bookstack

BookStack sends out emails for a range of purposes such as email-address confirmation & “forgot password” flows. Both SMTP and Sendmail (Linux Sendmail) are supported email mechanisms.

SMTP

To get up and running with SMTP you will need to add, or set, the following variables in your .env file or docker-compose.yaml:

MAIL_DRIVER=smtp

# SMTP server host address
MAIL_HOST=smtp.provider.tld

# SMTP server port
# Using port 465 will force connections to be via TLS
MAIL_PORT=587

# Connection encryption to use
# Valid values are: tls, null
# Using 'tls' will require either TLS or STARTTLS to be used.
# When using 'null' STARTTLS will still be attempted if announced
# as supported by your SMTP server.
# Using port 465 above will force connections to be via TLS.
MAIL_ENCRYPTION=tls

# Authentication details for your SMTP service
MAIL_USERNAME=user@provider.tld
MAIL_PASSWORD=onlyifneeded

# The "from" email address for outgoing email
MAIL_FROM=noreply@yourdomain.tld  

# The "from" name used for outgoing email
MAIL_FROM_NAME=BookStack

Connection TLS/SSL Certificate Verification

In some cases your SMTP server may be using a private/self-signed TLS/SSL certificate that would usually fail certificate verification. In these cases its common for that certificate (Or its CA) to be added to the BookStack’s host trusted certificate database. If that’s not possible, you can alternatively disable SSL/TLS certificate verification for mail sending by adding this setting to your .env file or docker-compose.yaml:

# Verify SSL/TLS certificates during SMTP sending
# WARNING: Disabling verification using a 'false' value 
# can make you vulnerable to MITM attacks
MAIL_VERIFY_SSL=false

Sendmail

The sendmail drivers uses the sendmail application on the host system. By default it will call /usr/sbin/sendmail -bs although this is configurable.
To enable this option you can set the following in your .env file or docker-compose.yaml:

MAIL_DRIVER=sendmail

# The "from" email address for outgoing email
MAIL_FROM=noreply@yourdomain.tld  

# The "from" name used for outgoing email
MAIL_FROM_NAME=BookStack

# The command to use for calling sendmail
MAIL_SENDMAIL_COMMAND="/usr/sbin/sendmail -bs"

Debugging Email

You can follow the instructions provided in the debugging documentation page to help gain more details about issues you may come across. Within the “Settings > Maintenance” area of BookStack you can find a “Send a Test Email” action which provides a quick & easy way to send emails after changing your configuration. This action will also attempt to capture any errors thrown and display them.