## E-mail settings                                                            ##

##                                                                            ##

## Refer to the documentation ("E-mail settings") for more details.           ##

##                                                                            ##

## It is recommended to use a valid sender address that passes access         ##

## validation and spam filtering in mail servers.                             ##

## 'From' header for application e-mails. You can optionally add a name.

## Default:

## Examples:

## Subject prefix for application e-mails.

## A space between this prefix and the real subject is automatically added.

## Default:

## Example:

## Recipients for error e-mails and fallback recipients of application mails.

## Multiple addresses can be specified, space-separated.

## Only addresses are allowed, do not add any name part.

## Default:

#email_to =

## Examples:

## 'From' header for error e-mails. You can optionally add a name.

## Default:

## Examples:

## SMTP server settings

## Only smtp_server is mandatory. All other settings take the specified default

## values.

## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).

## If empty, use any of the authentication parameters supported by the server.

   usage/e-mail

.. _email:

===============

E-mail settings

===============

The Kallithea configuration file has several e-mail related settings. When

these contain correct values, Kallithea will send e-mail in the situations

described below. If the e-mail configuration is not correct so that e-mails

cannot be sent, all mails will show up in the log output.

Before any e-mail can be sent, an SMTP server has to be configured using the

configuration file setting ``smtp_server``. If required for that server, specify

a username (``smtp_username``) and password (``smtp_password``), a non-standard

port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``)

and/or specific authentication parameters (``smtp_auth``).

Application e-mails

-------------------

Kallithea sends an e-mail to `users` on several occasions:

- when comments are given on one of their changesets

- when comments are given on changesets they are reviewer on or on which they

  commented regardless

- when they are invited as reviewer in pull requests

- when they request a password reset

Kallithea sends an e-mail to all `administrators` upon new account registration.

Administrators are users with the ``Admin`` flag set in the ``Admin->Users``

section.

When Kallithea wants to send an e-mail but due to an error cannot correctly

determine the intended recipients, the administrators and the addresses

specified in ``email_to`` in the configuration file are used as fallback.

Recipients will see these e-mails originating from the sender specified in the

``app_email_from`` setting in the configuration file. This setting can either

contain only an e-mail address, like `kallithea-noreply@example.com`, or both

a name and an address in the following format: `Kallithea

<kallithea-noreply@example.com>`. The subject of these e-mails can

optionally be prefixed with the value of ``email_prefix`` in the configuration

file.

Error e-mails

-------------

When an exception occurs in Kallithea -- and unless interactive debugging is

enabled using ``set debug = true`` in the ``[app:main]`` section of the

configuration file -- an e-mail with exception details is sent by WebError_'s

``ErrorMiddleware`` to the addresses specified in ``email_to`` in the

configuration file.

Recipients will see these e-mails originating from the sender specified in the

``error_email_from`` setting in the configuration file. This setting can either

contain only an e-mail address, like `kallithea-noreply@example.com`, or both

a name and an address in the following format: `Kallithea Errors

<kallithea-noreply@example.com>`.

*Note:* The WebError_ package does not respect ``smtp_port`` and assumes the

standard SMTP port (25). If you have a remote SMTP server with a different port,

you could set up a local forwarding SMTP server on port 25.

References

----------

- `Error Middleware (Pylons documentation) <http://pylons-webframework.readthedocs.org/en/latest/debugging.html#error-middleware>`_

- `ErrorHandler (Pylons modules documentation) <http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler>`_

.. _WebError: https://pypi.python.org/pypi/WebError

<%text>## E-mail settings                                                            ##</%text>

<%text>##                                                                            ##</%text>

<%text>## Refer to the documentation ("E-mail settings") for more details.           ##</%text>

<%text>##                                                                            ##</%text>

<%text>## It is recommended to use a valid sender address that passes access         ##</%text>

<%text>## validation and spam filtering in mail servers.                             ##</%text>

<%text>## 'From' header for application e-mails. You can optionally add a name.</%text>

<%text>## Default:</%text>

<%text>## Examples:</%text>

<%text>## Subject prefix for application e-mails.</%text>

<%text>## A space between this prefix and the real subject is automatically added.</%text>

<%text>## Default:</%text>

<%text>## Example:</%text>

<%text>## Recipients for error e-mails and fallback recipients of application mails.</%text>

<%text>## Multiple addresses can be specified, space-separated.</%text>

<%text>## Only addresses are allowed, do not add any name part.</%text>

<%text>## Default:</%text>

#email_to =

<%text>## Examples:</%text>

<%text>## 'From' header for error e-mails. You can optionally add a name.</%text>

<%text>## Default:</%text>

<%text>## Examples:</%text>

<%text>## SMTP server settings</%text>

<%text>## Only smtp_server is mandatory. All other settings take the specified default</%text>

<%text>## values.</%text>

<%text>## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).</%text>

<%text>## If empty, use any of the authentication parameters supported by the server.</%text>

## E-mail settings                                                            ##

##                                                                            ##

## Refer to the documentation ("E-mail settings") for more details.           ##

##                                                                            ##

## It is recommended to use a valid sender address that passes access         ##

## validation and spam filtering in mail servers.                             ##

## 'From' header for application e-mails. You can optionally add a name.

## Default:

## Examples:

## Subject prefix for application e-mails.

## A space between this prefix and the real subject is automatically added.

## Default:

## Example:

## Recipients for error e-mails and fallback recipients of application mails.

## Multiple addresses can be specified, space-separated.

## Only addresses are allowed, do not add any name part.

## Default:

#email_to =

## Examples:

## 'From' header for error e-mails. You can optionally add a name.

## Default:

## Examples:

## SMTP server settings

## Only smtp_server is mandatory. All other settings take the specified default

## values.

## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).

## If empty, use any of the authentication parameters supported by the server.

## E-mail settings                                                            ##

##                                                                            ##

## Refer to the documentation ("E-mail settings") for more details.           ##

##                                                                            ##

## It is recommended to use a valid sender address that passes access         ##

## validation and spam filtering in mail servers.                             ##

## 'From' header for application e-mails. You can optionally add a name.

## Default:

## Examples:

## Subject prefix for application e-mails.

## A space between this prefix and the real subject is automatically added.

## Default:

## Example:

## Recipients for error e-mails and fallback recipients of application mails.

## Multiple addresses can be specified, space-separated.

## Only addresses are allowed, do not add any name part.

## Default:

#email_to =

## Examples:

## 'From' header for error e-mails. You can optionally add a name.

## Default:

## Examples:

## SMTP server settings

## Only smtp_server is mandatory. All other settings take the specified default

## values.

## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).

## If empty, use any of the authentication parameters supported by the server.