Mercurial > kallithea

annotate docs/usage/email.rst @ 8395:482e163caccd i18n

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge closed stable-i18n Everything has already landed.
author Mads Kiilerich <mads@kiilerich.com>
date Mon, 04 May 2020 19:24:04 +0200
parents 19af3fef3b34
children 61bd04b90f58
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
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