docs: Added email test steps (#291)

* docs: Added email test steps #267

* Added known issue from #290

* Clarified DAVx5 known issue

* Added instructions for gmail app passwords

Author: ckulka

docs/email-guide.md

@@ -6,11 +6,30 @@ In order to send out emails, you need a working SMTP service - you can host your
 
 The entire email configuration is stored in the `MSMTPRC` environment variable.
 
+> [!Tip]
+> After you have set up your configuration, you can run a quick test by sending an email from the command line.
+>
+> This is especially helpful when you do not receive emails from Baikal and you want to narrow down the error.
+>
+> 1. Start your Baikal container with the SMTP configuration
+> 1. Open a command prompt inside the Baikal container
+>
+>    ```sh
+>    docker exec -it <conatiner_name> /bin/sh
+>    ```
+>
+> 1. Send an email
+>
+>    ```sh
+>    echo "Hello world." | msmtp -a default your-email-address@example.com
+>    ```
+
 ## Generic SMTP server
 
 If you have an SMTP server without security in place, i.e. no authentication or SSL/TLS/STARTTLS, then you only have to configure the SMTP server name. Needless to say it's highly recommended to have authentication and TLS in place.
 
 ```yaml
+# docker-compose.yaml
 services:
   baikal:
     image: ckulka/baikal:nginx
@@ -25,6 +44,7 @@ services:
 If you have TLS and authentication in place, add the following configuration parameters:
 
 ```yaml
+# docker-compose.yaml
 services:
   baikal:
     image: ckulka/baikal:nginx
@@ -47,11 +67,22 @@ See [examples/docker-compose.email.yaml](../examples/docker-compose.email.yaml)
 
 ## Gmail
 
-If you use Gmail as your SMTP server, you have to first allow less secure apps (sendmail) to use Gmail, see [Less secure apps & your Google Account](https://support.google.com/accounts/answer/6010255?hl=en#zippy=).
+> [!IMPORTANT]
+> Username/password authentication using seems to be no longer available.
+>
+> For more details, see [Less secure apps & your Google Account](https://support.google.com/accounts/answer/6010255).
+
+If you use Gmail as your SMTP server, you have create an app password:
+
+1. Enable two-factor authentication (2FA): <https://myaccount.google.com/signinoptions/twosv>
+2. Create an app password: <https://myaccount.google.com/u/0/apppasswords>
+
+For more details on app passwords, see [Sign in with app passwords](https://support.google.com/accounts/answer/185833).
 
 Once that is done, use the following configuration:
 
 ```yaml
+# docker-compose.yaml
 services:
   baikal:
     image: ckulka/baikal:nginx
@@ -70,3 +101,13 @@ services:
 ```
 
 See [examples/docker-compose.sendmail-gmail.yaml](../examples/docker-compose.email-gmail.yaml) for a starter template.
+
+## Known issues
+
+### DAVx5 but usernames are not an emails
+
+When using DAVx5, then your Baikal usernames must be email addresses, otherwise email invitations will not be sent out.
+
+For more details, see <https://manual.davx5.com/accounts_collections.html#account-names>.
+
+Kodus to @deathblade666 for finding this out in <https://github.com/ckulka/baikal-docker/issues/290#issuecomment-3136438356>.