gitlab-org--gitlab-foss/doc/api/notification_settings.md

# Notification settings API

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632) in GitLab 8.12.

## Valid notification levels

The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized:

```
disabled
participating
watch
global
mention
custom
```

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:

- `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`
- `success_pipeline`
- `new_epic` **(ULTIMATE)**

## Global notification settings

Get current notification settings and email address.

```
GET /notification_settings
```

```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/notification_settings
```

Example response:

```json
{
  "level": "participating",
  "notification_email": "admin@example.com"
}
```

## Update global notification settings

Update current notification settings and email address.

```
PUT /notification_settings
```

```bash
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/notification_settings?level=watch
```

| 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 |
| `issue_due` | boolean | no | Enable/disable this notification |
| `new_merge_request` | boolean | no | Enable/disable this notification |
| `push_to_merge_request` | boolean | no | Enable/disable this notification |
| `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 |
| `failed_pipeline` | boolean | no | Enable/disable this notification |
| `success_pipeline` | boolean | no | Enable/disable this notification |
| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **(ULTIMATE)** |

Example response:

```json
{
  "level": "watch",
  "notification_email": "admin@example.com"
}
```

## Group / project level notification settings

Get current group or project notification settings.

```
GET /groups/:id/notification_settings
GET /projects/:id/notification_settings
```

```bash
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
```

| 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.

```
PUT /groups/:id/notification_settings
PUT /projects/:id/notification_settings
```

```bash
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
```

| 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 |
| `issue_due` | boolean | no | Enable/disable this notification |
| `new_merge_request` | boolean | no | Enable/disable this notification |
| `push_to_merge_request` | boolean | no | Enable/disable this notification |
| `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 |
| `failed_pipeline` | boolean | no | Enable/disable this notification |
| `success_pipeline` | boolean | no | Enable/disable this notification |
| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **(ULTIMATE)** |

Example responses:

```json
{
  "level": "watch"
}

{
  "level": "custom",
  "events": {
    "new_note": true,
    "new_issue": false,
    "reopen_issue": false,
    "close_issue": false,
    "reassign_issue": false,
    "issue_due": false,
    "new_merge_request": false,
    "push_to_merge_request": false,
    "reopen_merge_request": false,
    "close_merge_request": false,
    "reassign_merge_request": false,
    "merge_merge_request": false,
    "failed_pipeline": false,
    "success_pipeline": false
  }
}
```

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,
    ...
  }
}
```
update API doc with +API (h1 heading) 2017-05-10 18:48:07 +00:00			`# Notification settings API`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00
Clean up EE api docs that were merged to CE Many small fixes to api docs which were merged from EE to CE, and tables cleaned up, as noted in issue https://gitlab.com/gitlab-org/gitlab-ce/issues/64072 2019-07-04 08:22:41 +00:00			`> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632) in GitLab 8.12.`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00
Clean up EE api docs that were merged to CE Many small fixes to api docs which were merged from EE to CE, and tables cleaned up, as noted in issue https://gitlab.com/gitlab-org/gitlab-ce/issues/64072 2019-07-04 08:22:41 +00:00			`## Valid notification levels`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00
Add failed_pipeline and success_pipeline to API doc 2016-11-02 08:19:25 +00:00			The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized:
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00
			```
			`disabled`
			`participating`
			`watch`
			`global`
			`mention`
			`custom`
			```

Add email_events to replace EMAIL_EVENTS because it needs to be dynamic, allowing override for EE. 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:
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00
Update api docs to finish aligning EE and CE docs Squashing a few commits and continuing work on merging the 12 api docs that have not been ported to CE yet. 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`
			- `success_pipeline`
Changing badges to use parentheses not brackets Previously, we used brackets to denote the tier badges, but this made Kramdown, the docs site Markdown renderer, show many warnings when building the site. This is now fixed by using parentheses instead of square brackets. This was caused by [PREMIUM] looking like a link to Kramdown, which couldn't find a URL there. See: - https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/484 - https://gitlab.com/gitlab-org/gitlab-ce/issues/63800 2019-07-08 08:50:38 +00:00			- `new_epic` (ULTIMATE)
Update api docs to finish aligning EE and CE docs Squashing a few commits and continuing work on merging the 12 api docs that have not been ported to CE yet. 2019-07-03 09:32:54 +00:00
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00			`## Global notification settings`

			`Get current notification settings and email address.`

			```
			`GET /notification_settings`
			```

			```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs. 2018-12-27 09:03:08 +00:00			`curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/notification_settings`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 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.`

			```
			`PUT /notification_settings`
			```

			```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs. 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`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 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 \|
