You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: How notification email recipients get determined
2
+
title: How Notification Email Recipients are Determined
3
3
titleSuffix: Azure DevOps
4
-
description: Describes how email recipients are determined for notifications and events in Azure DevOps.
4
+
description: Explore how email recipients are determined for notifications and events in Azure DevOps.
5
5
ms.subservice: azure-devops-notifications
6
6
ms.reviewer: wismythe
7
7
ms.author: chcomley
8
8
author: chcomley
9
-
ms.topic: conceptual
10
-
ms.date: 05/24/2022
9
+
ms.topic: concept-article
10
+
ms.date: 05/08/2025
11
11
monikerRange: '<= azure-devops'
12
+
#customer intent: As an Azure DevOps developer, I want to understand how email recipients are determined for notifications and events, so I can ensure users receive the correct messages.
@@ -20,138 +22,162 @@ Many factors determine the recipients of an email notification when an event mat
20
22
21
23
## Custom personal subscriptions
22
24
23
-
With custom personal subscription, emails get delivered to the _preferred email address_ of the user who owns the subscription, or to the email address configured on the subscription.
25
+
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)
28
30
29
-
> [!div class="mx-imgBorder"]
30
-
>
31
+
:::image type="content" source="media/email-personal-preferred.png" alt-text="Screenshot that shows how to configure the preferred email address for a personal subscription.":::
31
32
32
33
### Custom email address on a personal subscription
33
34
34
-
> [!div class="mx-imgBorder"]
35
-
>
35
+
:::image type="content" source="media/email-personal-other.png" alt-text="Screenshot that shows how to configure a custom email address for a personal subscription.":::
36
36
37
37
## Delivery settings for teams and groups
38
38
39
-
Delivery settings control the default delivery behavior when the team or group is the recipient of a notification. The subscription's configured with a delivery option that looks at the recipients' delivery settings.
39
+
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.
40
40
41
-
You can manage subscriptions and delivery settings at the team-level or organization-level.
41
+
You can manage subscriptions and delivery settings at the teamlevel or organizationlevel.
42
42
43
43
### Organization-level settings
44
44
45
-
::: moniker range="<=azure-devops"
46
-
47
-
1. In **Organization settings**, select **Global notifications** > **Subscribers** > your **Team** > **Delivery settings**.
48
-
49
-
:::image type="content" source="media/team-delivery-settings-new-ui.png" border="false" alt-text="Screenshot that shows how to configure team delivery settings for an organization." lightbox="media/team-delivery-settings-new-ui.png":::
52
48
53
-
2.Select from the following settings:
49
+
Select from the following settings:
54
50
55
-
***Deliver to email address:** notifications get delivered to a specific email address.
56
-
***Deliver to individual members:** notifications get delivered to each member of the group or team. This setting is usually the default option. For more information about the default option, see [Team expansion](#team-and-group-expansion-for-email-recipients).
57
-
***Do not deliver:** notifications aren't delivered by default.
51
+
-**Deliver to email address**: Notifications are delivered to a specific email address.
52
+
-**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](#team-and-group-expansion-for-email-recipients).
53
+
-**Do not deliver**: Notifications aren't delivered by default.
58
54
59
-
55
+
:::image type="content" source="media/email-team-delivery-settings.png" border="false" alt-text="Screenshot of the team Delivery settings dialog showing the 'Deliver to individual members' options selected.":::
60
56
61
-
If you don't explicitly choose delivery settings for a team or group, it gets determined from the [organization-level delivery setting](manage-team-group-global-organization-notifications.md). The default is either _Deliver to individual members_ or _Do not deliver_.
57
+
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](manage-team-group-global-organization-notifications.md). The default value is either **Deliver to individual members** or **Do not deliver**.
62
58
63
59
> [!TIP]
64
-
> The delivery settings dialog doesn't indicate whether the current selection was explicitly set or if it was inherited.
60
+
> The delivery settings dialog doesn't indicate whether the current selection is explicitly set or inherited.
65
61
66
62
## Custom team and group subscription recipients
67
63
68
-
The recipients for a custom team or group subscription get determined by the subscription. But, with certain delivery options, the team's default delivery setting is used to determine the set of recipients.
64
+
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.
:::image type="content" source="media/email-team-delivery-options-new.png" border="false" alt-text="Screenshot that shows how to configure the email delivery options for a custom team or group subscription.":::
73
67
74
68
The following delivery options are available for a group or team subscription:
75
69
76
-
***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)
77
-
***Team preference:** recipients are determined by the delivery setting of the team or group (_Do not deliver_, _preferred email address_, or _members of team_)
78
-
***Custom email address:** recipient is the specified email address
79
-
***Members of team:** recipients are all members of the team or group, except members who have opted out of the subscription.
80
-
***SOAP:** similar to API Management, recipients are specified by adding their email addresses (subscribing) to the SOAP service.
70
+
-**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).
71
+
-**Team preference**: Recipients are determined by the delivery setting of the team or group (**Do not deliver**, **Preferred email address**, or **Members of team**).
72
+
-**Custom email address**: Recipient is the specified email address.
73
+
-**Members of team**: Recipients are all members of the team or group, except members who are opted out of the subscription.
74
+
-**SOAP**: Similar to API Management, recipients are specified by adding their email addresses (subscribing) to the SOAP service.
81
75
82
76
> [!NOTE]
83
77
> The default delivery setting of each member is honored, including groups that are members of the team or group.
84
78
85
-
::: moniker-end
86
-
87
79
### Member of team by role
88
80
89
-
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](oob-supported-event-types.md).
81
+
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](oob-supported-event-types.md).
90
82
91
-
83
+
:::image type="content" source="media/email-team-delivery-option-role.png" border="false" alt-text="Screenshot that shows the email team delivery option role.":::
92
84
93
-
The option _Skip initiator_, 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 "on" since most users don't want to receive a notification about something they did.
85
+
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.
94
86
95
87
### Team preference
96
88
97
89
The delivery option is taken from the team's delivery setting and can be one of the following options:
98
90
99
-
***Deliver to email address:** The email is delivered to the team's preferred email address.
100
-
***Deliver to individual members:** See the following option, [Members of team_](#members-of-team).
101
-
***Do not deliver:** No email is delivered.
91
+
-**Deliver to email address**: The email is delivered to the team's preferred email address.
92
+
-**Deliver to individual members**: The process is described in the following section, [Members of team_](#members-of-team).
93
+
-**Do not deliver**: No email is delivered.
102
94
103
-
95
+
:::image type="content" source="media/email-team-delivery-option-preference.png" border="false" alt-text="Screenshot that shows the email team delivery option preference.":::
104
96
105
-
The team's delivery setting value is displayed after the _Address_ label and can't be changed.
97
+
The team's delivery setting value is displayed after the **Address** label and can't be changed.
106
98
107
99
### Custom email address
108
100
109
-
The notification gets sent to multiple custom email addresses, which are separated by semicolons.
101
+
The notifications are sent to multiple custom email addresses, which are separated by semicolons.
102
+
103
+
:::image type="content" source="media/email-team-delivery-option-custom.png" border="false" alt-text="Screenshot that shows the custom email team delivery options.":::
110
104
111
-
112
105
### Members of team
113
106
114
-
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 is included on the **To:** line of the resulting email. However, the results of this expansion can be complicated and are explained in more detail in the [team and group expansion](#team-and-group-expansion-for-email-recipients) section.
107
+
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](#team-and-group-expansion-for-email-recipients) section.
115
108
116
-
109
+
:::image type="content" source="media/email-team-delivery-option-members.png" border="false" alt-text="Screenshot showing the name of a team for email delivery.":::
117
110
118
111
## Default subscription recipients
119
112
120
-
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](oob-supported-event-types.md).
113
+
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](oob-supported-event-types.md).
121
114
122
-
115
+
:::image type="content" source="media/email-delivery-default-subscription.png" border="false" alt-text="Screenshot showing recipients for default subscriptions.":::
123
116
124
117
> [!NOTE]
125
118
> The _Skip initiator_ option isn't available for all event types.
119
+
126
120
## Team and group expansion for email recipients
127
121
128
-
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 is a potentially recursive process that starts by looking at the team's direct members.
122
+
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.
129
123
130
-
Only members who have**not** opted out of the subscription get considered for the final recipient list. Any member who's an individual user gets added to the recipient list.
124
+
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.
131
125
132
-
Only Azure DevOps Services groups remain. For each group, the group's delivery preferences get examined:
126
+
Only Azure DevOps Services groups remain. For each group, the group's delivery preferences are examined:
133
127
134
-
* "Do not deliver": no further evaluation is done on this group and the next member group is evaluated
135
-
* "Deliver to email address": the email address is added to the final recipient list
136
-
* "Deliver to individual members": the group is expanded (like its parent group) and the same rules for evaluating its members are followed
128
+
-**Do not deliver**: No further evaluation is done on this group and the next member group is evaluated.
129
+
-**Deliver to email address**: The email address is added to the final recipient list.
130
+
-**Deliver to individual members**: The group is expanded (like its parent group) and the same rules for evaluating its members are followed.
137
131
138
132
### Scenarios
139
133
140
-
Let's look at a few scenarios. We use the following symbols to denote the types of members:
134
+
This section explores several example scenarios. The following examples use symbols to denote the types of team members:
135
+
136
+
-`I`: Individual user
137
+
-`T`: Nested team or group
138
+
-`E`: Email-enabled Microsoft Entra group
139
+
140
+
#### Team member enables "Do not deliver" setting
141
+
142
+
Example team members:
143
+
144
+
- The primary team has three members: users `I1` and `I2`, and nested team `T1`.
145
+
- Team `T1` has the **Do not deliver** setting enabled.
146
+
147
+
Only users `I1` and `I2` receive the notification messages at their preferred contact email address. Members of the nested team `T1` aren't notified.
148
+
149
+
#### Team member enables "Deliver to individual members" setting
150
+
151
+
Example team members:
152
+
153
+
- The primary team has three members: users `I1` and `I2`, and nested team `T1`.
154
+
- Team `T1` has two member users, `I2` and `I3`.
155
+
- User `I2` is a member of both the primary team and team `T1`.
156
+
- Team `T1` has the **Deliver to individual members** setting enabled.
157
+
158
+
Team `T1` is expanded to identify its members. `I1`, `I2`, and `I3` all receive the notification messages at their preferred contact email address.
159
+
160
+
#### Team contains nested group
161
+
162
+
Example team members:
163
+
164
+
- The primary team has three members: users `I1` and `I2`, and nested team `T1`.
165
+
- Team `T1` has three members: users `I2` and `I3`, and nested team `T2`.
166
+
- Team `T2` has two member users, `I4` and `I5`.
167
+
- User `I2` is a member of both the primary team and team `T1`.
168
+
- Team `T1` has the **Do not deliver** setting enabled.
169
+
- Team `T2` has the **Deliver to individual members** setting enabled.
170
+
171
+
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.
172
+
173
+
#### Team member is Microsoft Entra group
141
174
142
-
*`I`: individual user
143
-
*`T`: nested team or group
144
-
*`A`: mail-enabled Microsoft Entra group.
175
+
In this example, the primary team has three members: users `I1` and `I2`, and nested Microsoft Entra group `E1`.
145
176
146
-
| Scenario | Example |
147
-
|--|--|
148
-
| A member with _Do not deliver_ preference | The team has members `I1`, `I2`, and `T1`. `T1`'s delivery preference is _Do not deliver_. What happens: only `I1` and `I2` get notified via their preferred email addresses. Members of `T1` aren't notified. |
149
-
| A member with _Deliver to individual members_ preference | The team has members `I1`, `I2`, and `T1`. `T1`'s delivery preference is _Deliver to individual members_. `T1` has members `I2` and `I3`. What happens: `T1` is expanded (because of its delivery preference) and so `I1`, `I2`, and `I3` get notified via their preferred email addresses. |
150
-
| A nested group | The team has members `I1`, `I2`, and `T1`. `T1` has members `I2`, `I3`, and `T2`. `T1`'s delivery preference is _Do not deliver_. `T2` has members `I4` and `I5`. `T2`'s delivery preference is _Deliver to individual members_. What happens: because `T1` isn't expanded (because its delivery preference is "do not deliver"), only `I1` and `I2` get notified via their preferred email addresses. |
151
-
| A member that's a Microsoft Entra group | The team has members `I1`, `I2`, and `A1`. What happens: only `I1` and `I2` get notified via their preferred email addresses. Members of `A1` don't get notified, as Azure DevOps doesn't expand AD groups when delivering notifications. |
177
+
Azure DevOps doesn't expand Windows Server Active Directory (Windows AD) groups when delivering notifications. Only users `I1` and `I2` receive the notification messages at their preferred contact email address.
152
178
153
-
## Related articles
179
+
## Related content
154
180
155
181
-[Manage notifications for a team, group, global organization](manage-team-group-global-organization-notifications.md)
156
182
-[Default and supported notifications](oob-built-in-notifications.md)
157
-
-[Permissions, security groups, and service accounts reference](../../organizations/security/permissions.md)
183
+
-[Permissions, security groups, and service accounts reference](../../organizations/security/permissions.md)
Copy file name to clipboardExpand all lines: docs/organizations/notifications/includes/note-smtp-server.md
+3-4Lines changed: 3 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,13 +4,12 @@ ms.manager: mijacobs
4
4
ms.author: chcomley
5
5
author: chcomley
6
6
ms.topic: include
7
-
ms.date: 01/23/2020
7
+
ms.date: 05/12/2025
8
8
---
9
9
10
10
::: moniker range="< azure-devops"
11
11
12
12
> [!NOTE]
13
-
> For on-premises Azure DevOps Server, [configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) for team members to see the **Notifications** option from their [organization or user profile menu](../navigating-the-ui.md) and to receive notifications.
14
-
15
-
::: moniker-end
13
+
> For on-premises Azure DevOps Server, [configure an SMTP server](/azure/devops/server/admin/setup-customize-alerts) so team members can see the **Notifications** option from their [organization or user profile menu](../navigating-the-ui.md) and receive notifications.
0 commit comments