Phabricator/Help/Managing mail

Phabricator can send you notification emails. How many it sends by default depends on what products and teams you work with (some projects use more steps and actions to manage workflows, than others), and how long you've been active in the community (over time you may accumulate a lot of tasks that you're indirectly subscribed to or are otherwise watching).

This page helps you tune your notifications based on your role and interest, to reduce noise and help you be more productive. Feel free to improve this page with your own ideas.

Manage notifications

Folder

By default notifications arrive in your email Inbox. This might make sense for you, if you actively follow the Inbox Zero practice and are able to configure your Phabricator account such that you only get a few important notifications by email. Otherwise, you'll probably benefit from letting these go into a separate folder (or "channel") that you can process once a day, reserving your Inbox for more urgent matters.

See Gmail#Create filter for web notifications for an example of how to do this.

Threading

By default, subject lines of Phabricator emails contain the current status of a task. This means when a task is closed, for example, it will essentially start a new thread with the subject line mentioning "Closed: T123: Some task". This might be handy if the status information is what you are mainly interested in as it would allow you to scan the Phabricator email folder without even opening most email threads.

If you prefer notifications to remain in a single thread, then disable this "Vary Subjects" feature. In the Phabricator settings, on the Email Format page, choose:

Vary Subjects: Disable Vary Subjects.

Reduce notifications

Phabricator lets you mirror all activity from a task in a single thread within your email application. This means you'll always have the context of what happened before, which includes a copy of your own actions. This also means you can use your email application to search through all task activity that you've received in the past. This is especially useful in combination with the ability to reply by email, as well as various Phabricator Mail commands you can issue via email.

A more common model is to use email only to be notified of something, and primarily use Phabricator itself for searching, reading context, making changes, and replying to tasks. In that case you'll want to reduce the notifications.

To perform silent actions that prevent sending notifications to other people, check Phabricator/Help#Batch edits.

Ignore your own actions

On the Email Delivery page in your Phabricator settings, you may disable "Self Actions". This means Phabricator will not email you about your own actions.

Ignore metadata changes

On the Email Preferences page in your Phabricator settings, you can control whether changes to metadata will notify you. For example, you can:

Ignore task owner changes.
Ignore task priority changes.
Ignore subscriber list changes.
Ignore project tag changes.
Ignore subtask status changes.
Ignore workboard column changes.
Ignore task status changes.
Ignore comments.

For team members (e.g. as software engineer), it might make sense to ignore all of these except "status changes" and "comments". The idea being that other activity is not likely to need a "response" from you. Which workboards a task is on is something you'll deal with as part of triaging the workboard from its own interface, and other metadata changes will be there for you to read up on once you are on the task for a different reason. (This configuration is recommended by @Quiddity and @Krinkle).

There is a How to Manage Phabricator Email guide with more information.

Ignore tasks you're not subscribed to

You may be receiving notifications of tasks that you're not subscribed to. If this happens to you, you have likely "watched" one of the associated projects. Watching a project means you receive notifications as if you're subscribed to each of the project's tasks.

Check the List of projects you are watching. To stop watching a project, click on its name first. If you arrived on on the project's workboard, then click on its name in the left-hand sidebar (usually the first item) to arrive on its profile page. Click "Unwatch Project".

Another possibility may be that you are a "Member" of a project that was subscribed as a group to a task. This feature is not commonly in use at Wikimedia, but if it applies to you, you can choose to opt-out of group mail by choosing "Disable Mail" on the project's "Members" page. See the List of projects you have joined.

Mute a task

You can disable future notifications for an individual task without publicly unsubscribing. From the task page, choose the "Mute Notifications" option.

The Mute Notifications option is also useful if you are watching a project and want to opt-out from notifications about some of its tasks (as there would not be an unsubscribe option).

Other

Filter notifications

In addition to reducing notifications sent by Phabricator, you can apply additional filters within your email application.

Phabricator mail notifications include message header fields (such as X-Phabricator-Stamps for most metadata, X-Phabricator-Projects for project tags associated to the task, X-Phabricator-Mail-Tags for actions performed) that common email clients (except for the Gmail web interface) allow filtering on.
- If you use the Gmail web interface and want to inspect the header fields of an email, click Show original in the message dropdown menu.
If you use the Gmail web interface and want to filter on header fields, set Send Stamps to Mail Headers and Body under Email Format. This will duplicate the content of the header fields to the bottom of the message body. Gmail allows filtering on content in the message body. Steps and screenshots are available in phab:T150766#3977670.
Depending on your needs, you could filter on X-Phabricator-Stamps values such as
- actor(@username) - who triggered the notification
- author(@username) - author of the task
- tag(#someproject) - but not for subprojects as only an internal PHID is used
- task-owner(@username) - task assignee
- task-priority(number) - available numbers: 100 = unbreak now; 90 = needs triage; 80 = high; 50 = medium; 25 = low; 10 = lowest
- task-status(status) - status such as "open"
- task-unassigned() - when no task assignee is set
You can also distinguish when you were explicitly mentioned in a comment by filtering X-Phabricator-Stamps on mention(@yourusername).
If you need to specifically filter on subprojects and do not use the Gmail web interface, consider filtering on the X-Phabricator-Projects instead of X-Phabricator-Mail-Stamps

Alternative: Web notifications

If you strictly only follow tasks and projects that you regularly want to see all updates about (for example by using personal flags for "less important" tasks that don't require regular awareness), you could change numerous dropdowns in your email preferences under "Maniphest Tasks" from "Email" to "Notify" and then check your latest unread web notifications.

To receive an additional email only when being explicitly mentioned in a task comment, in parallel to using web notifications only, set up a personal Herald rule (more info) with the condition Comment content | contains | YourPhabUserName and the action Send me an email.

Disabling email notifications

You can completely disable email notifications under phab:settings/panel/emaildelivery/.