notification_settings.md 5.54 KB
Newer Older
1
# Notification settings API
2 3 4 5 6

>**Note:** This feature was [introduced][ce-5632] in GitLab 8.12.

**Valid notification levels**

7
The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized:
8 9 10 11 12 13 14 15 16 17

```
disabled
participating
watch
global
mention
custom
```

18
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:
19 20 21 22 23 24 25

```
new_note
new_issue
reopen_issue
close_issue
reassign_issue
26
issue_due
27
new_merge_request
28
push_to_merge_request
29 30 31 32
reopen_merge_request
close_merge_request
reassign_merge_request
merge_merge_request
33 34
failed_pipeline
success_pipeline
35 36 37 38 39 40 41 42 43 44 45
```

## Global notification settings

Get current notification settings and email address.

```
GET /notification_settings
```

```bash
46
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/notification_settings
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
```

Example response:

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

## Update global notification settings

Update current notification settings and email address.

```
PUT /notification_settings
```

```bash
67
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/notification_settings?level=watch
68 69 70 71 72 73 74 75 76 77 78
```

| 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 |
79
| `issue_due` | boolean | no | Enable/disable this notification |
80
| `new_merge_request` | boolean | no | Enable/disable this notification |
81
| `push_to_merge_request` | boolean | no | Enable/disable this notification |
82 83 84 85
| `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 |
86 87
| `failed_pipeline` | boolean | no | Enable/disable this notification |
| `success_pipeline` | boolean | no | Enable/disable this notification |
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107

Example response:

```json
{
  "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
```

```bash
108 109
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
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |

Example response:

```json
{
  "level": "global"
}
```

## Update group/project level notification settings

Update current group/project notification settings.

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

```bash
134 135
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
136 137 138 139 140 141 142 143 144 145 146
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The group/project ID or path |
| `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 |
147
| `issue_due` | boolean | no | Enable/disable this notification |
148
| `new_merge_request` | boolean | no | Enable/disable this notification |
149
| `push_to_merge_request` | boolean | no | Enable/disable this notification |
150 151 152 153
| `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 |
154 155
| `failed_pipeline` | boolean | no | Enable/disable this notification |
| `success_pipeline` | boolean | no | Enable/disable this notification |
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171

Example responses:

```json
{
  "level": "watch"
}

{
  "level": "custom",
  "events": {
    "new_note": true,
    "new_issue": false,
    "reopen_issue": false,
    "close_issue": false,
    "reassign_issue": false,
172
    "issue_due": false,
173
    "new_merge_request": false,
174
    "push_to_merge_request": false,
175 176 177
    "reopen_merge_request": false,
    "close_merge_request": false,
    "reassign_merge_request": false,
178 179 180
    "merge_merge_request": false,
    "failed_pipeline": false,
    "success_pipeline": false
181 182 183 184 185
  }
}
```

[ce-5632]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632