phorge / src / docs / user / userguide / mail_rules.diviner

@title User Guide: Managing Phorge Email
@group userguide

How to effectively manage Phorge email notifications.

Overview
========

Phorge uses email as a major notification channel, but the amount of email
it sends can seem overwhelming if you're working on an active team. This
document discusses some strategies for managing email.

By far the best approach to managing mail is to **write mail rules** to
categorize mail. Essentially all modern mail clients allow you to quickly
write sophisticated rules to route, categorize, or delete email.

Reducing Email
==============

You can reduce the amount of email you receive by turning off some types of
email in {nav Settings > Email Preferences}. For example, you can turn off email
produced by your own actions (like when you comment on a revision), and some
types of less-important notifications about events.

Mail Rules
==========

The best approach to managing mail is to write mail rules. Simply writing rules
to move mail from Differential, Maniphest and Herald to separate folders will
vastly simplify mail management.

Phorge also adds mail headers (see below) which can allow you to write
more sophisticated mail rules.

Mail Headers
============

Phorge sends various information in mail headers that can be useful in
crafting rules to route and manage mail. To see a full list of headers, use
the "View Raw Message" feature in your mail client.

The most useful header for routing is generally `X-Phabricator-Stamps`. This
is a list of attributes which describe the object the mail is about and the
actions which the mail informs you about.

Stamps and Gmail
================

If you use a client which can not perform header matching (like Gmail), you can
change the {nav Settings > Email Format > Send Stamps} setting to include the
stamps in the mail body and then match them with body rules.

When writing filter rules against mail stamps in Gmail, you should quote any
filters you want to apply. For example, specify rules like this, with quotes:

> "author(@alice)"

Note that Gmail will ignore some symbols when matching mail against filtering
rules, so you can get false positives if the body of the message includes text
like `author alice` (the same words in the same order, without the special
symbols).

You'll also get false positives if the message body includes the text of a
mail stamp explicitly in a normal text field like a summary, description, or
comment.

There's no way to avoid these false positives other than using a different
client with support for more powerful filtering rules, but these false
positives should normally be uncommon.