]> BookStack Code Mirror - website/blob - content/docs/admin/email-webhooks.md
a9330fcc6cc2ee916c237d75e0e0f108e4d79c04
[website] / content / docs / admin / email-webhooks.md
1 +++
2 title = "Email & Webhooks"
3 date = "2021-12-21"
4 type = "admin-doc"
5 slug = "email-webhooks"
6 aliases = ["email-config"]
7 +++
8
9 Within BookStack email is used in various ways relating to user management & authentication. 
10 Outgoing webhooks are available as a mechanism to extend BookStack or notify in an event-driven manner.
11
12 - [Email Configuration](#email-configuration)
13 - [Outgoing Webhooks](#outgoing-webhooks)
14 - [Async Action Handling](#async-action-handling)
15
16 ---
17
18 ### Email Configuration
19
20 BookStack sends out emails for a range of purposes such as email-address confirmation & "forgot password" flows.
21 Both SMTP and Sendmail (Linux Sendmail) are supported email mechanisms.
22
23 #### SMTP
24
25 To get up and running with SMTP you will need to add, or set, the following variables in your `.env` file:
26
27 ```bash
28 MAIL_DRIVER=smtp
29
30 # Host, Port & Encryption mechanism to use
31 MAIL_HOST=smtp.provider.tld
32 MAIL_PORT=465
33 MAIL_ENCRYPTION=tls
34
35 # Authentication details for your SMTP service
36 MAIL_USERNAME=user@provider.tld
37 MAIL_PASSWORD=onlyifneeded
38
39 # The "from" email address for outgoing email
40 MAIL_FROM=noreply@yourdomain.tld  
41
42 # The "from" name used for outgoing email
43 MAIL_FROM_NAME=BookStack
44 ```
45
46 #### Sendmail
47
48 The `sendmail` drivers uses the sendmail application on the host system. It will call `/usr/sbin/sendmail -bs`.
49
50 To enable this option you can set the following in your `.env` file:
51
52 ```bash
53 MAIL_DRIVER=sendmail
54
55 # The "from" email address for outgoing email
56 MAIL_FROM=noreply@yourdomain.tld  
57
58 # The "from" name used for outgoing email
59 MAIL_FROM_NAME=BookStack
60 ```
61
62 #### Debugging Email
63
64 You can follow the instructions provided in the [debugging documentation page](/docs/admin/debugging/)
65 to help gain more details about issues you may come across. Within the "Settings > Maintenance" area of
66 BookStack you can find a "Send a Test Email" action which provides a quick & easy way to send emails
67 after changing your configuration. This action will also attempt to capture any errors thrown and display them.
68
69 ---
70
71 ### Outgoing Webhooks
72
73 Webhooks can be configured in the "Settings > Webhooks" area of your BookStack instance.
74 An example of the POST data format is shown when creating or editing a webhook.
75
76 The running on webhooks can slow down a system due to the required additional processing time.
77 See the [async action handling](#async-action-handling) section below to details on running webhooks
78 in a background process to improve performance.
79
80 ---
81
82
83 ### Async Action Handling
84
85 Actions like sending email or triggering webhooks are done synchronously by default within BookStack which can
86 slow down page loading when those actions are triggered. These actions can instead be processed asynchronously
87 so they're handled in the background to prevent slowing down the request. This requires a config change 
88 and a queue worker process to handle these background jobs:
89
90 #### Config Change
91
92 Within your `.env` file add or update (if already existing) the following option then save the file.
93
94 ```bash
95 QUEUE_CONNECTION=database
96 ```
97
98 #### Queue Worker Process
99
100 The queue work process can be run via the following command from your BookStack installation directory:
101
102 ```bash
103 php artisan queue:work --sleep=3 --tries=3
104 ```
105
106 Ideally this needs to be ran continuously. The method of doing this may depend on your operating system
107 and personal software preferences. On many modern Linux systems systemd is an appropriate method.
108 The below unit file example can be used with systemd to run this process. Note, this is suited to 
109 Ubuntu 20.04 setups that have used our installation script. Details may need tweaking for other systems.
110
111 ```bash
112 [Unit]
113 Description=BookStack Queue Worker
114
115 [Service]
116 User=www-data
117 Group=www-data
118 Restart=always
119 ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600
120
121 [Install]
122 WantedBy=multi-user.target
123 ```
124
125 To configure systemd (On a Ubuntu 20.04 system) with the above unit you'd typically:
126
127 - Create a new `/etc/systemd/system/bookstack-queue.service` file containing the above content.
128 - Run `systemctl daemon-reload` to discover the new service.
129 - Run `systemctl enable bookstack-queue.service` to ensure the service starts at (re)boot.
130 - Run `systemctl start bookstack-queue.service` to start the queue service.
131
132 Note: you may need to run the above commands with `sudo` if not acting as a privileged user. 
133 You can then use `systemctl status bookstack-queue.service` to check the status of the queue worker.