Notification settings API All tiers All offerings

Change notification settings using the REST API.

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 All offerings

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"
AttributeTypeRequiredDescription
levelstringnoThe global notification level
notification_emailstringnoThe email address to send notifications
new_notebooleannoEnable/disable this notification
new_issuebooleannoEnable/disable this notification
reopen_issuebooleannoEnable/disable this notification
close_issuebooleannoEnable/disable this notification
reassign_issuebooleannoEnable/disable this notification
issue_duebooleannoEnable/disable this notification
new_merge_requestbooleannoEnable/disable this notification
push_to_merge_requestbooleannoEnable/disable this notification
reopen_merge_requestbooleannoEnable/disable this notification
close_merge_requestbooleannoEnable/disable this notification
reassign_merge_requestbooleannoEnable/disable this notification
merge_merge_requestbooleannoEnable/disable this notification
failed_pipelinebooleannoEnable/disable this notification
fixed_pipelinebooleannoEnable/disable this notification
success_pipelinebooleannoEnable/disable this notification
moved_projectbooleannoEnable/disable this notification (Introduced in GitLab 13.3)
merge_when_pipeline_succeedsbooleannoEnable/disable this notification (Introduced in GitLab 13.9)
new_epicbooleannoEnable/disable this notification (Introduced in GitLab 11.3) Ultimate All offerings

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"
AttributeTypeRequiredDescription
idinteger or stringyesThe 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 --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"
AttributeTypeRequiredDescription
idinteger or stringyesThe ID, or URL-encoded path, of the group or project
levelstringnoThe global notification level
new_notebooleannoEnable/disable this notification
new_issuebooleannoEnable/disable this notification
reopen_issuebooleannoEnable/disable this notification
close_issuebooleannoEnable/disable this notification
reassign_issuebooleannoEnable/disable this notification
issue_duebooleannoEnable/disable this notification
new_merge_requestbooleannoEnable/disable this notification
push_to_merge_requestbooleannoEnable/disable this notification
reopen_merge_requestbooleannoEnable/disable this notification
close_merge_requestbooleannoEnable/disable this notification
reassign_merge_requestbooleannoEnable/disable this notification
merge_merge_requestbooleannoEnable/disable this notification
failed_pipelinebooleannoEnable/disable this notification
fixed_pipelinebooleannoEnable/disable this notification
success_pipelinebooleannoEnable/disable this notification
moved_projectbooleannoEnable/disable this notification (Introduced in GitLab 13.3)
merge_when_pipeline_succeedsbooleannoEnable/disable this notification (Introduced in GitLab 13.9)
new_epicbooleannoEnable/disable this notification (Introduced in GitLab 11.3) Ultimate All offerings

Example responses:

{
  "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,
    "fixed_pipeline": false,
    "success_pipeline": false
  }
}

Users on GitLab Ultimate also see the new_epic parameter for global and group-level notification settings:

{
  "level": "custom",
  "events": {
    "new_note": true,
    "new_issue": false,
    "new_epic": false,
    ...
  }
}