[Summary view] [Print] [Text view]

   1  @title User Guide: Managing Phabricator Email
   2  @group userguide
   3  
   4  How to effectively manage Phabricator email notifications.
   5  
   6  = Overview =
   7  
   8  Phabricator uses email as a major notification channel, but the amount of email
   9  it sends can seem overwhelming if you're working on an active team. This
  10  document discusses some strategies for managing email.
  11  
  12  By far the best approach to managing mail is to **write mail rules** to
  13  categorize mail. Essentially all modern mail clients allow you to quickly
  14  write sophisticated rules to route, categorize, or delete email.
  15  
  16  = Reducing Email =
  17  
  18  You can reduce the amount of email you receive by turning off some types of
  19  email in {nav Settings > Email Preferences}. For example, you can turn off email
  20  produced by your own actions (like when you comment on a revision), and some
  21  types of less-important notifications about events.
  22  
  23  = Mail Rules =
  24  
  25  The best approach to managing mail is to write mail rules. Simply writing rules
  26  to move mail from Differential, Maniphest and Herald to separate folders will
  27  vastly simplify mail management.
  28  
  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.
  36  
  37  Headers in plural contain lists. A list containing two items, ##1## and
  38  `15` will generally be formatted like this:
  39  
  40    X-Header: <1>, <15>
  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>".
  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.