# Spam (Rspamd)

<a id="delete-api-v1-spam-blacklist"></a>
#### `DELETE /api/v1/spam/blacklist`

*Remove from spam blacklist*

Pass the entry as `?entry=value` query param. Idempotent.

**Query parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `entry` | 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 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/spam/blacklist
```

---

<a id="get-api-v1-spam-blacklist"></a>
#### `GET /api/v1/spam/blacklist`

*Get global spam blacklist*

Domains / emails / IPs always rejected. Response data: `{entries: [...]}`.

**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/spam/blacklist
```

---

<a id="post-api-v1-spam-blacklist"></a>
#### `POST /api/v1/spam/blacklist`

*Add to spam blacklist*

Idempotent — already-present entries return success with the original list.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `entry` | string | yes | minLength=1; maxLength=255 |

**Request body example:**

```json
{
  "entry": "string"
}
```

**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/spam/blacklist
```

---

<a id="get-api-v1-spam-config"></a>
#### `GET /api/v1/spam/config`

*Get Rspamd global config*

Reject / add-header / greylist score thresholds, learning toggles.

**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/spam/config
```

---

<a id="put-api-v1-spam-config"></a>
#### `PUT /api/v1/spam/config`

*Update Rspamd global config*

Patch score thresholds / learning flags. Reloads Rspamd.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `add_header_score` | number | no | — |
| `greylist_score` | number | no | — |
| `reject_score` | number | no | — |

**Request body example:**

```json
{
  "add_header_score": 1.0,
  "greylist_score": 1.0,
  "reject_score": 1.0
}
```

**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 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/spam/config
```

---

<a id="get-api-v1-spam-status"></a>
#### `GET /api/v1/spam/status`

*Rspamd service status*

Reports whether Rspamd is installed + running + version.

**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/spam/status
```

---

<a id="get-api-v1-spam-webui"></a>
#### `GET /api/v1/spam/webui`

*Rspamd web UI proxy info*

Returns the local controller URL + a has_password flag (not the password itself) for the loopback-only Rspamd controller (admin-only).

**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/spam/webui
```

---

<a id="delete-api-v1-spam-whitelist"></a>
#### `DELETE /api/v1/spam/whitelist`

*Remove from spam whitelist*

Pass the entry as `?entry=value` query param. Idempotent.

**Query parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `entry` | 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 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/spam/whitelist
```

---

<a id="get-api-v1-spam-whitelist"></a>
#### `GET /api/v1/spam/whitelist`

*Get global spam whitelist*

Domains / emails / IPs always passed through without scoring. Response data: `{entries: [...]}`.

**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/spam/whitelist
```

---

<a id="post-api-v1-spam-whitelist"></a>
#### `POST /api/v1/spam/whitelist`

*Add to spam whitelist*

Idempotent — already-present entries return success with the original list.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `entry` | string | yes | minLength=1; maxLength=255 |

**Request body example:**

```json
{
  "entry": "string"
}
```

**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/spam/whitelist
```

---