Spamhaus DNSBL return codes: technical update

Spamhaus' primary data sets are published in DNS zones known as DNSBLs. Users of that data ask the zone a question (a "query") and the zone provides a response - a return code - in the form of an IPv4 IP address within a designated range (RFC1918 internal network). The meaning of each of those particular IP responses may carry additional information to the querier. We post those return code values in our DNSBL Usage FAQ.

A new range containing return codes (127.255.255.0/24) has been added to return possible errors related to the DNSBL queries themselves, which should NOT be interpreted as any sort of reputation related to the data being queried. While it will be quite uncommon for most Spamhaus users to encounter these codes, it is vitally important that software developers implement all return codes correctly, and not treat these error codes as any sort of reputation or "listed" values. The first two new error codes, and links to pages further explaining their meaning, are:

Anyone that encounters either of those return codes should recognize that their queries are receiving error responses. Those responses must not be interpreted as advisories of Spamhaus reputation data regarding the object which was queried. Accordingly, any software which queries a Spamhaus DNSBL must distinguish between valid reputational responses and those error code responses. Any software which does not distinguish response codes from Spamhaus DNSBLs is, unfortunately, already out of date and may not be reliable in these or other cases. A common result of not correctly parsing DNSBL return codes is either treating all responses as either "LISTED," or treating them all as "NOT LISTED," and that means either all mail is treated by the indiscriminate software as "spam," or all mail is treated as "not spam." Neither result is desirable.

Failure to correctly parse these return codes will render the query results meaningless and detrimental for the querier. Here is information on how to correctly configure commonly used MTAs for use with our public mirrors.

These two return codes apply only to Spamhaus Project publicly queried zone mirrors. Clients of Spamhaus Technology DQS or rsync services will never encounter these return codes.