Mercurial > kallithea

comparison docs/usage/e-mail.rst @ 5366:ce72c36f7a0e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
e-mail: add documentation about configuration settings Document e-mail related configuration settings in the documentation (overview) and the .ini file itself (technical details and example settings).
author Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
date Thu, 16 Jul 2015 17:40:35 +0200
parents
children
comparison
equal deleted inserted replaced
5365:ef64905223f5 5366:ce72c36f7a0e
1 .. _email:
2
3 ===============
4 E-mail settings
5 ===============
6
7 The Kallithea configuration file has several e-mail related settings. When
8 these contain correct values, Kallithea will send e-mail in the situations
9 described below. If the e-mail configuration is not correct so that e-mails
10 cannot be sent, all mails will show up in the log output.
11
12 Before any e-mail can be sent, an SMTP server has to be configured using the
13 configuration file setting ``smtp_server``. If required for that server, specify
14 a username (``smtp_username``) and password (``smtp_password``), a non-standard
15 port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``)
16 and/or specific authentication parameters (``smtp_auth``).
17
18 Application e-mails
19 -------------------
20
21 Kallithea sends an e-mail to `users` on several occasions:
22
23 - when comments are given on one of their changesets
24 - when comments are given on changesets they are reviewer on or on which they
25 commented regardless
26 - when they are invited as reviewer in pull requests
27 - when they request a password reset
28
29 Kallithea sends an e-mail to all `administrators` upon new account registration.
30 Administrators are users with the ``Admin`` flag set in the ``Admin->Users``
31 section.
32
33 When Kallithea wants to send an e-mail but due to an error cannot correctly
34 determine the intended recipients, the administrators and the addresses
35 specified in ``email_to`` in the configuration file are used as fallback.
36
37 Recipients will see these e-mails originating from the sender specified in the
38 ``app_email_from`` setting in the configuration file. This setting can either
39 contain only an e-mail address, like `kallithea-noreply@example.com`, or both
40 a name and an address in the following format: `Kallithea
41 <kallithea-noreply@example.com>`. The subject of these e-mails can
42 optionally be prefixed with the value of ``email_prefix`` in the configuration
43 file.
44
45 Error e-mails
46 -------------
47
48 When an exception occurs in Kallithea -- and unless interactive debugging is
49 enabled using ``set debug = true`` in the ``[app:main]`` section of the
50 configuration file -- an e-mail with exception details is sent by WebError_'s
51 ``ErrorMiddleware`` to the addresses specified in ``email_to`` in the
52 configuration file.
53
54 Recipients will see these e-mails originating from the sender specified in the
55 ``error_email_from`` setting in the configuration file. This setting can either
56 contain only an e-mail address, like `kallithea-noreply@example.com`, or both
57 a name and an address in the following format: `Kallithea Errors
58 <kallithea-noreply@example.com>`.
59
60 *Note:* The WebError_ package does not respect ``smtp_port`` and assumes the
61 standard SMTP port (25). If you have a remote SMTP server with a different port,
62 you could set up a local forwarding SMTP server on port 25.
63
64 References
65 ----------
66 - `Error Middleware (Pylons documentation) <http://pylons-webframework.readthedocs.org/en/latest/debugging.html#error-middleware>`_
67 - `ErrorHandler (Pylons modules documentation) <http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler>`_
68
69 .. _WebError: https://pypi.python.org/pypi/WebError