Skip to content

Notification settings API

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

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

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
  • fixed_pipeline
  • success_pipeline
  • moved_project
  • merge_when_pipeline_succeeds
  • new_epic Ultimate only.

Global notification settings

Get current notification settings and email address.

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

Example response:

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

Update global notification settings

Update current notification settings and email address.

PUT /notification_settings
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
fixed_pipeline boolean no Enable/disable this notification
success_pipeline boolean no Enable/disable this notification
moved_project boolean no Enable/disable this notification
merge_when_pipeline_succeeds boolean no Enable/disable this notification
new_epic boolean no Enable/disable this notification Ultimate only.

Example response:

{
  "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
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 or string yes The ID, or URL-encoded path, of the group or project.

Example response:

{
  "level": "global"
}

Update group/project level notification settings

Update current group/project notification settings.

PUT /groups/:id/notification_settings
PUT /projects/:id/notification_settings
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/notification_settings"
```0

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/_index.md#namespaced-paths) |
| `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 |
| `fixed_pipeline` | boolean | no | Enable/disable this notification |
| `success_pipeline` | boolean | no | Enable/disable this notification |
| `moved_project` | boolean | no | Enable/disable this notification |
| `merge_when_pipeline_succeeds` | boolean | no | Enable/disable this notification |
| `new_epic` | boolean | no | Enable/disable this notification Ultimate only. |

Example responses:

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

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

Users on [GitLab Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic`
parameter for global and group-level notification settings:

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