@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Briefly document mail stamps and remove obsolete header documentation
Summary: Fixes T10189. Ref T13053. We haven't sent these headers in a very long time. Briefly mention the new stamps header instead, although I expect to integrate stamp documentation into the UI in a more cohesive way in the future.
Test Plan: Read documentation.
Maniphest Tasks: T13053, T10189
Differential Revision: https://secure.phabricator.com/D19030
+20
-53
+1
-1
src/applications/metamta/storage/PhabricatorMetaMTAMail.php
+1
-1
src/applications/metamta/storage/PhabricatorMetaMTAMail.php
+19
-52
src/docs/user/userguide/mail_rules.diviner
+19
-52
src/docs/user/userguide/mail_rules.diviner
···
3
3
4
4
How to effectively manage Phabricator email notifications.
5
5
6
-
= Overview =
6
+
Overview
7
+
========
7
8
8
9
Phabricator uses email as a major notification channel, but the amount of email
9
10
it sends can seem overwhelming if you're working on an active team. This
···
13
14
categorize mail. Essentially all modern mail clients allow you to quickly
14
15
write sophisticated rules to route, categorize, or delete email.
15
16
16
-
= Reducing Email =
17
+
Reducing Email
18
+
==============
17
19
18
20
You can reduce the amount of email you receive by turning off some types of
19
21
email in {nav Settings > Email Preferences}. For example, you can turn off email
20
22
produced by your own actions (like when you comment on a revision), and some
21
23
types of less-important notifications about events.
22
24
23
-
= Mail Rules =
25
+
Mail Rules
26
+
==========
24
27
25
28
The best approach to managing mail is to write mail rules. Simply writing rules
26
29
to move mail from Differential, Maniphest and Herald to separate folders will
27
30
vastly simplify mail management.
28
31
29
-
Phabricator also sets a large number of headers (see below) which can allow you
30
-
to write more sophisticated mail rules.
31
-
32
-
= Mail Headers =
33
-
34
-
Phabricator sends a variety of mail headers that can be useful in crafting rules
35
-
to route and manage mail.
32
+
Phabricator also adds mail headers (see below) which can allow you to write
33
+
more sophisticated mail rules.
36
34
37
-
Headers in plural contain lists. A list containing two items, `1` and
38
-
`15` will generally be formatted like this:
35
+
Mail Headers
36
+
============
39
37
40
-
X-Header: <1>, <15>
38
+
Phabricator sends various information in mail headers that can be useful in
39
+
crafting rules to route and manage mail. To see a full list of headers, use
40
+
the "View Raw Message" feature in your mail client.
41
41
42
-
The intent is to allow you to write a rule which matches against "<1>". If you
43
-
just match against "1", you'll incorrectly match "15", but matching "<1>" will
44
-
correctly match only "<1>".
42
+
The most useful header for routing is generally `X-Phabricator-Stamps`. This
43
+
is a list of attributes which describe the object the mail is about and the
44
+
actions which the mail informs you about.
45
45
46
-
Some other headers use a single value but can be presented multiple times.
47
-
It is to support e-mail clients which are not able to create rules using regular
48
-
expressions or wildcards (namely Outlook).
49
-
50
-
The headers Phabricator adds to mail are:
51
-
52
-
- `X-Phabricator-Sent-This-Message`: this is attached to all mail
53
-
Phabricator sends. You can use it to differentiate between email from
54
-
Phabricator and replies/forwards of Phabricator mail from human beings.
55
-
- `X-Phabricator-To`: this is attached to all mail Phabricator sends.
56
-
It shows the PHIDs of the original "To" line, before any mutation
57
-
by the mailer configuration.
58
-
- `X-Phabricator-Cc`: this is attached to all mail Phabricator sends.
59
-
It shows the PHIDs of the original "Cc" line, before any mutation by the
60
-
mailer configuration.
61
-
- `X-Differential-Author`: this is attached to Differential mail and shows
62
-
the revision's author. You can use it to filter mail about your revisions
63
-
(or other users' revisions).
64
-
- `X-Differential-Reviewer`: this is attached to Differential mail and
65
-
shows the reviewers. You can use it to filter mail about revisions you
66
-
are reviewing, versus revisions you are explicitly CC'd on or CC'd as
67
-
a result of Herald rules.
68
-
- `X-Differential-Reviewers`: list version of the previous.
69
-
- `X-Differential-CC`: this is attached to Differential mail and shows
70
-
the CCs on the revision.
71
-
- `X-Differential-CCs`: list version of the previous.
72
-
- `X-Differential-Explicit-CC`: this is attached to Differential mail and
73
-
shows the explicit CCs on the revision (those that were added by humans,
74
-
not by Herald).
75
-
- `X-Differential-Explicit-CCs`: list version of the previous.
76
-
- `X-Phabricator-Mail-Tags`: this is attached to some mail and has
77
-
a list of descriptors about the mail. (This is fairly new and subject
78
-
to some change.)
79
-
- `X-Herald-Rules`: this is attached to some mail and shows Herald rule
80
-
IDs which have triggered for the object. You can use this to sort or
81
-
categorize mail that has triggered specific rules.
46
+
If you use a client which can not perform header matching (like Gmail), you can
47
+
change the {nav Settings > Email Format > Send Stamps} setting to include the
48
+
stamps in the mail body and then match them with body rules.