Last updated: 2026-08-28

DNSBL reliable mutation delivery

DNSBL/FraudBL mutation requests sent to the existing /api/dnsbl/records/* endpoints are now protected by durable delivery tracking. This is intended for integrations where losing an add, update, delist, or bulk request would be more serious than receiving a delayed final result.

The API URLs are unchanged.

Durable requests

For DNSBL-token authenticated mutation requests, Tools records the requested action before the DNS write is attempted. The stored request does not contain the raw authentication token.

If the DNS operation succeeds, the request is marked complete. If Tools encounters a server-side or DNS transport failure, the request remains pending and is retried automatically until it succeeds. Permanent client errors such as invalid payloads or denied access are retained as rejected requests but are not retried.

Clients may send an X-Request-ID header. Reusing the same request ID makes the durable intake idempotent at the request-buffer level. If no request ID is supplied, Tools creates one.

Example:

curl -s "https://tools.tornevall.net/api/dnsbl/records/add" \
  -H "Content-Type: application/json" \
  -H "X-Dnsbl-Token: YOUR_TOKEN" \
  -H "X-Request-ID: mail-filter-20260828-000123" \
  -d '{"ip":"203.0.113.10","bitmask":64,"publication_type":"fraudbl"}'

A server-side failure can still be returned to the original HTTP caller. That response describes the immediate attempt; the durable request remains eligible for automatic retry.

Bulk failure diagnostics

Bulk DNS writes now keep mutation and verification state consistent. If any required DNS write fails, the overall result is unsuccessful and authoritative verification cannot be reported as successful for the complete mutation.

Failure results can include the failed authoritative zone, a reason, a status code, and a safe error message. Authentication secrets are not included.

Completion callbacks

A DNSBL token can register one completion callback. Callbacks are delivered for successful mutations whether the first inbound attempt succeeded immediately or the mutation succeeded later after automatic retry.

Configure the callback with the same DNSBL token:

GET /api/dnsbl/callback
POST /api/dnsbl/callback

Example configuration request:

curl -s "https://tools.tornevall.net/api/dnsbl/callback" \
  -H "Content-Type: application/json" \
  -H "X-Dnsbl-Token: YOUR_TOKEN" \
  -d '{"enabled":true,"url":"https://callback.example.com/dnsbl","secret":"YOUR_CALLBACK_SECRET"}'

Callback URLs must use HTTPS and resolve only to public network addresses.

Successful results are grouped into callback batches instead of producing one outbound HTTP request per DNSBL mutation. A callback payload has this shape:

{
  "event": "dnsbl.mutations.completed",
  "count": 2,
  "results": [
    {
      "request_id": "mail-filter-20260828-000123",
      "action": "add",
      "request": {
        "ip": "203.0.113.10",
        "bitmask": 64,
        "publication_type": "fraudbl"
      },
      "status": "success",
      "attempts": 2,
      "completed_at": "2026-08-28T08:50:00+02:00"
    }
  ]
}

If a callback secret is configured, Tools signs the exact JSON body with HMAC-SHA256 and sends the signature in:

X-ToolsAPI-Signature: sha256=<hex digest>

Callbacks also include:

X-ToolsAPI-Event: dnsbl.mutations.completed

A failed callback delivery does not undo a successful DNS mutation. The callback batch remains pending and is retried later.

Operator reporting

DNSBL reliability summaries have their own configurable Slack destination in the DNSBL reliability admin page. Operational application failures continue to use the normal always-on Tools diagnostics independently of that reporting choice.

Tornevall Networks