# Halon Delivery Guru Version: 2.2-stable Delivery Guru is an AI-powered assistant. It helps to optimize email deliverability by identifying patterns that may not be classified correctly by simple regex techniques. A service provided by Delivery Guru is *halon-bounce-classifier*. This provides an easy-to-use API, allowing the classifier to be used directly from HSL, as well as from other services. To get started, see [examples](#api). Each classification result has a suggested next action to take, and the scope for the action. Most [classification results](#api:results) relate directly to Halon policy fields, enabling you to have automatic responses in HSL. ## Table of contents * [Installation](#install) * [Prerequisites](#install:prerequisites) * [Distributions](#install:distributions) * [Ubuntu](#install:ubuntu) * [RHEL](#install:rhel) * [Startup](#install:startup) * [Docker & K8s](#install:docker-k8s) * [Docker Desktop with VS Code](#install:docker-desktop-with-vs-code) * [Upgrade](#upgrade) * [Configuration](#config) * [Cache](#config:cache) * [Batching](#config:batching) * [HTTP API](#api) * [Endpoints](#api:endpoints) * [Version 1 (`/v1`)](#api:version-1-v1) * [Version 2 (`/v2`)](#api:version-2-v2) * [HTTPS](#api:https) * [Authentication](#api:authentication) * [Bounce Next Action Classification (BNAC)](#api:bounce-next-action-classification-bnac) * [Single Message Example](#api:single-message-example) * [Batch Message Example](#api:batch-message-example) * [Results](#api:results) * [Severity](#api:severity) * [Implementation](#api:implementation) * [Halon Extras Plugin](#api:halon-extras-plugin) * [Example HSL script](#api:example-hsl-script) * [Backoff Action Classification](#api:backoff-action-classification) * [Example request (default behaviour)](#api:example-request-default-behaviour) * [Example request (single message, returning probability)](#api:example-request-single-message-returning-probability) * [Example request (batch, class-only response)](#api:example-request-batch-class-only-response) * [Backoff Results](#api:backoff-results) * [Cache](#api:cache) * [Cache Endpoints](#api:cache-endpoints) * [Cache statistics](#api:cache-statistics) * [Cache info](#api:cache-info) * [Changelog](#changelog) # Installation ## Prerequisites Make sure you have followed the [instructions](https://docs.halon.io/manual/install.html#installation) in our manual to add our package repository. ## Distributions ### Ubuntu To install the .deb package use the following commands. ```console # apt-get update # apt-get install halon-bounce-classifier ``` ### RHEL To install the .rpm package use the following commands. ```console # yum install halon-bounce-classifier ``` ## Startup When the initial [configuration](#config) is in place, the program can be started with: ```console # systemctl start halon-bounce-classifier ``` ## Docker & K8s For instructions on how to build a container image of the program as well as deploying it on K8s (Kubernetes), see our [halon-docker](https://github.com/halon/halon-docker) GitHub repository. ## Docker Desktop with VS Code For local running in Docker Desktop, make the following additions. `.devcontainer/Dockerfile`: ```docker RUN apt-get update && apt-get -y install halon-bounce-classifier=2.0.0 ``` `.devcontainer/supervisord.conf`: ```docker [program:bounce-classifier] command=/opt/halon/bounce-classifier/sbin/bounce-classifier environment=PORT=8084 ``` You can set [configuration](#config) environment variables for the service here. # Upgrade In order to upgrade the package, install the new package over the previous installed one (see the [Installation](#install) chapter). After the upgrade the service needs to be manually restarted. # Configuration *halon-bounce-classifier* loads settings from environment variables. You can set the environment variables by using the following command. ```console # systemctl edit halon-bounce-classifier ``` You can then add the environment variables you want to configure like below. ```default [Service] Environment="PORT=8000" Environment="HOST=127.0.0.1" ``` Below are some of the most important environment variables that can be configured. ## PORT The port that the server will run on. The default is `8080`. ## HOST The IP address that the server will run on. The default is `127.0.0.1`. > **Note** > > Use `*` to listen on any IP, useful when for example running in a container ## SSL_CERTFILE The path to the certificate. The default is to not use SSL. ## SSL_KEYFILE The path to the private key. The default is to not use SSL. ## API_KEY The API key to use. The default is to not use an API key. ## Cache ### HALON_BNAC_CACHE * **Type:** bool `True` if the cache should be enabled. The default is `True`. ### HALON_BNAC_CACHE_STATS * **Type:** bool `True` if the cache statistics should be enabled. The default is `False` since collection statistics has a small performance impact. ### HALON_BNAC_CACHE_FOLDER * **Type:** str The folder where the cache is stored. The default is `/var/lib/halon/bounce-classifier`. ### HALON_BNAC_CACHE_SIZE * **Type:** int The cache size in bytes. The default is of approximately 100MB. ### HALON_BNAC_CACHE_TIMER * **Type:** bool Enables timing metrics for cache `get` and `set` operations. The default is `False`. When enabled, `/v1/cache/stats` reports: - `timer_enabled` as `true` - `avg_get_time_ms`: average cache read time in milliseconds - `avg_set_time_ms`: average cache write time in milliseconds Set `HALON_BNAC_CACHE_TIMER=true` to enable it. Any other value keeps it disabled. ## Batching ### HALON_BNAC_BATCH_SIZE * **Type:** int Maximum number of queued requests processed together in one server-side batch for batch endpoints (for example `/v1/bnac` and `/v2/bnac`). This does not apply to single-request endpoints such as `/v1/bnac/single` and `/v2/bnac/single`. The default is `16`. ### HALON_BNAC_BATCH_WAIT_TIME * **Type:** int Batch flush interval in milliseconds. The default is `100`. # 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. ## 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 ### Version 1 (`/v1`) - **BNAC classification only:** BNAC endpoints under `/v1` return the model’s classification prediction. Response (`v1`): ```default {"class":"GRAYLISTING"} ``` ### 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} ``` ## HTTPS To run the service with HTTPS you can set the environment varibales: - [`SSL_CERTFILE`](#config:confval-SSL_CERTFILE) - [`SSL_KEYFILE`](#config:confval-SSL_KEYFILE) You can also configure the port and the host as defined in [configuration](#config): - [`PORT`](#config:confval-PORT) - [`HOST`](#config:confval-HOST) ## 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: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: ' -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"message": "smtp;451 4.7.1 : 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: ' -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"message": "smtp;451 4.7.1 : Recipient address rejected: Greylisting in effect, please come back later"}' ``` ## Bounce Next Action Classification (BNAC) ### 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 : Recipient address rejected: Greylisting in effect, please come back later"}' ``` Response (v1): ```default {"class":"GRAYLISTING"} ``` Response (v2): ```default {"class":"GRAYLISTING","probability":0.95663047} ``` ### 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 : Recipient address rejected: Greylisting in effect, please come back later", "smtp;450 4.0.0 ... User unknown..." ] }' ``` Response (v2): ```default [ {"class":"GRAYLISTING","probability":0.95663047}, {"class":"RECIPIENT_NOT_FOUND","probability":0.70459944}] ``` ### 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

