4. API

The Halon MTA is controlled via an API, which in turn is used by management tools such as the command line interface, Visual Studio Code plugin, and integrated package’s web administration. Those tools can be installed on either a central location (controlling an entire cluster) or on the MTA hosts themselves.

4.1. Endpoints

The primary API is the server programs’ control sockets. There is also a HTTP/JSON endpoint which can sometimes be more convenient. The API calls, and their respective request and response bodies are documented in the API reference.

4.1.1. Control sockets

The server programs have a control socket (Unix domain) as specified by environment.controlsocket.path.

All requests begin with a version (two bytes, ASCII char 5 and 3), and a command identifier (one byte, ASCII char). The command identifiers are assigned in alphabetical order. In requests with a Protobuf body, the command identifier is followed by a binary host packed (LE) unsigned 64 bit integer telling the size of the request body.

The response begins with one byte indicating the status; + for success, or E for error. It is followed by a binary host (LE) packed unsigned 64 bit integer telling the size the response data that follows. In the success case, the data is a Protobuf response body. In the error case, it is an ASCII string.

4.1.2. HTTP/JSON

Rather than connecting directly to the control sockets, there is a JSON over HTTP endpoint that proxies calls to the respective programs’ control sockets. The JSON request body (called payload) and response are direct JSON representations of the respective Protobuf structures. The HTTP/JSON API takes program, command, payload and version as arguments, where payload contains the request body as per the examples below.

Simple example without request body (payload)
% curl https://mta1/api/protobuf -d '{ "program": "smtpd", "command": "q" }' \
    --user johndoe:secret -H "Content-Type: application/json"
{
    "process": {
        "pid": "145",
        "runtime": "4235"
    },
    ...
More complex JSON request that returns queued email from example.org or example.com
{
    "program": "smtpd",
    "command": "F",
    "payload": {
        "conditions": {
            "senders": [
                { "domain": { "value": "example.org" }},
                { "domain": { "value": "example.com" }}
            ]
        }
    }
}

The command line interface has two arguments called --json-request and --json which dumps the request and response Protobuf data as JSON. It can be very helpful when working with the HTTP/JSON API.

Using halonctl to learn about the request and response data format
$ halonctl queue update --bounce --state DEFER --jobid foobar --json-request --json
{
    "conditions": {
        "queues": [
            {
                "queue": "DEFER"
                ...

4.2. API reference

The API request and response bodies are defined by the Protocol Buffer schemas. The following section describes them in more detail. As explained above, the HTTP/JSON simply uses a direct JSON representation of the respective Protobuf structures.

4.2.1. Command list

This is a list of all the API commands; which program that implements them, their command identifier, and request/response body format.

Prog.   Request Response Description
smtpd a ConfigGreenDeployRequest   Live stage
smtpd b   ConfigGreenStatusResponse ” (status)
smtpd c   ConfigGreenStatusResponse ” (cancel)
smtpd d   HSLBreakPointRequest Breakpoint
smtpd g   HSLCacheResponse Script cache
smtpd h HSLCacheClearRequest HSLCacheClearResponse ” (clear)
smtpd y HSLMemoryRequest HSLMemoryResponse Script memory
smtpd z HSLMemoryStoreRequest HSLMemoryStoreResponse ” (store)
smtpd A HSLMemoryDeleteRequest HSLMemoryDeleteResponse ” (delete)
rated i HSLRateRequest HSLRateResponse Script rate
rated i HSLRateClearRequest HSLRateClearResponse ” (clear)
smtpd r     Reload config
smtpd o     ” (suspend)
smtpd p     ” (policy)
smtpd H     ” (delivery)
rated r     ” (rated)
dlpd r     ” (dlpd)
smtpd s   SuspendResponse Queue suspend
smtpd t SuspendAddRequest SuspendAddResponse ” (add)
smtpd u SuspendDeleteRequest SuspendDeleteRequest ” (delete)
smtpd v   PolicyConditionResponse Queue policy
smtpd w PolicyConditionAddRequest PolicyConditionAddResponse ” (add)
smtpd x PolicyConditionDeleteRequest PolicyConditionDeleteResponse ” (delete)
smtpd B PolicyRateRefillRequest PolicyRateRefillResponse ” (rate refill)
smtpd D QueueGroupByRequest QueueGroupByResponse Queue distr.
smtpd F QueueListRequest QueueListResponse Queue list
smtpd G QueueUpdateRequest QueueUpdateResponse Queue update
smtpd E QueueImportRequest   Queue import
smtpd J QueueUnloadRequest QueueUnloadResponse Queue unload
smtpd I QueueQuotaRequest QueueQuotaResponse Queue quota
smtpd q   ProcessStatsResponse Show stats
smtpd C     Clear DNS