Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Commit

Permalink
Move email to Server section in config file documentation (#14730)
Browse files Browse the repository at this point in the history 
* Move `email` to server in config file documentation

* changelog
  • Loading branch information
@dklimpel
dklimpel authored Dec 28, 2022
1 parent a52822d commit 2fb4071
Show file tree
Hide file tree
Showing 2 changed files with 110 additions and 108 deletions.
1 change: 1 addition & 0 deletions changelog.d/14730.doc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Move `email` to Server section in config file documentation.
217 changes: 109 additions & 108 deletions docs/usage/configuration/config_documentation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -569,6 +569,115 @@ Example configuration:
```yaml
delete_stale_devices_after: 1y
```
---
### `email`

Configuration for sending emails from Synapse.

Server admins can configure custom templates for email content. See
[here](../../templates.md) for more information.

This setting has the following sub-options:
* `smtp_host`: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'.
* `smtp_port`: The port on the mail server for outgoing SMTP. Defaults to 465 if `force_tls` is true, else 25.

_Changed in Synapse 1.64.0:_ the default port is now aware of `force_tls`.
* `smtp_user` and `smtp_pass`: Username/password for authentication to the SMTP server. By default, no
authentication is attempted.
* `force_tls`: By default, Synapse connects over plain text and then optionally upgrades
to TLS via STARTTLS. If this option is set to true, TLS is used from the start (Implicit TLS),
and the option `require_transport_security` is ignored.
It is recommended to enable this if supported by your mail server.

_New in Synapse 1.64.0._
* `require_transport_security`: Set to true to require TLS transport security for SMTP.
By default, Synapse will connect over plain text, and will then switch to
TLS via STARTTLS *if the SMTP server supports it*. If this option is set,
Synapse will refuse to connect unless the server supports STARTTLS.
* `enable_tls`: By default, if the server supports TLS, it will be used, and the server
must present a certificate that is valid for 'smtp_host'. If this option
is set to false, TLS will not be used.
* `notif_from`: defines the "From" address to use when sending emails.
It must be set if email sending is enabled. The placeholder '%(app)s' will be replaced by the application name,
which is normally set in `app_name`, but may be overridden by the
Matrix client application. Note that the placeholder must be written '%(app)s', including the
trailing 's'.
* `app_name`: `app_name` defines the default value for '%(app)s' in `notif_from` and email
subjects. It defaults to 'Matrix'.
* `enable_notifs`: Set to true to enable sending emails for messages that the user
has missed. Disabled by default.
* `notif_for_new_users`: Set to false to disable automatic subscription to email
notifications for new users. Enabled by default.
* `client_base_url`: Custom URL for client links within the email notifications. By default
links will be based on "https://matrix.to". (This setting used to be called `riot_base_url`;
the old name is still supported for backwards-compatibility but is now deprecated.)
* `validation_token_lifetime`: Configures the time that a validation email will expire after sending.
Defaults to 1h.
* `invite_client_location`: The web client location to direct users to during an invite. This is passed
to the identity server as the `org.matrix.web_client_location` key. Defaults
to unset, giving no guidance to the identity server.
* `subjects`: Subjects to use when sending emails from Synapse. The placeholder '%(app)s' will
be replaced with the value of the `app_name` setting, or by a value dictated by the Matrix client application.
In addition, each subject can use the following placeholders: '%(person)s', which will be replaced by the displayname
of the user(s) that sent the message(s), e.g. "Alice and Bob", and '%(room)s', which will be replaced by the name of the room the
message(s) have been sent to, e.g. "My super room". In addition, emails related to account administration will
can use the '%(server_name)s' placeholder, which will be replaced by the value of the
`server_name` setting in your Synapse configuration.

Here is a list of subjects for notification emails that can be set:
* `message_from_person_in_room`: Subject to use to notify about one message from one or more user(s) in a
room which has a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..."
* `message_from_person`: Subject to use to notify about one message from one or more user(s) in a
room which doesn't have a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s..."
* `messages_from_person`: Subject to use to notify about multiple messages from one or more users in
a room which doesn't have a name. Defaults to "[%(app)s] You have messages on %(app)s from %(person)s..."
* `messages_in_room`: Subject to use to notify about multiple messages in a room which has a
name. Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room..."
* `messages_in_room_and_others`: Subject to use to notify about multiple messages in multiple rooms.
Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room and others..."
* `messages_from_person_and_others`: Subject to use to notify about multiple messages from multiple persons in
multiple rooms. This is similar to the setting above except it's used when
the room in which the notification was triggered has no name. Defaults to
"[%(app)s] You have messages on %(app)s from %(person)s and others..."
* `invite_from_person_to_room`: Subject to use to notify about an invite to a room which has a name.
Defaults to "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..."
* `invite_from_person`: Subject to use to notify about an invite to a room which doesn't have a
name. Defaults to "[%(app)s] %(person)s has invited you to chat on %(app)s..."
* `password_reset`: Subject to use when sending a password reset email. Defaults to "[%(server_name)s] Password reset"
* `email_validation`: Subject to use when sending a verification email to assert an address's
ownership. Defaults to "[%(server_name)s] Validate your email"

Example configuration:

```yaml
email:
smtp_host: mail.server
smtp_port: 587
smtp_user: "exampleusername"
smtp_pass: "examplepassword"
force_tls: true
require_transport_security: true
enable_tls: false
notif_from: "Your Friendly %(app)s homeserver <noreply@example.com>"
app_name: my_branded_matrix_server
enable_notifs: true
notif_for_new_users: false
client_base_url: "http://localhost/riot"
validation_token_lifetime: 15m
invite_client_location: https://app.element.io
subjects:
message_from_person_in_room: "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..."
message_from_person: "[%(app)s] You have a message on %(app)s from %(person)s..."
messages_from_person: "[%(app)s] You have messages on %(app)s from %(person)s..."
messages_in_room: "[%(app)s] You have messages on %(app)s in the %(room)s room..."
messages_in_room_and_others: "[%(app)s] You have messages on %(app)s in the %(room)s room and others..."
messages_from_person_and_others: "[%(app)s] You have messages on %(app)s from %(person)s and others..."
invite_from_person_to_room: "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..."
invite_from_person: "[%(app)s] %(person)s has invited you to chat on %(app)s..."
password_reset: "[%(server_name)s] Password reset"
email_validation: "[%(server_name)s] Validate your email"
```

## Homeserver blocking
Useful options for Synapse admins.
Expand Down Expand Up @@ -3259,114 +3368,6 @@ ui_auth:
session_timeout: "15s"
```
---
### `email`

Configuration for sending emails from Synapse.

Server admins can configure custom templates for email content. See
[here](../../templates.md) for more information.

This setting has the following sub-options:
* `smtp_host`: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'.
* `smtp_port`: The port on the mail server for outgoing SMTP. Defaults to 465 if `force_tls` is true, else 25.

_Changed in Synapse 1.64.0:_ the default port is now aware of `force_tls`.
* `smtp_user` and `smtp_pass`: Username/password for authentication to the SMTP server. By default, no
authentication is attempted.
* `force_tls`: By default, Synapse connects over plain text and then optionally upgrades
to TLS via STARTTLS. If this option is set to true, TLS is used from the start (Implicit TLS),
and the option `require_transport_security` is ignored.
It is recommended to enable this if supported by your mail server.

_New in Synapse 1.64.0._
* `require_transport_security`: Set to true to require TLS transport security for SMTP.
By default, Synapse will connect over plain text, and will then switch to
TLS via STARTTLS *if the SMTP server supports it*. If this option is set,
Synapse will refuse to connect unless the server supports STARTTLS.
* `enable_tls`: By default, if the server supports TLS, it will be used, and the server
must present a certificate that is valid for 'smtp_host'. If this option
is set to false, TLS will not be used.
* `notif_from`: defines the "From" address to use when sending emails.
It must be set if email sending is enabled. The placeholder '%(app)s' will be replaced by the application name,
which is normally set in `app_name`, but may be overridden by the
Matrix client application. Note that the placeholder must be written '%(app)s', including the
trailing 's'.
* `app_name`: `app_name` defines the default value for '%(app)s' in `notif_from` and email
subjects. It defaults to 'Matrix'.
* `enable_notifs`: Set to true to enable sending emails for messages that the user
has missed. Disabled by default.
* `notif_for_new_users`: Set to false to disable automatic subscription to email
notifications for new users. Enabled by default.
* `client_base_url`: Custom URL for client links within the email notifications. By default
links will be based on "https://matrix.to". (This setting used to be called `riot_base_url`;
the old name is still supported for backwards-compatibility but is now deprecated.)
* `validation_token_lifetime`: Configures the time that a validation email will expire after sending.
Defaults to 1h.
* `invite_client_location`: The web client location to direct users to during an invite. This is passed
to the identity server as the `org.matrix.web_client_location` key. Defaults
to unset, giving no guidance to the identity server.
* `subjects`: Subjects to use when sending emails from Synapse. The placeholder '%(app)s' will
be replaced with the value of the `app_name` setting, or by a value dictated by the Matrix client application.
In addition, each subject can use the following placeholders: '%(person)s', which will be replaced by the displayname
of the user(s) that sent the message(s), e.g. "Alice and Bob", and '%(room)s', which will be replaced by the name of the room the
message(s) have been sent to, e.g. "My super room". In addition, emails related to account administration will
can use the '%(server_name)s' placeholder, which will be replaced by the value of the
`server_name` setting in your Synapse configuration.

Here is a list of subjects for notification emails that can be set:
* `message_from_person_in_room`: Subject to use to notify about one message from one or more user(s) in a
room which has a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..."
* `message_from_person`: Subject to use to notify about one message from one or more user(s) in a
room which doesn't have a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s..."
* `messages_from_person`: Subject to use to notify about multiple messages from one or more users in
a room which doesn't have a name. Defaults to "[%(app)s] You have messages on %(app)s from %(person)s..."
* `messages_in_room`: Subject to use to notify about multiple messages in a room which has a
name. Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room..."
* `messages_in_room_and_others`: Subject to use to notify about multiple messages in multiple rooms.
Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room and others..."
* `messages_from_person_and_others`: Subject to use to notify about multiple messages from multiple persons in
multiple rooms. This is similar to the setting above except it's used when
the room in which the notification was triggered has no name. Defaults to
"[%(app)s] You have messages on %(app)s from %(person)s and others..."
* `invite_from_person_to_room`: Subject to use to notify about an invite to a room which has a name.
Defaults to "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..."
* `invite_from_person`: Subject to use to notify about an invite to a room which doesn't have a
name. Defaults to "[%(app)s] %(person)s has invited you to chat on %(app)s..."
* `password_reset`: Subject to use when sending a password reset email. Defaults to "[%(server_name)s] Password reset"
* `email_validation`: Subject to use when sending a verification email to assert an address's
ownership. Defaults to "[%(server_name)s] Validate your email"

Example configuration:
```yaml
email:
smtp_host: mail.server
smtp_port: 587
smtp_user: "exampleusername"
smtp_pass: "examplepassword"
force_tls: true
require_transport_security: true
enable_tls: false
notif_from: "Your Friendly %(app)s homeserver <noreply@example.com>"
app_name: my_branded_matrix_server
enable_notifs: true
notif_for_new_users: false
client_base_url: "http://localhost/riot"
validation_token_lifetime: 15m
invite_client_location: https://app.element.io
subjects:
message_from_person_in_room: "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..."
message_from_person: "[%(app)s] You have a message on %(app)s from %(person)s..."
messages_from_person: "[%(app)s] You have messages on %(app)s from %(person)s..."
messages_in_room: "[%(app)s] You have messages on %(app)s in the %(room)s room..."
messages_in_room_and_others: "[%(app)s] You have messages on %(app)s in the %(room)s room and others..."
messages_from_person_and_others: "[%(app)s] You have messages on %(app)s from %(person)s and others..."
invite_from_person_to_room: "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..."
invite_from_person: "[%(app)s] %(person)s has invited you to chat on %(app)s..."
password_reset: "[%(server_name)s] Password reset"
email_validation: "[%(server_name)s] Validate your email"
```
---
## Push
Configuration settings related to push notifications

Expand Down

0 comments on commit 2fb4071

Please sign in to comment.