(e.g. Spamhaus,..) information | 5 | `tenantid` | | `BLOCKED` | Recipient MTA is blocking,

no third-party information | 3 | `tenantid`,

`grouping` | | `DKIM` | Fix DKIM | 3 | `tenantid`,

`grouping` | | `DMARC` | Fix DMARC | 3 | `tenantid`,

`grouping` | | `DNS_PTR` | Fix reverse DNS | 3 | `tenantid`,

`grouping` | | `DOMAIN_REPUTATION` | Slow down from this sending domain | 4 | `tenantid`,

`grouping` | | `GRAYLISTING` | Slow down to this recipient domain,

you are at risk of being blocked | 3 | `tenantid`,

`grouping` | | `IP_REPUTATION` | Slow down from this sending IP | 4 | `localip`,

`grouping` | | `MESSAGE_CONTENT` | Suspend campaign and review what is sent | 3 | `jobid` | | `MX_ERROR` | Verify your DNS resolution of this recipient

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,

reduce frequency to this address | 2 | `jobid`,

`grouping` | | `RECIPIENT_NOT_FOUND` | Remove the address | 1 | recipient address | | `SPF` | Fix SPF | 3 | `tenantid`,

`grouping` | | `TEMPORARY_ERROR` | Slow down sending to this recipient domain | 1 | `tenantid`,

