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.

  Copy to clipboard  
GET /notification_settings

Example request:

 Shell Copy to clipboard  
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:

 JSON Copy to clipboard  
{
  "level": "participating",
  "notification_email": "admin@example.com"
}

Update global notification settings

Update notification settings and email address.

  Copy to clipboard  
PUT /notification_settings

Example request:

 Shell Copy to clipboard  
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:

 JSON Copy to clipboard  
{
  "level": "watch",
  "notification_email": "admin@example.com"
}

Get group or project notification settings

Get notification settings for a group or project.

  Copy to clipboard  
GET /groups/:id/notification_settings
GET /projects/:id/notification_settings

Example request:

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

 Shell Copy to clipboard  
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:

 JSON Copy to clipboard  
{
  "level": "global"
}

Example response for a group with custom notification level:

 JSON Copy to clipboard  
{
  "level": "custom",
  "events": {
    "new_release": null,
    "new_note": null,
    "new_issue": null,
    "reopen_issue": null,
    "close_issue": null,
    "reassign_issue": null,
    "issue_due": null,
    "new_merge_request": null,
    "push_to_merge_request": null,
    "reopen_merge_request": null,
    "close_merge_request": null,
    "reassign_merge_request": null,
    "change_reviewer_merge_request": null,
    "merge_merge_request": null,
    "failed_pipeline": null,
    "fixed_pipeline": null,
    "success_pipeline": null,
    "moved_project": true,
    "merge_when_pipeline_succeeds": false,
    "new_epic": null
  }
}

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.

  Copy to clipboard  
PUT /groups/:id/notification_settings
PUT /projects/:id/notification_settings

Example requests:

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

 Shell Copy to clipboard  
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true"

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 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 and one of the following response formats.

For a non-custom notification level:

 JSON Copy to clipboard  
{
  "level": "watch"
}

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

 JSON Copy to clipboard  
{
  "level": "custom",
  "events": {
    "new_release": null,
    "new_note": true,
    "new_issue": false,
    "reopen_issue": null,
    "close_issue": null,
    "reassign_issue": null,
    "issue_due": null,
    "new_merge_request": null,
    "push_to_merge_request": null,
    "reopen_merge_request": null,
    "close_merge_request": null,
    "reassign_merge_request": null,
    "change_reviewer_merge_request": null,
    "merge_merge_request": null,
    "failed_pipeline": false,
    "fixed_pipeline": null,
    "success_pipeline": null,
    "moved_project": false,
    "merge_when_pipeline_succeeds": false,
    "new_epic": null
  }
}

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.

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

Try GitLab for free with access to all features for 30 days.

Get help

If you didn't find what you were looking for, search the docs.

If you want help with something specific and could use community support, post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab subscription).

Request support

Notification settings API

Notification levels

Get global notification settings

Update global notification settings

Get group or project notification settings

Update group or project notification settings

Help & feedback

Docs

Product

Feature availability and product trials

Get help