<a id="http-api"></a>

# HTTP API

The bounce-classifier service provides HTTP(S) endpoints for classifying bounce reasons using a machine learning model.
It supports batching, caching, and can run with or without TLS.

<a id="endpoints"></a>

## Endpoints

- **POST** `/v1/bnac/single` — Classify a single message, returns class only
- **POST** `/v2/bnac/single` — Classify a single message, returns class and probability
- **POST** `/v1/bnac`        — Classify a batch or single, returns class only, uses server-side cache if enabled
- **POST** `/v2/bnac`        — Classify a batch or single, returns class and probability, uses server-side cache if enabled
- **POST** `/v1/backoff`     — Classify a batch or single for backoff actions, returns class with metadata
- **POST** `/normalise`      — Normalize a bounce message into a canonical representation
- **GET**  `/v1/cache/stats` — Get cache statistics
- **GET**  `/v1/cache/info`  — Get cache configuration info

<a id="version-1-v1"></a>

### Version 1 (`/v1`)

- **BNAC classification only:** BNAC endpoints under `/v1` return the model’s classification prediction.

Response (`v1`):

```default
{"class":"GRAYLISTING"}
```

<a id="version-2-v2"></a>

### Version 2 (`/v2`)

- **BNAC classification with probability:** BNAC endpoints under `/v2` provide both:
  : - The classification prediction, and
    - An associated probability value for informational purposes.
- **Probability Usage:** The provided probability is meant to supplement the classification. It’s recommended not to rely solely on this value for automated decision-making processes.

Response (`v2`):

```default
{"class":"GRAYLISTING","probability":0.95663047}
```

<a id="https"></a>

## HTTPS

To run the service with HTTPS you can set the environment varibales:

