This is LEGACY

This document belongs to a legacy endpoint, no longer (or barely) in use.

Instead, we have a new section at this place DNSBL for ToolsAPI

However: To keep yourself really up to date, we are moving our docs to https://tools.tornevall.net/docs/dnsbl-api

Endpoint: dnsbl - DNSBL v5 with API v3

GDPR NOTICE

We used to snapshot the data that rendered the blacklist reason.

However, as of 25 May 2018, when the data protection law changed the history of personal integrity, we no longer store this kind of content. It might sound strange that we do not store spam that works like proof for why an e-mail has been blacklisted. It also normally helps system administrators, especially those who administer e-mail services, trace the source of spam. But to protect the receiver's data, the mail spam storage project has been abandoned.

API description, development and DNSBL docs

Permissions

Resolve first, use API last!
Before using the API to get a list of blacklisted hosts, read the best-practice section in the request documentation first:
DNSBLv5APIv3: GET/POST/PUT/DELETE requests

In the DNSBLv3 API, a new set of permissions is assigned to DNSBL. Normally, no permissions are required to list blacklisted hosts.

Requesting permissions?
Special permissions need to be requested manually via support@tornevall.net.

Permission flag	Description

Permission flag	Description
`allow_cidr`	The usage of CIDR blocks is normally not permitted by the DNSBL API, except in more functions than listing them. This permission also opens up usage in DELETE and UPDATE cases. However, adding data with CIDR and different flags might be a problem. This permission does not exist in the API yet.
`allow_cidr_update`	Setting that partially allows CIDR block updates for DNSBL. There might be limitations linked to this permission; see the documentation for more information. Current limitations: Not larger than a `/24`. This permission is also currently limited for internal use.
`can_purge`	Special ability to purge hosts instead of marking them deleted in the database.
`dnsbl_update`	Standard DNSBL ability to update data in DNSBL (`dnsbl.tornevall.org` and `bl.fraudbl.org`).
`fraudbl_update`	Extended ability to handle `fraudbl-commerce` (this is not the regular `bl.fraudbl.org` resolver).
`global_delist`	Global delisting permission, so the client can act as a delisting service for visitors.
`local_delist`	Local delisting permission, so a server can delist itself.
`overwrite_flags`	When sending new or updated data to DNSBL, clients can only add more flags to the host. This feature makes it possible to overwrite old flags. Not yet implemented.

DNSBL Version

The DNSBL system itself is still running on version 5.0. It is only the API that communicates with the system that has changed.

DNSBLv5APIv2

In DNSBLv5APIv2, a request for checking a listed IP looks like this:

Method	URL / data	Parameter	Expected response

Method	URL / data	Parameter	Expected response
`HTTP POST`	`<https://api.tornevall.net/2.0/dnsbl/ip/`>	—	—
`HTTP POST variables`	`?bulk[]=ipaddr1&bulk[]=ipaddr2`	`bulk[]=ipAddr`	Arrayed requests, or a single `bulk=ipAddr`, should return information about the currently blacklisted IP if it is blacklisted. To return fingerprints about the IP address, you could add `ipAddr\|e`, where `e` stands for extended information. To add or delete a host in the blacklist, additional parameters were used with the right permissions: `\|a\|<bitValue>` for insertion, `\|d` for deletion, and sometimes `p` to purge content.

Fingerprints are used to give API requesters more information about the address being evaluated.

DNSBLv5APIv3

In DNSBLv5APIv3, the request model is simplified.

`HTTP POST`

Purpose: check whether an IP is listed.

URLs:

<https://api.tornevall.net/3.0/dnsbl/>
<https://api.tornevall.com/3.0/dnsbl/request/ip/1.2.3.4>

Information:

HTTP POST has the same role as HTTP GET, but with POST parameters. IPv6 is supported.

Data examples:

{"ip":"1.2.3.4"}

&ip=1.2.3.4

{"ip":["1.2.3.4","5.6.7.8"]}

ip[]=1.2.3.4&ip[]=5.6.7.8

This example format is the same for the rest of the examples in this section.

`HTTP PUT`

Purpose: insert or update an IP address.

URL:

<https://api.tornevall.net/3.0/dnsbl/>

Data structure:

Field	Description

Field	Description
`ip`	Array with IP address and bitmasked flag-per-IP

The bitmask flags are described in DNSBLv5: About and usage.

Example request:

{
  "ip": {
    "10.10.10.10": 64
  },
  "type": "dnsbl"
}

Response parameters:

Field	Description

Field	Description
`success`	The insertion ID
`address`	The address that was updated or inserted
`state`	Defines whether the address was newly blacklisted or updated. Values can be `new` or `update`.
`arpaDelegations`	A list of DNS records that were registered or updated
`flag`	The flag of the blacklisted address

Example response:

{
  "dnsblResponse": {
    "status": [
      {
        "success": "1934699",
        "address": "10.10.10.10",
        "state": "new",
        "arpaDelegations": [
          "10.10.10.10.dnsbl.tornevall.org"
        ],
        "flag": "64"
      }
    ]
  }
}

`HTTP DELETE`

Purpose: delist, delete, or remove an IP address.

URL:

<https://api.tornevall.net/3.0/dnsbl/>

Example request:

{
  "ip": "1.2.3.4"
}

Registration types

The default type used in some of the examples above is the standard registration behaviour: dnsbl.

As fraudbl.org uses the same flag set, normally you do not need to know anything more than that. Adding a host with flag ID 4 (phishing) will also automatically update the FraudBL tables with proper data.

In the newer WordPress plugin, however, there is a supported method that includes ecommerce. The refresh rate for this method is much higher than for the normal host registry, and normally you want to use the API for this because DNS requests might be delayed.

The ecommerce method is specifically intended for fraud control in ecommerce sites, for example with ecommerce plugins that support fraud control. This method should be used with caution, since it may directly affect ecommerce sites. The hosts also have a shorter time to live and a supporting plugin should handle ecommerce unfreezing as well. In other words, if your site flags a host as fraudulent, it should also de-flag hosts when they are confirmed as non-fraudulent.

It should also be considered how to block website visitors, since orders flagged as fraud might deny access to websites instead of just order confirmations. However, the real purpose of this functionality is to block visitors from shopping if they are really being used for fraud, for example fraud customers visiting many shops at the same time to buy things before they are discovered. In such cases, the checkout should be rejected.

The type used for this scenario is ecommerce, and it is flagged differently from regular lookups.

Example:

{
  "ip": "1.2.3.4",
  "type": "ecommerce"
}

Endpoint: dnsbl - DNSBL v5 with API v3

This is LEGACY

Endpoint: dnsbl - DNSBL v5 with API v3

Table of contents

API description, development and DNSBL docs

Permissions

DNSBL Version

DNSBLv5APIv2

DNSBLv5APIv3

HTTP POST

HTTP PUT

HTTP DELETE

Registration types

`HTTP POST`

`HTTP PUT`

`HTTP DELETE`