4.1.2.3. Examples

Simple example without request body (payload)
% curl https://mta1/api/protobuf -d '{ "program": "smtpd", "command": "q" }' \
    -H "Content-Type: application/json" \
    -H "X-API-Key: badsecret"
{
    "process": {
        "pid": "145",
        "runtime": "4235"
    },
    ...

Note

When using the integrated package you should send over a username and password using basic access authentication (--user johndoe:badsecret) instead of using an API key.

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"
                ...