- [`SSL_CERTFILE`](config.html.md#confval-SSL_CERTFILE)
- [`SSL_KEYFILE`](config.html.md#confval-SSL_KEYFILE)

You can also configure the port and the host as defined in [configuration](config.html.md):

- [`PORT`](config.html.md#confval-PORT)
- [`HOST`](config.html.md#confval-HOST)

<a id="authentication"></a>

## Authentication

You can use the `X-API-Key` header for authentication.

The `X-API-Key` header is optional and can be used to restrict access to the API. If not provided, the API will still function but without authentication.

To configure the API key, look in the configuration section: [`API_KEY`](config.html.md#confval-API_KEY) , once that is set then that key can be used in the requests:

```default
curl -X 'POST' 'https://127.0.0.1:8443/v1/bnac/single' \
  -H 'X-API-Key: <YOUR_API_KEY_HERE>' -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"message": "smtp;451 4.7.1 <user@example.sk>: Recipient address rejected: Greylisting in effect, please come back later"}'
```

The API key is independent of HTTPS, it can be used with HTTP as well:

```default
curl -X 'POST' 'http://127.0.0.1:8080/v1/bnac' \
  -H 'X-API-Key: <YOUR_API_KEY_HERE>' -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"message": "smtp;451 4.7.1 <user@example.sk>: Recipient address rejected: Greylisting in effect, please come back later"}'
```

<a id="bounce-next-action-classification-bnac"></a>

## Bounce Next Action Classification (BNAC)

<a id="single-message-example"></a>

### Single Message Example

```default
curl -X 'POST' 'http://127.0.0.1:8080/v1/bnac/single' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"message": "smtp;451 4.7.1 <user@example.sk>: Recipient address rejected: Greylisting in effect, please come back later"}'
```

Response (v1):

```default
{"class":"GRAYLISTING"}
```

Response (v2):

```default
{"class":"GRAYLISTING","probability":0.95663047}
```

<a id="batch-message-example"></a>

### Batch Message Example

Sending multiple messages at the same time is supported and will be faster than sending them one by one.

```default
curl -X 'POST' 'http://127.0.0.1:8080/v2/bnac' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [
      "smtp;451 4.7.1 <user@example.sk>: Recipient address rejected: Greylisting in effect, please come back later",
      "smtp;450 4.0.0 <fish.biscuit@acme.ca>... User unknown..."
    ]
  }'
```

Response (v2):

```default
[ {"class":"GRAYLISTING","probability":0.95663047}, {"class":"RECIPIENT_NOT_FOUND","probability":0.70459944}]
```

<a id="results"></a>

<a id="id1"></a>

### Results

An object with a *class* property is returned. The possible classifications are:

| Classification        | Suggested Action                                                                    | Severity   | Scope                           |
|-----------------------|-------------------------------------------------------------------------------------|------------|---------------------------------|
| `BLOCK_LIST`          | Recipient MTA is blocking, with third-party<br/><br/>(e.g. Spamhaus,..) information | 5          | `tenantid`                      |
| `BLOCKED`             | Recipient MTA is blocking,<br/><br/>no third-party information                      | 3          | `tenantid`,<br/><br/>`grouping` |
| `DKIM`                | Fix DKIM                                                                            | 3          | `tenantid`,<br/><br/>`grouping` |
| `DMARC`               | Fix DMARC                                                                           | 3          | `tenantid`,<br/><br/>`grouping` |
| `DNS_PTR`             | Fix reverse DNS                                                                     | 3          | `tenantid`,<br/><br/>`grouping` |
| `DOMAIN_REPUTATION`   | Slow down from this sending domain                                                  | 4          | `tenantid`,<br/><br/>`grouping` |
| `GRAYLISTING`         | Slow down to this recipient domain,<br/><br/>you are at risk of being blocked       | 3          | `tenantid`,<br/><br/>`grouping` |
| `IP_REPUTATION`       | Slow down from this sending IP                                                      | 4          | `localip`,<br/><br/>`grouping`  |
| `MESSAGE_CONTENT`     | Suspend campaign and review what is sent                                            | 3          | `jobid`                         |
| `MX_ERROR`            | Verify your DNS resolution of this recipient<br/><br/>domain                        | 3          | `remotemx`                      |
| `PROTOCOL_ERROR`      | Verify the MTA configuration and protocols                                          | 1          | `grouping`                      |
| `RATE_LIMIT`          | Slow down to this recipient domain                                                  | 3          | `grouping`                      |
| `RECIPIENT_ERROR`     | Slow down, possible poor list quality,<br/><br/>reduce frequency to this address    | 2          | `jobid`,<br/><br/>`grouping`    |
| `RECIPIENT_NOT_FOUND` | Remove the address                                                                  | 1          | recipient address               |
| `SPF`                 | Fix SPF                                                                             | 3          | `tenantid`,<br/><br/>`grouping` |
| `TEMPORARY_ERROR`     | Slow down sending to this recipient domain                                          | 1          | `tenantid`,<br/><br/>`grouping` |
| `TLS`                 | Check your TLS negotiation with this<br/><br/>recipient domain                      | 3          | `tenantid`,<br/><br/>`grouping` |
| `VIRUS`               | Suspend campaign and review what is sent                                            | 6          | `jobid`                         |

<a id="severity"></a>

### Severity

* 6 = Most severe impact on sender reputation
* 1 = Lowest impact on sender reputation

<a id="implementation"></a>

### Implementation

<a id="halon-extras-plugin"></a>

#### Halon Extras Plugin

Halon provides a client plugin reference implementation; that is cacheable, support http_background.

* [halon-extras-bounce-classifier](https://github.com/halon-extras/bounce-classifier)

<a id="example-hsl-script"></a>

#### Example HSL script

This example script can be run from the terminal directly with [hsh](https://docs.halon.io/manual/plugins_development.html#hsh).
It is equivalent to the `curl` example above, passing in a message and receiving a response.

> ```hsl
> $guru = "http://127.0.0.1:8000/v1/bnac/single";
> $options = ["headers" => ["Content-Type: application/json", "Accept: application/json"], "extended_result" => true];
> $data = "451 4.7.1 <bla.candy@fish.sk>: Recipient address rejected: Greylisting in effect, please come back later";
> $payload = json_encode(["message" => $data]);
> $res = http($guru, $options, [], $payload);
> if ($res["content"]) {
>     $content = json_decode($res["content"]);
>     $class = $content["class"];
>     echo $class;
> }
> ```

For best performance in calls from script hooks, use the [http-background](https://github.com/halon-extras/http-background) plugin
instead of the foreground [http](https://docs.halon.io/hsl/functions.html#http) function.

<a id="backoff-action-classification"></a>

## Backoff Action Classification

The `/v1/backoff` endpoint is used by the sending MTA to determine the action it should take in response to an SMTP bounce message returned by the receiving MTA.
While identifying the specific cause of a failure is the responsibility of the BNAC model, the Backoff model is essential for implementing automated backoff logic and handling all failure types effectively.

Optional Query Parameters

| Parameter            | Type    | Description                                                                   | Default   |
|----------------------|---------|-------------------------------------------------------------------------------|-----------|
| `bypass_cache`       | boolean | When true, skip reading/writing the cache                                     | false     |
| `return_probability` | boolean | When true, include probability for each class instead of class-only responses | false     |

<a id="example-request-default-behaviour"></a>

### Example request (default behaviour)

```default
curl -X 'POST' 'http://127.0.0.1:8080/v1/backoff' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "smtp;451 4.7.1 <bla.candy@fish.sk>: Recipient address rejected: Greylisting in effect, please come back later"
  }' -w "\n"
```

Returns:

```default
[{"class":"GRAYLISTING","fields":[],"actions":[]}]
```

<a id="example-request-single-message-returning-probability"></a>

### Example request (single message, returning probability)

```default
curl -X 'POST' 'http://127.0.0.1:8080/v1/backoff?return_probability=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "smtp;451 4.7.1 <bla.candy@fish.sk>: Recipient address rejected: Greylisting in effect, please come back later"
  }' -w "\n"
```

Returns:

```default
[{"class":"GRAYLISTING","probability":0.9574445,"fields":[],"actions":[]}]
```

<a id="example-request-batch-class-only-response"></a>

### Example request (batch, class-only response)

```default
curl -X 'POST' 'http://127.0.0.1:8080/v1/backoff?bypass_cache=true' \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [
      "smtp;451 4.7.1 <bla.candy@fish.sk>: Recipient address rejected: Greylisting in effect, please come back later",
      "smtp;450 4.0.0 <fish.biscuit@acme.ca>... User unknown..."
    ]
  }' -w "\n"
```

Returns:

```default
[{"class":"GRAYLISTING","fields":[],"actions":[]},{"class":"RECIPIENT_ERROR","fields":[],"actions":[]}]
```

<a id="backoff-results"></a>

### Backoff Results

A response object always includes `class`, `fields` and `actions`. When `return_probability=true` is used, it also includes `probability`.
The possible classifications are:

| Classification                                  | Fields                            | Actions               |
|-------------------------------------------------|-----------------------------------|-----------------------|
| `AUTHENTICATION_ERROR`                          |                                   |                       |
| `CONCURRENCY_LIMIT`                             | `localip`, `grouping`             | `concurrency`         |
| `CONNECTION_FAILURE`                            |                                   |                       |
| `CONTENT_REJECTED_OTHER`                        |                                   |                       |
| `CONTENT_REJECTED_SPAM`                         | `tenantid`, `jobid`, `grouping`   | `suspend`             |
| `CONTENT_REJECTED_VIRUS`                        | `tenantid`, `jobid`, `grouping`   | `suspend`             |
| `GENERIC_BLOCK`                                 |                                   |                       |
| `GRAYLISTING`                                   |                                   |                       |
| `INFRASTRUCTURE_BLOCK`                          | `jobid`, `grouping`               | `suspend`             |
| `INFRASTRUCTURE_ERROR`                          | `jobid`, `grouping`               | `suspend`             |
| `MAILBOX_FULL`                                  |                                   |                       |
| `POLICY_VIOLATION_SPF_DMARC__DKIM_FAIL`         | `tenantid`, `jobid`, `grouping`   | `suspend`             |
| `POLICY_VIOLATION_SPF_DMARC__SPF_OR_DMARC_FAIL` | `localip`, `tenantid`, `grouping` | `suspend`             |
| `PROTOCOL_ERROR`                                |                                   |                       |
| `RATE_LIMIT__DOMAIN_RATE_LIMIT`                 | `tenantid`, `grouping`            | `rate`                |
| `RATE_LIMIT__GENERAL`                           | `localip`, `grouping`             | `rate`                |
| `RATE_LIMIT__IP_RATE_LIMIT`                     | `localip`, `grouping`             | `rate`                |
| `RATE_LIMIT__RECIPIENT_LIMIT`                   |                                   |                       |
| `RATE_LIMIT__SERVER_BUSY`                       | `localip`, `remoteip`             | `concurrency`, `rate` |
| `RATE_LIMIT__URL_DOMAIN`                        | `tenantid`, `jobid`, `grouping`   | `rate`                |
| `RECIPIENT_ERROR`                               |                                   |                       |
| `SENDER_REPUTATION__DOMAIN`                     | `tenantid`, `grouping`            | `suspend`             |
| `SENDER_REPUTATION__SENDER_ADDRESS`             | `tenantid`, `grouping`            | `suspend`             |
| `TEMPORARY_SYSTEM_FAILURE`                      |                                   |                       |

<a id="cache"></a>

## Cache

<a id="cache-endpoints"></a>

### Cache Endpoints

```default
curl -X 'GET' 'http://127.0.0.1:8080/v1/cache/stats' -H 'accept: application/json'
curl -X 'GET' 'http://127.0.0.1:8080/v1/cache/info'  -H 'accept: application/json'
```

<a id="cache-statistics"></a>

#### Cache statistics

```default
curl -X 'GET' 'http://127.0.0.1:8080/v1/cache/stats' -H 'accept: application/json'
```

Returns:

```default
{
    "cache_enabled": true,
    "stats_enabled": false,
    "timer_enabled": false,
    "hit_requests": 0,
    "miss_requests": 0,
    "size_in_bytes": 12288,
    "number_of_elements": 0,
    "avg_get_time_ms": 0,
    "avg_set_time_ms": 0
}
```

<a id="cache-info"></a>

#### Cache info

Cache info endpoint returns the current cache configuration,
including whether it is enabled (see [`HALON_BNAC_CACHE`](config.html.md#confval-HALON_BNAC_CACHE)), the folder where it is stored (see [`HALON_BNAC_CACHE_FOLDER`](config.html.md#confval-HALON_BNAC_CACHE_FOLDER)), and the maximum size in bytes (see [`HALON_BNAC_CACHE_SIZE`](config.html.md#confval-HALON_BNAC_CACHE_SIZE)).

```default
{
    "cache_enabled": true,
    "folder": "/var/lib/halon/bounce-classifier",
    "max_size": "104857600"
}
```
