2017-05-10 18:48:07 +00:00
# Notification settings API
2016-08-02 20:52:55 +00:00
2020-02-06 15:09:11 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5632) in GitLab 8.12.
2016-08-02 20:52:55 +00:00
2019-07-04 08:22:41 +00:00
## Valid notification levels
2016-08-02 20:52:55 +00:00
2016-11-02 08:19:25 +00:00
The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized:
2016-08-02 20:52:55 +00:00
2020-02-27 09:09:01 +00:00
```plaintext
2016-08-02 20:52:55 +00:00
disabled
participating
watch
global
mention
custom
```
2018-07-23 02:42:19 +00:00
If the `custom` level is used, specific email events can be controlled. Available events are returned by `NotificationSetting.email_events` . Currently, these events are recognized:
2016-08-02 20:52:55 +00:00
2019-07-03 09:32:54 +00:00
- `new_note`
- `new_issue`
- `reopen_issue`
- `close_issue`
- `reassign_issue`
- `issue_due`
- `new_merge_request`
- `push_to_merge_request`
- `reopen_merge_request`
- `close_merge_request`
- `reassign_merge_request`
- `merge_merge_request`
- `failed_pipeline`
2020-02-27 18:09:21 +00:00
- `fixed_pipeline`
2019-07-03 09:32:54 +00:00
- `success_pipeline`
2019-07-08 08:50:38 +00:00
- `new_epic` ** (ULTIMATE)**
2019-07-03 09:32:54 +00:00
2016-08-02 20:52:55 +00:00
## Global notification settings
Get current notification settings and email address.
2020-02-27 09:09:01 +00:00
```plaintext
2016-08-02 20:52:55 +00:00
GET /notification_settings
```
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/notification_settings
2016-08-02 20:52:55 +00:00
```
Example response:
```json
{
"level": "participating",
"notification_email": "admin@example.com"
}
```
## Update global notification settings
Update current notification settings and email address.
2020-02-27 09:09:01 +00:00
```plaintext
2016-08-02 20:52:55 +00:00
PUT /notification_settings
```
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/notification_settings?level=watch
2016-08-02 20:52:55 +00:00
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `level` | string | no | The global notification level |
| `notification_email` | string | no | The email address to send notifications |
| `new_note` | boolean | no | Enable/disable this notification |
| `new_issue` | boolean | no | Enable/disable this notification |
| `reopen_issue` | boolean | no | Enable/disable this notification |
| `close_issue` | boolean | no | Enable/disable this notification |
| `reassign_issue` | boolean | no | Enable/disable this notification |
2018-03-30 12:25:46 +00:00
| `issue_due` | boolean | no | Enable/disable this notification |
2016-08-02 20:52:55 +00:00
| `new_merge_request` | boolean | no | Enable/disable this notification |
2017-07-25 11:56:09 +00:00
| `push_to_merge_request` | boolean | no | Enable/disable this notification |
2016-08-02 20:52:55 +00:00
| `reopen_merge_request` | boolean | no | Enable/disable this notification |
| `close_merge_request` | boolean | no | Enable/disable this notification |
| `reassign_merge_request` | boolean | no | Enable/disable this notification |
| `merge_merge_request` | boolean | no | Enable/disable this notification |
2016-11-08 15:52:45 +00:00
| `failed_pipeline` | boolean | no | Enable/disable this notification |
2020-02-27 18:09:21 +00:00
| `fixed_pipeline` | boolean | no | Enable/disable this notification |
2016-11-08 15:52:45 +00:00
| `success_pipeline` | boolean | no | Enable/disable this notification |
2020-02-06 15:09:11 +00:00
| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6626) in 11.3) ** (ULTIMATE)** |
2016-08-02 20:52:55 +00:00
Example response:
```json
{
"level": "watch",
"notification_email": "admin@example.com"
}
```
## Group / project level notification settings
Get current group or project notification settings.
2020-02-27 09:09:01 +00:00
```plaintext
2016-08-02 20:52:55 +00:00
GET /groups/:id/notification_settings
GET /projects/:id/notification_settings
```
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/groups/5/notification_settings
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/projects/8/notification_settings
2016-08-02 20:52:55 +00:00
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
Example response:
```json
{
"level": "global"
}
```
## Update group/project level notification settings
Update current group/project notification settings.
2020-02-27 09:09:01 +00:00
```plaintext
2016-08-02 20:52:55 +00:00
PUT /groups/:id/notification_settings
PUT /projects/:id/notification_settings
```
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/groups/5/notification_settings?level=watch
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom& new_note=true
2016-08-02 20:52:55 +00:00
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `level` | string | no | The global notification level |
| `new_note` | boolean | no | Enable/disable this notification |
| `new_issue` | boolean | no | Enable/disable this notification |
| `reopen_issue` | boolean | no | Enable/disable this notification |
| `close_issue` | boolean | no | Enable/disable this notification |
| `reassign_issue` | boolean | no | Enable/disable this notification |
2018-03-30 12:25:46 +00:00
| `issue_due` | boolean | no | Enable/disable this notification |
2016-08-02 20:52:55 +00:00
| `new_merge_request` | boolean | no | Enable/disable this notification |
2017-07-25 11:56:09 +00:00
| `push_to_merge_request` | boolean | no | Enable/disable this notification |
2016-08-02 20:52:55 +00:00
| `reopen_merge_request` | boolean | no | Enable/disable this notification |
| `close_merge_request` | boolean | no | Enable/disable this notification |
| `reassign_merge_request` | boolean | no | Enable/disable this notification |
| `merge_merge_request` | boolean | no | Enable/disable this notification |
2016-11-08 15:52:45 +00:00
| `failed_pipeline` | boolean | no | Enable/disable this notification |
2020-02-27 18:09:21 +00:00
| `fixed_pipeline` | boolean | no | Enable/disable this notification |
2016-11-08 15:52:45 +00:00
| `success_pipeline` | boolean | no | Enable/disable this notification |
2020-02-06 15:09:11 +00:00
| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6626) in 11.3) ** (ULTIMATE)** |
2016-08-02 20:52:55 +00:00
Example responses:
```json
{
"level": "watch"
}
{
"level": "custom",
"events": {
"new_note": true,
"new_issue": false,
"reopen_issue": false,
"close_issue": false,
"reassign_issue": false,
2018-03-30 12:25:46 +00:00
"issue_due": false,
2016-08-02 20:52:55 +00:00
"new_merge_request": false,
2017-07-25 11:56:09 +00:00
"push_to_merge_request": false,
2016-08-02 20:52:55 +00:00
"reopen_merge_request": false,
"close_merge_request": false,
"reassign_merge_request": false,
2016-11-08 15:52:45 +00:00
"merge_merge_request": false,
"failed_pipeline": false,
2020-02-27 18:09:21 +00:00
"fixed_pipeline": false,
2016-11-08 15:52:45 +00:00
"success_pipeline": false
2016-08-02 20:52:55 +00:00
}
}
```
2019-07-03 09:32:54 +00:00
Users on GitLab [Ultimate or Gold ](https://about.gitlab.com/pricing/ ) will also see
the `new_epic` parameter:
```json
{
"level": "custom",
"events": {
"new_note": true,
"new_issue": false,
"new_epic": false,
...
}
}
```