Email Notifications and Replies

How does Monorail send email messages?

Monorail sends individual email messages to each user who should be notified of an issue change. For example, if users A, B and C are all CC’d on an issue, a new comment on that issue will trigger three separate email messages: one to each of the email addresses for users A, B, and C. Sending individual messages, rather than a single message with several addresses listed, allows Monorail to customize the content of each message for each user, avoid sending duplicate emails in many cases, and better manage email replies.

Who is notified when an issue changes?

When a new issue is created or a comment is posted to an issue, Monorail computes a set of users to notify for specific reasons. Those reasons cause the following users to be added to the set:

  • The issue owner, plus the previous owner if the owner field was edited

  • CC’d users, including any CC’d user added by filter rules or component definitions

  • Users who have starred the issue and are currently allowed to view the issue

  • Users named in user-type custom fields that are configured to trigger notifications

  • Users who have subscriptions with queries that match the new state of the issue

If any of those items are user groups that exist in Monorail, they are replaced by the list of members of the user group. If a given user is a member of two user groups in the set, the user themselves will only be in the set once.

The issue reporter is not automatically included in the set of users to notify. However, by default, a user stars an issue when they report it. So, the issue reporter is usually also a starrer unless they click to unstar the issue.

Monorail removes some users from the set:

  • The user who made the change, because they already know about the change.

  • Users who opted out of issue change notifications by unchecking some options on their user settings page (see below).

  • For any users with linked accounts, if both accounts would be notified, Monorail omits the child account.

  • Any banned or bouncing users.

Finally, Monorail adds in these email addresses:

  • Any also-notify addresses defined in matching filter rules

  • Any notify-all email address configured by the project owners

Monorail then sends email messages to each of those email addresses. Usually, those addresses correspond to the inboxes of individual users. However, some accounts have email addresses that post to mailing lists (not user groups that are sync’d to Monorail). For those messages, the mailing list software takes over to distribute the message to members of that mailing list and add it to the mailing list archive.

Who is notified when an issue's approval changes?

Some issues own approvals which have their own thread of comments and fields. Notifications for approval changes and comments behave differently from issue notifications.

Below, “feature team” will be used to mean users named in user-type custom fields that are configured to trigger notifications AND the issue owner. CC'd users are not notified for any approval changes.

The following are all possible changes someone could make to an approval and the users that would be added to the set of notification recipients as a result.

A new approval comment or approval field change will trigger notifications to:

  • The feature team
  • Approvers of the approval

An approval status change to:

  • ReviewRequested notifies approvers.
  • NeedInfo, NeedsReview, ReviewStarted, Approved, NotApproved, and NA notifies the feature team.

A change of approvers notifies all approvers including the ones being added and removed.

Like issues, the user who made the approval changes will not receive the resulting email.

Why did I get an email notification?

If you receive an email notification from Monorail, it is because of one of the reasons listed in the section above. Monorail personalizes each message by adding a footer that lists the reason or reasons why that message was sent to you. In Gmail, you may need to click a “...” icon near the bottom of the message to see this footer.

Why did I NOT get an email notification?

Please see the reasons listed above for why Monorail removes potential email recipients.

If Monorail previously sent an email to your address, and that email bounced, Monorail will flag your account as bouncing. This can happen if you are new to a team and a teammate CC’d your email address before your email account had been created. You can clear the bouncing flag by clicking a link on your user profile page.

If you use multiple accounts with Monorail, someone may have CC’d one of your other accounts.

How do I configure email notifications?

Users currently have two options to configure email notifications on their settings page:

  • If I am in the issue's owner or CC fields.

  • If I starred the issue.

You can access the settings page via the account menu.

How can I filter these emails?

The best way to filter emails is to look at the reasons listed in the footer. For example, if the email message contains the string “You are the owner of the issue”, then you might want to mark the message as important.

How to star an issue

Anyone can star an issue by clicking the star icon near the issue ID on the issue detail page, issue list page, or hotlist page. Starring an issue will subscribe you to email notifications for changes to that issue. The issue reporter stars the issue be default, but they can unstar it if they are no longer interested.

How to subscribe to an issue query

  1. Sign in and click your email address in the far upper right of the page to access your account menu.
  2. Choose Saved queries.
  3. Choose a name that describes what you are interested in.
  4. List the names of the projects where you want the subscription to apply.
  5. Type an issue query for issues in those projects that you are interested in.

If you choose the Notify immediately option, then when any issue that matches that query is updated, you will get an email notification. If you choose either to be notified or not notified, you can use any of your subscriptions in the issue query scope menu.

Why did I get a follow-up email notification?

When an issue has a date-type custom field set, and that field is configured to trigger notifications, and the specified date arrives while the issue is still open, then Monorail will automatically post a comment to the issue as a reminder. That comment triggers notification emails to the issue owner, CC’d users, and users who starred the issue.

On the settings page, there is an option to not send follow-up emails for issues that you have starred. However, follow-up emails are always sent to the issue owner and CC’d users.

How to reply to a notification email

Project owners may enable processing of replies in their project, but it is disabled by default. If it is enabled in your project, you will see that the footer of each email notification invites you to “Reply to this email to add a comment” or “Reply to this email to add a comment or make updates”. These lines will only appear on messages that are sent directly to you, not on messages sent to an also-notify or notify-all mailing list address.

When you see one of those footer lines, you can reply to the email from your email client. You should reply using the same email address that the notification was sent to, which normally happens automatically unless you forward your email from one account to another. And, you must keep the same email subject line. The text of your reply will become the content of a new comment on the issue. If your reply cannot be processed, you will get an email notification with an error message explaining what went wrong.

If the notification sent to you invited you to “make updates”, then you can include some lines at the top of your email message to update the state of the issue. Any text after the first line that does not parse as a command will be treated as the comment content. Quoted lines and signature lines are automatically stripped off. To help make sure nothing important is lost, project members may use the comment ... menu to view the original email message with nothing stripped off.

For example:

Status: Started
Pri: 2

I looked through the logs and found a possible root cause.  Lowering
priority because there is a clear work-around.


That reply will update the issue owner, status, and the issue priority. And, it will use the rest of the text as the comment body, except for “Cheers” which will be stripped.

Can I create a new issue via email?

Monorail does not currently allow for new issues to be created via email. Please use the issue entry page to create a new issue.