# Notifications

<a id="delete-api-v1-admin-notifications"></a>
#### `DELETE /api/v1/admin/notifications`

*Delete every admin notification*

Bulk operation behind the inbox's "Clear All": removes every record the operator's inbox holds (admin-targeted and broadcast; a tenant's own records stay). Response data: `{deleted: <count>}`.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/notifications
```

---

<a id="get-api-v1-admin-notifications"></a>
#### `GET /api/v1/admin/notifications`

*List admin notifications*

Returns the admin notification inbox. Response data shape: `{notifications: [...], total, unread_count}` — `total` is the size of the inbox, not of the page.

**Query parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `limit` | integer | no | minimum=1; maximum=200 |
| `unread_only` | boolean | no | — |
| `category` | string | no | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/notifications
```

---

<a id="post-api-v1-admin-notifications"></a>
#### `POST /api/v1/admin/notifications`

*Push admin notification*

Create a notification visible in the admin inbox. Response data: `{id, stored}` — `stored` is false and `id` null when the panel switch or the event matrix suppresses the record.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `category` | string | no | default `system`; enum: `account`, `disk`, `ssl`, `backup`, `service`, `login`, `2fa`, `firewall`, `email`, `database`, `update`, `license`, `system` |
| `level` | string | no | default `info`; enum: `info`, `warning`, `critical` |
| `message` | string | yes | minLength=1; maxLength=4096 |
| `target` | string | no | default `admin`; enum: `admin`, `client`, `all` |
| `title` | string | yes | minLength=1; maxLength=255 |
| `username` | string | no | default ``; pattern=`^([a-z][a-z0-9]{2,15})?$` |

**Request body example:**

```json
{
  "category": "system",
  "level": "info",
  "message": "string",
  "target": "admin",
  "title": "string",
  "username": ""
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/notifications
```

---

<a id="post-api-v1-admin-notifications-read-all"></a>
#### `POST /api/v1/admin/notifications/read-all`

*Mark every admin notification as read*

Bulk operation. Response data: `{marked: <count>}`.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/notifications/read-all
```

---

<a id="get-api-v1-admin-notifications-settings"></a>
#### `GET /api/v1/admin/notifications/settings`

*Get admin notification preferences*

Returns panel + email toggles per category, SMTP settings (with password masked), the event matrix and every event's e-mail template. Each `templates` entry carries the subject and body in force, `customized` (true when the operator's own copy replaces the default; `default_subject` / `default_body` then hold the default) and `variables` — the keys the event fills in, each with a `sample` value for previews. `general_variables` lists the keys every template can use. SMTP password is redacted to a `••••` sentinel — pass the same sentinel back on save to keep the stored value untouched.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/notifications/settings
```

---

<a id="put-api-v1-admin-notifications-settings"></a>
#### `PUT /api/v1/admin/notifications/settings`

*Update admin notification preferences*

Patch panel/email category toggles, SMTP block, event templates.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `email_categories` | array<string> | no | — |
| `email_enabled` | boolean | no | — |
| `events` | array<NotificationEventUpdate> | no | — |
| `panel_categories` | array<string> | no | — |
| `panel_enabled` | boolean | no | — |
| `smtp` | SmtpSettingsUpdate | no | — |
| `templates` | array<NotificationTemplateUpdate> | no | — |

**Request body example:**

```json
{
  "email_categories": [
    "string"
  ],
  "email_enabled": false,
  "events": [
    {
      "admin_email": "...",
      "admin_panel": "...",
      "client_email": "...",
      "client_panel": "...",
      "id": "..."
    }
  ],
  "panel_categories": [
    "string"
  ],
  "panel_enabled": false,
  "smtp": {
    "encryption": "...",
    "from_email": "...",
    "from_name": "...",
    "host": "...",
    "password": "...",
    "port": "...",
    "username": "..."
  },
  "templates": [
    {
      "body": "...",
      "event": "...",
      "id": "...",
      "name": "...",
      "subject": "...",
      "variables": "..."
    }
  ]
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_NotificationPreferences_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "email_categories": [
      "..."
    ],
    "email_enabled": true,
    "events": [
      "..."
    ],
    "panel_categories": [
      "..."
    ],
    "panel_enabled": true
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/notifications/settings
```

---

<a id="post-api-v1-admin-notifications-test-email"></a>
#### `POST /api/v1/admin/notifications/test-email`

*Send test email*

Send a one-shot test email using the SMTP block in the body (or the persisted settings if the body sends the masked sentinel).

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `encryption` | string | no | default `tls`; pattern=`^(none\|tls\|ssl)$` |
| `from_email` | string | no | default ``; maxLength=255 |
| `from_name` | string | no | default `WHost`; maxLength=255 |
| `host` | string | no | default ``; maxLength=255 |
| `password` | string | no | default ``; maxLength=255 |
| `port` | integer | no | default `587`; minimum=1.0; maximum=65535.0 |
| `to_email` | string | no | — |
| `username` | string | no | default ``; maxLength=255 |

**Request body example:**

```json
{
  "encryption": "tls",
  "from_email": "",
  "from_name": "WHost",
  "host": "",
  "password": "",
  "port": 587,
  "to_email": "string",
  "username": ""
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/admin/notifications/test-email
```

---

<a id="get-api-v1-admin-notifications-unread-count"></a>
#### `GET /api/v1/admin/notifications/unread-count`

*Get unread admin notifications count*

Lightweight endpoint for the topbar bell badge. Response data: `{unread_count}`.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/notifications/unread-count
```

---

<a id="delete-api-v1-admin-notifications-notif-id"></a>
#### `DELETE /api/v1/admin/notifications/{notif_id}`

*Delete notification*

Remove a single notification from the inbox (no soft-delete).

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `notif_id` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/notifications/{notif_id}
```

---

<a id="post-api-v1-admin-notifications-notif-id-read"></a>
#### `POST /api/v1/admin/notifications/{notif_id}/read`

*Mark notification as read*

Flip the unread → read flag for one notification.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `notif_id` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/admin/notifications/{notif_id}/read
```

---