Only send issue due emails to participants and custom subscribers 2018-03-30 12:25:46 +00:00			\| `issue_due` \| boolean \| no \| Enable/disable this notification \|
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00			\| `new_merge_request` \| boolean \| no \| Enable/disable this notification \|
Send notification emails when push to a merge request Closes #23460 2017-07-25 11:56:09 +00:00			\| `push_to_merge_request` \| boolean \| no \| Enable/disable this notification \|
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 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 \|
Add failed_pipeline and success_pipeline to API doc Feedback: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6342#note_17981448 2016-11-08 15:52:45 +00:00			\| `failed_pipeline` \| boolean \| no \| Enable/disable this notification \|
			\| `success_pipeline` \| boolean \| no \| Enable/disable this notification \|
Changing badges to use parentheses not brackets Previously, we used brackets to denote the tier badges, but this made Kramdown, the docs site Markdown renderer, show many warnings when building the site. This is now fixed by using parentheses instead of square brackets. This was caused by [PREMIUM] looking like a link to Kramdown, which couldn't find a URL there. See: - https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/484 - https://gitlab.com/gitlab-org/gitlab-ce/issues/63800 2019-07-08 08:50:38 +00:00			\| `new_epic` \| boolean \| no \| Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) (ULTIMATE) \|
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 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.`

			```
			`GET /groups/:id/notification_settings`
			`GET /projects/:id/notification_settings`
			```

			```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs. 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`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 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.`

			```
			`PUT /groups/:id/notification_settings`
			`PUT /projects/:id/notification_settings`
			```

			```bash
Replace look-alike token with '<your_access_token>' Replace all '9koXpg98eAheJpvBs5tK' occurrences with '<your_access_token>' in API docs. 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`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 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 \|
Only send issue due emails to participants and custom subscribers 2018-03-30 12:25:46 +00:00			\| `issue_due` \| boolean \| no \| Enable/disable this notification \|
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00			\| `new_merge_request` \| boolean \| no \| Enable/disable this notification \|
Send notification emails when push to a merge request Closes #23460 2017-07-25 11:56:09 +00:00			\| `push_to_merge_request` \| boolean \| no \| Enable/disable this notification \|
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 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 \|
Add failed_pipeline and success_pipeline to API doc Feedback: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6342#note_17981448 2016-11-08 15:52:45 +00:00			\| `failed_pipeline` \| boolean \| no \| Enable/disable this notification \|
			\| `success_pipeline` \| boolean \| no \| Enable/disable this notification \|
Changing badges to use parentheses not brackets Previously, we used brackets to denote the tier badges, but this made Kramdown, the docs site Markdown renderer, show many warnings when building the site. This is now fixed by using parentheses instead of square brackets. This was caused by [PREMIUM] looking like a link to Kramdown, which couldn't find a URL there. See: - https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/484 - https://gitlab.com/gitlab-org/gitlab-ce/issues/63800 2019-07-08 08:50:38 +00:00			\| `new_epic` \| boolean \| no \| Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) (ULTIMATE) \|
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 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,`
Only send issue due emails to participants and custom subscribers 2018-03-30 12:25:46 +00:00			`"issue_due": false,`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00			`"new_merge_request": false,`
Send notification emails when push to a merge request Closes #23460 2017-07-25 11:56:09 +00:00			`"push_to_merge_request": false,`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00			`"reopen_merge_request": false,`
			`"close_merge_request": false,`
			`"reassign_merge_request": false,`
Add failed_pipeline and success_pipeline to API doc Feedback: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6342#note_17981448 2016-11-08 15:52:45 +00:00			`"merge_merge_request": false,`
			`"failed_pipeline": false,`
			`"success_pipeline": false`
Add notification_settings API calls Use NotificationSetting::EMAIL_EVENTS for params 2016-08-02 20:52:55 +00:00			`}`
			`}`
			```

Update api docs to finish aligning EE and CE docs Squashing a few commits and continuing work on merging the 12 api docs that have not been ported to CE yet. 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,`
			`...`
			`}`
			`}`
			```