• Notification levels
• Get global notification settings
• Update global notification settings
• Get group or project notification settings
• Update group or project notification settings

Notification settings API

{{< details >}}

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

{{< /details >}}

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:

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:

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:

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

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:

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

Example response for standard notification level:

{
  "level": "global"
}

Example response for a group with custom notification level:

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

{{< alert type=”note” >}}

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

{{< /alert >}}

Update group or project notification settings

Update notification settings for a group or project.

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

Example requests:

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

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:

If successful, returns 200 OK and one of the following response formats.

For a non-custom notification level:

{
  "level": "watch"
}

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

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

{{< alert type=”note” >}}

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

{{< /alert >}}