src/docs/user/userguide/mail_rules.diviner

   1 @title User Guide: Managing Phabricator Email
   2 @group userguide
   3
   4 How to effectively manage Phabricator email notifications.
   5
   6 Overview
   7 ========
   8
   9 Phabricator uses email as a major notification channel, but the amount of email
  10 it sends can seem overwhelming if you're working on an active team. This
  11 document discusses some strategies for managing email.
  12
  13 By far the best approach to managing mail is to **write mail rules** to
  14 categorize mail. Essentially all modern mail clients allow you to quickly
  15 write sophisticated rules to route, categorize, or delete email.
  16
  17 Reducing Email
  18 ==============
  19
  20 You can reduce the amount of email you receive by turning off some types of
  21 email in {nav Settings > Email Preferences}. For example, you can turn off email
  22 produced by your own actions (like when you comment on a revision), and some
  23 types of less-important notifications about events.
  24
  25 Mail Rules
  26 ==========
  27
  28 The best approach to managing mail is to write mail rules. Simply writing rules
  29 to move mail from Differential, Maniphest and Herald to separate folders will
  30 vastly simplify mail management.
  31
  32 Phabricator also adds mail headers (see below) which can allow you to write
  33 more sophisticated mail rules.
  34
  35 Mail Headers
  36 ============
  37
  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
  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
  46 Stamps and Gmail
  47 ================
  48
  49 If you use a client which can not perform header matching (like Gmail), you can
  50 change the {nav Settings > Email Format > Send Stamps} setting to include the
  51 stamps in the mail body and then match them with body rules.
  52
  53 When writing filter rules against mail stamps in Gmail, you should quote any
  54 filters you want to apply. For example, specify rules like this, with quotes:
  55
  56 > "author(@alice)"
  57
  58 Note that Gmail will ignore some symbols when matching mail against filtering
  59 rules, so you can get false positives if the body of the message includes text
  60 like `author alice` (the same words in the same order, without the special
  61 symbols).
  62
  63 You'll also get false positives if the message body includes the text of a
  64 mail stamp explicitly in a normal text field like a summary, description, or
  65 comment.
  66
  67 There's no way to avoid these false positives other than using a different
  68 client with support for more powerful filtering rules, but these false
  69 positives should normally be uncommon.