Last updated: 2026-08-20

DNSBL WordPress plugin telemetry

The Tornevall Networks DNSBL WordPress plugin can optionally submit aggregate usage statistics to Tools. This feature is disabled by default and requires an explicit WordPress administrator opt-in.

Configuring a DNSBL / Tools API token is functional configuration and is not treated as telemetry consent.

Endpoint

POST /api/dnsbl/telemetry/batch
X-Dnsbl-Token: <active DNSBL token>
Content-Type: application/json

The endpoint is write-only for plugin clients. It does not provide a telemetry readback endpoint to the sending WordPress site.

Frequency

The plugin normally submits at most one telemetry batch per hour through WP-Cron. On low-traffic WordPress installations, delivery can occur later because WP-Cron is traffic-driven.

A failed or timed-out submission retains the same batch ID. Tools treats the combination of DNSBL token and batch ID as idempotent so a retry of an already accepted batch is not counted twice.

Aggregate payload

Example:

{
  "schema_version": 1,
  "batch_id": "f6c2259d-2454-4bc0-b62e-1df174c4bf9d",
  "plugin_version": "3.1.6",
  "period_start": "2026-08-20T15:00:00+00:00",
  "period_end": "2026-08-20T15:59:59+00:00",
  "events": [
    {
      "type": "dnsbl_evaluation",
      "bitmask": 64,
      "listed": true,
      "blocked": true,
      "source": "request",
      "count": 37
    }
  ]
}

The WordPress sender aggregates its local DNSBL evaluation statistics before transmission. It does not submit one telemetry HTTP request per lookup or page request.

Data minimization

Telemetry payloads may contain:

telemetry schema version
random batch ID used for idempotency
plugin version
reporting period start/end
aggregate DNSBL bitmask
aggregate listed/not-listed state
aggregate blocked/not-blocked decision
internal source category such as request, admin-request, or dry-run-request
aggregate count

Telemetry payloads must not contain:

queried or visitor IP addresses
target IP addresses
WordPress site URL or hostname
comments or raw submitted content
usernames or email addresses
raw DNS responses

Tools actively rejects telemetry JSON containing these privacy-forbidden fields.

The sending WordPress server's network IP address is still necessarily visible to Tools as part of the normal HTTPS connection. Normal Tools API request accounting may record that connection IP together with endpoint, status and authenticated token/user attribution. This is separate from the aggregate telemetry payload.

Token and user attribution

Tools authenticates the request with the existing active DNSBL token and stores the internal DNSBL token ID and token owner/user ID with the accepted batch. The raw token value is not stored inside telemetry rows.

Consent lifecycle

On first opt-in, the WordPress plugin moves its telemetry cursor to the current end of its local DNSBL statistics table. Statistics created before consent are not sent retroactively.

When the administrator disables telemetry:

the telemetry WP-Cron schedule is removed
any unsent pending telemetry batch is discarded
statistics produced while telemetry is disabled are not sent after a later re-enable

Tornevall Networks