Notification settings API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to manage notification settings in GitLab. For more information, see notification emails.

Notification levels

The notification levels are defined in the NotificationSetting.level model enumeration. These levels are recognized:

disabled: Turn off all notifications
participating: Receive notifications for threads you have participated in
watch: Receive notifications for most activity
global: Use your global notification settings
mention: Receive notifications when you are mentioned in a comment
custom: Receive notifications for selected events

If you use the custom level, you can control specific email events. Available events are returned by NotificationSetting.email_events. These events are recognized:

Event	Description
`approver`	A merge request you're eligible to approve is created
`change_reviewer_merge_request`	When a merge request's reviewer is changed
`close_issue`	When an issue is closed
`close_merge_request`	When a merge request is closed
`failed_pipeline`	When a pipeline fails
`fixed_pipeline`	When a previously failed pipeline is fixed
`issue_due`	When an issue is due tomorrow
`merge_merge_request`	When a merge request is merged
`merge_when_pipeline_succeeds`	When a merge request is set to auto-merge
`moved_project`	When a project is moved
`new_epic`	When a new epic is created (in the Premium and Ultimate tier)
`new_issue`	When a new issue is created
`new_merge_request`	When a new merge request is created
`new_note`	When someone adds a comment
`new_release`	When a new release is published
`push_to_merge_request`	When someone pushes to a merge request
`reassign_issue`	When an issue is reassigned
`reassign_merge_request`	When a merge request is reassigned
`reopen_issue`	When an issue is reopened
`reopen_merge_request`	When a merge request is reopened
`success_pipeline`	When a pipeline completes successfully

Get global notification settings

Get current notification settings and email address.

GET /notification_settings

Example request:

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

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`level`	string	Global notification level
`notification_email`	string	Email address where notifications are sent

Example response:

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

Update global notification settings

Update notification settings and email address.

PUT /notification_settings

Example request:

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

Supported attributes:

Attribute	Type	Required	Description
`approver`	boolean	No	Turn on notifications when a merge request you're eligible to approve is created
`change_reviewer_merge_request`	boolean	No	Turn on notifications when a merge request's reviewer is changed
`close_issue`	boolean	No	Turn on notifications when an issue is closed
`close_merge_request`	boolean	No	Turn on notifications when a merge request is closed
`failed_pipeline`	boolean	No	Turn on notifications when a pipeline fails
`fixed_pipeline`	boolean	No	Turn on notifications when a previously failed pipeline is fixed
`issue_due`	boolean	No	Turn on notifications when an issue is due tomorrow
`level`	string	No	Global notification level
`merge_merge_request`	boolean	No	Turn on notifications when a merge request is merged
`merge_when_pipeline_succeeds`	boolean	No	Turn on notifications when a merge request is set to auto-merge
`moved_project`	boolean	No	Turn on notifications when a project is moved
`new_epic`	boolean	No	Turn on notifications when a new epic is created (in the Premium and Ultimate tier)
`new_issue`	boolean	No	Turn on notifications when a new issue is created
`new_merge_request`	boolean	No	Turn on notifications when a new merge request is created
`new_note`	boolean	No	Turn on notifications when a new comment is added
`new_release`	boolean	No	Turn on notifications when a new release is published
`notification_email`	string	No	Email address where notifications are sent
`push_to_merge_request`	boolean	No	Turn on notifications when someone pushes to a merge request
`reassign_issue`	boolean	No	Turn on notifications when an issue is reassigned
`reassign_merge_request`	boolean	No	Turn on notifications when a merge request is reassigned
`reopen_issue`	boolean	No	Turn on notifications when an issue is reopened
`reopen_merge_request`	boolean	No	Turn on notifications when a merge request is reopened
`success_pipeline`	boolean	No	Turn on notifications when a pipeline completes successfully

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`level`	string	Global notification level
`notification_email`	string	Email address where notifications are sent

Example response:

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

Get group or project notification settings

Get notification settings for a group or project.

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

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/notification_settings"

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/8/notification_settings"

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the group or project

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`level`	string	Notification level

Example response for standard notification level:

{
  "level": "global"
}

Example response for a group with custom notification level:

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

In this response:

- `true` indicates the notification is turned on.
- `false` indicates the notification is turned off.
- `null` indicates the notification uses the default setting.

The `new_epic` attribute is available only in the Premium and Ultimate tiers.

## Update group or project notification settings

Update notification settings for a group or project.

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

Example requests:

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

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

Supported attributes:

| Attribute                      | Type              | Required | Description |
| ------------------------------ | ----------------- | -------- | ----------- |
| `approver`                     | boolean           | No       | Turn on notifications when a merge request you're eligible to approve is created |
| `change_reviewer_merge_request`| boolean           | No       | Turn on notifications when a merge request's reviewer changes |
| `close_issue`                  | boolean           | No       | Turn on notifications when an issue is closed |
| `close_merge_request`          | boolean           | No       | Turn on notifications when a merge request is closed |
| `failed_pipeline`              | boolean           | No       | Turn on notifications when a pipeline fails |
| `fixed_pipeline`               | boolean           | No       | Turn on notifications when a previously failed pipeline is fixed |
| `id`                           | integer or string | Yes      | ID or [URL-encoded path](rest/_index.md#namespaced-paths) of the group or project |
| `issue_due`                    | boolean           | No       | Turn on notifications when an issue is due tomorrow |
| `level`                        | string            | No       | Notification level for this group or project |
| `merge_merge_request`          | boolean           | No       | Turn on notifications when a merge request is merged |
| `merge_when_pipeline_succeeds` | boolean           | No       | Turn on notifications when a merge request is set to merge when its pipeline succeeds |
| `moved_project`                | boolean           | No       | Turn on notifications when a project is moved |
| `new_epic`                     | boolean           | No       | Turn on notifications when a new epic is created (in the Premium and Ultimate tier) |
| `new_issue`                    | boolean           | No       | Turn on notifications when a new issue is created |
| `new_merge_request`            | boolean           | No       | Turn on notifications when a new merge request is created |
| `new_note`                     | boolean           | No       | Turn on notifications when a new comment is added |
| `new_release`                  | boolean           | No       | Turn on notifications when a new release is published |
| `push_to_merge_request`        | boolean           | No       | Turn on notifications when someone pushes to a merge request |
| `reassign_issue`               | boolean           | No       | Turn on notifications when an issue is reassigned |
| `reassign_merge_request`       | boolean           | No       | Turn on notifications when a merge request is reassigned |
| `reopen_issue`                 | boolean           | No       | Turn on notifications when an issue is reopened |
| `reopen_merge_request`         | boolean           | No       | Turn on notifications when a merge request is reopened |
| `success_pipeline`             | boolean           | No       | Turn on notifications when a pipeline completes successfully |

If successful, returns [`200 OK`](rest/troubleshooting.md#status-codes) and one of the following response formats.

For a non-custom notification level:

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

For a custom notification level, the response includes an `events` object showing the status of each notification:

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

In this response:

- `true` indicates the notification is turned on.
- `false` indicates the notification is turned off.
- `null` indicates the notification uses the default setting.

The `new_epic` attribute is available only in the Premium and Ultimate tiers.