Mercurial > kallithea
annotate docs/usage/email.rst @ 6453:ebe7d95f698b
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 |
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 |