Mercurial > kallithea
annotate docs/usage/email.rst @ 7835:41f780117963
helpers: fix bad handling of select values with length 2 - 'hg' showed up as 'g' in repo types list
Strings with length 2 are not tuples ...
author | Mads Kiilerich <mads@kiilerich.com> |
---|---|
date | Sun, 18 Aug 2019 15:52:33 +0200 |
parents | 19af3fef3b34 |
children | 61bd04b90f58 |
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 |
6574
e223c36e5b68
docs: update email documentation for TurboGears2
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6313
diff
changeset
|
79 configuration file -- an email with exception details is sent by backlash_ |
e223c36e5b68
docs: update email documentation for TurboGears2
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6313
diff
changeset
|
80 to the addresses specified in ``email_to`` in the configuration file. |
5366
ce72c36f7a0e
e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
81 |
5412
2079e864ce51
spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents:
5366
diff
changeset
|
82 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
|
83 ``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
|
84 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
|
85 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
|
86 <kallithea-noreply@example.com>`. |
ce72c36f7a0e
e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
87 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5426
diff
changeset
|
88 |
5366
ce72c36f7a0e
e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
89 References |
ce72c36f7a0e
e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
90 ---------- |
5413
22a3fa3c4254
docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
91 |
5366
ce72c36f7a0e
e-mail: add documentation about configuration settings
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
diff
changeset
|
92 - `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
|
93 - `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
|
94 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5426
diff
changeset
|
95 |
6749
84d8cff41282
docs: fix broken references
Andrew Shadura <andrew@shadura.me>
parents:
6575
diff
changeset
|
96 .. _backlash: https://github.com/TurboGears/backlash |