User Guide: Managing Phabricator Email

Phabricator User Documentation (Application User Guides)

How to effectively manage Phabricator email notifications.

Overview

Phabricator 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 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.

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

Mail Headers

Phabricator 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 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.