Mercurial > kallithea

annotate docs/usage/email.rst @ 6453:ebe7d95f698b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
auth: simplify the double invoked auth classes used for permission checking Also avoid storing request state in the Has Permission instances. The instances er temporary and only used once and there is thus not real problem, but it is simpler and cleaner this way.
author Mads Kiilerich <mads@kiilerich.com>
date Sun, 22 Jan 2017 01:16:52 +0100
parents 6b865fcfed20
children e223c36e5b68
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
1 .. _email:
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
2
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
3 ==============
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
4 Email settings
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
5 ==============
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
6
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
7 The Kallithea configuration file has several email related settings. When
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
8 these contain correct values, Kallithea will send email in the situations
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
9 described below. If the email configuration is not correct so that emails
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
10 cannot be sent, all mails will show up in the log output.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
11
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
12 Before any email can be sent, an SMTP server has to be configured using the
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
13 configuration file setting ``smtp_server``. If required for that server, specify
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
14 a username (``smtp_username``) and password (``smtp_password``), a non-standard
5881
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
15 port (``smtp_port``), whether to use "SSL" when connecting (``smtp_use_ssl``)
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
16 or use STARTTLS (``smtp_use_tls``), and/or specify special ESMTP "auth" features
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
17 (``smtp_auth``).
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
18
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
19 For example, for sending through gmail, use::
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
20
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
21 smtp_server = smtp.gmail.com
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
22 smtp_username = username
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
23 smtp_password = password
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
24 smtp_port = 465
a5ad2900985b docs: tweak email documentation - add gmail example
Mads Kiilerich <madski@unity3d.com>
parents: 5455
diff changeset
25 smtp_use_ssl = true
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
26
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
27
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
28 Application emails
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
29 ------------------
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
30
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
31 Kallithea sends an email to `users` on several occasions:
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
32
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
33 - when comments are given on one of their changesets
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
34 - when comments are given on changesets they are reviewer on or on which they
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
35 commented regardless
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
36 - when they are invited as reviewer in pull requests
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
37 - when they request a password reset
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
38
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
39 Kallithea sends an email to all `administrators` upon new account registration.
5426
66f1b9745905 docs: update menu navigation notation to use *Menu > Menu Item*
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
40 Administrators are users with the ``Admin`` flag set on the *Admin > Users*
66f1b9745905 docs: update menu navigation notation to use *Menu > Menu Item*
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
41 page.
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
42
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
43 When Kallithea wants to send an email but due to an error cannot correctly
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
44 determine the intended recipients, the administrators and the addresses
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
45 specified in ``email_to`` in the configuration file are used as fallback.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
46
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
47 Recipients will see these emails originating from the sender specified in the
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
48 ``app_email_from`` setting in the configuration file. This setting can either
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
49 contain only an email address, like `kallithea-noreply@example.com`, or both
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
50 a name and an address in the following format: `Kallithea
5455
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
51 <kallithea-noreply@example.com>`. However, if the email is sent due to an
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
52 action of a particular user, for example when a comment is given or a pull
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
53 request created, the name of that user will be combined with the email address
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
54 specified in ``app_email_from`` to form the sender (and any name part in that
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
55 configuration setting disregarded).
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
56
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
57 The subject of these emails can optionally be prefixed with the value of
c935bcaf7086 email: send comment and pullrequest mails with the author's name in 'From'
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5433
diff changeset
58 ``email_prefix`` in the configuration file.
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
59
6313
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
60 A Kallithea-specific header indicating the email type will be added to each
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
61 email. This header can be used for email filtering. The header is of the form:
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
62
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
63 X-Kallithea-Notification-Type: <type>
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
64
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
65 where ``<type>`` is one of:
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
66
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
67 - ``pull_request``: you are invited as reviewer in a pull request
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
68 - ``pull_request_comment``: a comment was given on a pull request
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
69 - ``cs_comment``: a comment was given on a changeset
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
70 - ``registration``: a new user was registered
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
71 - ``message``: another type of email
6b865fcfed20 docs: document X-Kallithea-Notification-Type header
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5881
diff changeset
72
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
73
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
74 Error emails
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
75 ------------
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
76
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
77 When an exception occurs in Kallithea -- and unless interactive debugging is
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
78 enabled using ``set debug = true`` in the ``[app:main]`` section of the
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
79 configuration file -- an email with exception details is sent by WebError_'s
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
80 ``ErrorMiddleware`` to the addresses specified in ``email_to`` in the
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
81 configuration file.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
82
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
83 Recipients will see these emails originating from the sender specified in the
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
84 ``error_email_from`` setting in the configuration file. This setting can either
5412
2079e864ce51 spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents: 5366
diff changeset
85 contain only an email address, like `kallithea-noreply@example.com`, or both
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
86 a name and an address in the following format: `Kallithea Errors
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
87 <kallithea-noreply@example.com>`.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
88
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
89 *Note:* The WebError_ package does not respect ``smtp_port`` and assumes the
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
90 standard SMTP port (25). If you have a remote SMTP server with a different port,
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
91 you could set up a local forwarding SMTP server on port 25.
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
92
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
93
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
94 References
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
95 ----------
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5412
diff changeset
96
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
97 - `Error Middleware (Pylons documentation) <http://pylons-webframework.readthedocs.org/en/latest/debugging.html#error-middleware>`_
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
98 - `ErrorHandler (Pylons modules documentation) <http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler>`_
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
99
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5426
diff changeset
100
5366
ce72c36f7a0e e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff changeset
101 .. _WebError: https://pypi.python.org/pypi/WebError