Determine recipients of notification emails

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Many factors determine the recipients of an email notification when an event matches a subscription. If you're unaware, these factors can result in your inbox receiving too many or too few emails. Learn about how the type of subscription, its delivery settings, delivery preferences, and other factors determine the set of recipients.

Custom personal subscriptions

With custom personal subscriptions, emails are delivered to the Preferred email address of the user who owns the subscription, or to the email address configured on the subscription.

Preferred email address on a personal subscription (default)

Custom email address on a personal subscription

Delivery settings for teams and groups

Delivery settings control the default delivery behavior when the team or group is the recipient of a notification. Each subscription is configured with a delivery option that looks at the recipients' delivery settings.

You can manage subscriptions and delivery settings at the team level or organization level.

Organization-level settings

In Organization settings, select Global notifications > Subscribers > <Team> > Delivery settings.

Select from the following settings:

• Deliver to email address: Notifications are delivered to a specific email address.
• Deliver to individual members: Notifications are delivered to each member of the group or team. This setting is usually the default option. For more information, see Team expansion.
• Do not deliver: Notifications aren't delivered by default.

If you don't explicitly choose delivery settings for a team or group, the settings are determined from the delivery options set at the organization level. The default value is either Deliver to individual members or Do not deliver.

Custom team and group subscription recipients

The recipients for a custom team or group subscription are determined by the subscription. For certain delivery options, the default delivery setting for the team is used to determine the set of recipients.

The following delivery options are available for a group or team subscription:

• Members of team by role: Recipients are members of the team or group that have one of the selected roles (for example, Work Item Assignee).
• Team preference: Recipients are determined by the delivery setting of the team or group (Do not deliver, Preferred email address, or Members of team).
• Custom email address: Recipient is the specified email address.
• Members of team: Recipients are all members of the team or group, except members who are opted out of the subscription.
• SOAP: Similar to API Management, recipients are specified by adding their email addresses (subscribing) to the SOAP service.

Member of team by role

The email recipient list is determined by members that had a role in the event. For example, the user assigned the work item has the role Assigned to (new) while the identity that was assigned the work item has the role Assigned to (previous). The full list of roles for each event type is shown in the supported event types.

The Skip initiator option, which appears for most event types, controls whether the user or group that started the event should be explicitly excluded from the set of recipients. In general, this option should be enabled (On) because most users don't want to receive a notification about their own actions.

Team preference

The delivery option is taken from the team's delivery setting and can be one of the following options:

• Deliver to email address: The email is delivered to the team's preferred email address.
• Deliver to individual members: The process is described in the following section, Members of team_.
• Do not deliver: No email is delivered.

The team's delivery setting value is displayed after the Address label and can't be changed.

Custom email address

The notifications are sent to multiple custom email addresses, which are separated by semicolons.

Members of team

The team or group membership is expanded to determine the email recipients. In the simple case, a team or group expands to a list of individuals and each user is included on the To: line of the resulting email. However, the results of the expansion can be complicated and are explained in more detail in the team and group expansion section.

Default subscription recipients

The delivery option for a default subscription is usually one or more roles. You can't change these values. The roles and the Skip initiator option vary depending on the event type. For more information and a list of roles available for each event type, see Supported event types.

Team and group expansion for email recipients

When a team or group receives a notification, and either the subscription or delivery preference is for all members, the team must be "expanded" to determine the actual set of email recipients. This process is potentially recursive, and starts by looking at the team's direct members.

Only members who are not opted out of the subscription are considered for the final recipient list. Any member who's an individual user is added to the recipient list.

For project-scoped events, Azure DevOps checks whether the team or group has the View project-level information permission. If you set this permission to Deny, Azure DevOps filters the team or group from the recipient list and doesn't evaluate its nested members. Resource-specific permissions don't replace this project-level notification check. For example, after View project-level information is set to Allow, a group can receive a Build completes notification even if View builds is set to Deny for the specific pipeline.

Only Azure DevOps Services groups remain. For each group, the group's delivery preferences are examined:

• Do not deliver: No further evaluation is done on this group and the next member group is evaluated.
• Deliver to email address: The email address is added to the final recipient list.
• Deliver to individual members: The group is expanded (like its parent group) and the same rules for evaluating its members are followed.

Scenarios

This section explores several example scenarios. The following examples use symbols to denote the types of team members:

• I: Individual user
• T: Nested team or group
• E: Mail-enabled Microsoft Entra group

Team member enables "Do not deliver" setting

Example team members:

• The primary team has three members: users I1 and I2, and nested team T1.
• Team T1 has the Do not deliver setting enabled.

Only users I1 and I2 receive the notification messages at their preferred contact email address. Members of the nested team T1 aren't notified.

Team member enables "Deliver to individual members" setting

Example team members:

• The primary team has three members: users I1 and I2, and nested team T1.
• Team T1 has two member users, I2 and I3.
• User I2 is a member of both the primary team and team T1.
• Team T1 has the Deliver to individual members setting enabled.

Team T1 is expanded to identify its members. I1, I2, and I3 all receive the notification messages at their preferred contact email address.

Team contains nested group

Example team members:

• The primary team has three members: users I1 and I2, and nested team T1.
• Team T1 has three members: users I2 and I3, and nested team T2.
• Team T2 has two member users, I4 and I5.
• User I2 is a member of both the primary team and team T1.
• Team T1 has the Do not deliver setting enabled.
• Team T2 has the Deliver to individual members setting enabled.

Because team T1 has the Do not deliver setting enabled, the team isn't expanded to identify its members. Although team T2 has the Deliver to individual members setting enabled, team T2 is nested within team T1. The Do not deliver delivery preferences for T1 takes precedence over settings made by its members. Only users I1 and I2 receive the notification messages at their preferred contact email address.

Mail-enabled Microsoft Entra group as recipient

Azure DevOps handles a mail-enabled Microsoft Entra group differently depending on whether the notification subscription addresses the group directly or reaches it through an Azure DevOps team or group:

• Direct recipient: When the subscription is configured directly for the mail-enabled Microsoft Entra group, Azure DevOps sends the notification to the group's email address. Azure DevOps doesn't expand the group or evaluate each member's Azure DevOps permissions.
• Nested recipient: When the mail-enabled Microsoft Entra group is a member of an Azure DevOps team or group, Azure DevOps first evaluates the parent team's or group's delivery settings and View project-level information permission. If this permission is set to Deny for the parent, Azure DevOps filters the parent and doesn't add the nested Microsoft Entra group to the recipient list.

The following cases show the expected results for a Build completes notification when the mail-enabled Microsoft Entra group is also a member of the Azure DevOps group:

To ensure delivery, use one of the following configurations:

• Keep the Microsoft Entra group nested and set View project-level information to Allow for the parent Azure DevOps team or group.
• Configure the mail-enabled Microsoft Entra group as the direct recipient when Azure DevOps should send the notification directly to the group address.

Before you configure direct delivery, confirm that all members of the mail-enabled Microsoft Entra group are authorized to receive the event details. Azure DevOps sends the message to the group address without validating each member's access to the Azure DevOps resources.

Related content

• Manage notifications for a team, group, global organization
• Default and supported notifications
• Permissions, security groups, and service accounts reference