`grouping` | | `TLS` | Check your TLS negotiation with this

recipient domain | 3 | `tenantid`,

`grouping` | | `VIRUS` | Suspend campaign and review what is sent | 6 | `jobid` | ### Severity * 6 = Most severe impact on sender reputation * 1 = Lowest impact on sender reputation ### Implementation #### 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) #### 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 : 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. ## 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 | ### 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 : Recipient address rejected: Greylisting in effect, please come back later" }' -w "\n" ``` Returns: ```default [{"class":"GRAYLISTING","fields":[],"actions":[]}] ``` ### 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 : Recipient address rejected: Greylisting in effect, please come back later" }' -w "\n" ``` Returns: ```default [{"class":"GRAYLISTING","probability":0.9574445,"fields":[],"actions":[]}] ``` ### 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 : Recipient address rejected: Greylisting in effect, please come back later", "smtp;450 4.0.0 ... User unknown..." ] }' -w "\n" ``` Returns: ```default [{"class":"GRAYLISTING","fields":[],"actions":[]},{"class":"RECIPIENT_ERROR","fields":[],"actions":[]}] ``` ### 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` | | | ## Cache ### 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' ``` #### 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 } ``` #### Cache info Cache info endpoint returns the current cache configuration, including whether it is enabled (see [`HALON_BNAC_CACHE`](#config:confval-HALON_BNAC_CACHE)), the folder where it is stored (see [`HALON_BNAC_CACHE_FOLDER`](#config:confval-HALON_BNAC_CACHE_FOLDER)), and the maximum size in bytes (see [`HALON_BNAC_CACHE_SIZE`](#config:confval-HALON_BNAC_CACHE_SIZE)). ```default { "cache_enabled": true, "folder": "/var/lib/halon/bounce-classifier", "max_size": "104857600" } ``` # Changelog ## 2.2.3 Released 2026-11-11 * **Fixes** Improved normalisation * **Fixes** Improved classification, for both BNAC and Backoff models, by retraining the model with more recent information * **Fixes** Updated third-party dependencies ## 2.2.2 Released 2026-04-27 - **Fixes** Updated third-party dependencies ## 2.2.1 Released 2026-03-25 * **Bug** Fix handling of very long bounce messages ## 2.2.0 Released 2026-03-05 * **New** Added an MTA backoff classification model that classifies bounce messages into specific backoff reason categories (for example temporary system failures, rate limits, reputation or policy-related blocks, and recipient errors). ## 2.1.1 Released 2025-09-19 * **Bug** Fix required dependencies list ## 2.1.0 Released 2025-09-18 * **Imp** Improved normalisation * **Imp** Improved classification by retraining the model with more recent information * **Imp** Performance improvements ## 2.0.0 Released 2025-07-25 * **Imp** Rewritten in Rust instead of Python > **Warning** > > The path of the binary has changed to `/opt/halon/bounce-classifier/sbin/bounce-classifier`. > **Warning** > > The default path where the cache is stored has changed to `/var/lib/halon/bounce-classifier`. ## 1.3.0 Released 2025-03-26 * **New** Added category `PROTOCOL_ERROR` * **Imp** Better support for German and French smtp error messages * **Imp** Improved model accuracy ## 1.2.0 Released 2025-02-26 * **New** New `/v2` API endpoints with probability score reporting * **Imp** Server-side batching API endpoint renamed from `/bnac/batch` to `/bnac/single` (Old one kept as alias) * **Bug** Fixed bug where `/cache/stats` API endpoint reported that stats were enabled when they weren’t ## 1.1.1 Released 2025-02-14 * **New** Added coverage of bounce messages * **Imp** Improved accuracy of model ## 1.1.0 Released 2025-01-07 * **New** Support for request cache in `/bnac` endpoint * **New** New `/bnac/batch` endpoint for server side request batching ## 1.0.0 Released 2024-12-16 * **New** Initial release