Release: surblclient 0.2.0
A small Python library for checking domains against the SURBL, URIBL, and Spamhaus DBL spam blocklists.
SURBL, URIBL and Spamhaus DBL are DNS-based blocklists of domains that turn up in spam — you query them like RBLs, with a specially-formed DNS lookup, and decode the answer from the returned IP address. The devil is in the fiddly details, and surblclient wraps it all behind a small Python interface.
>>> from surblclient import surbl
>>> "test.surbl.org" in surbl
True
>>> surbl.lookup("test.surbl.org")
('test.surbl.org', ['ph', 'mw', 'abuse', 'cr'])
>>> "google.com" in surbl
False
It extracts the base domain for you — foo.bar.test.surbl.org is reduced correctly using a bundled public-suffix-style table — and uribl and spamhausdbl share the same interface.
lookup() has a tri-state signature – it returns a (domain, lists) tuple if listed, False if confirmed not listed, and None if it couldn’t tell. That third case is important:
result = surbl.lookup(domain)
if result is None:
... # couldn't check — don't treat as clean
elif result is False:
... # confirmed not listed
else:
base, lists = result
There’s an important caveat in this: these services can refuse queries from public/shared resolvers (Google, Cloudflare, Quad9, your ISP’s cache) as an anti-abuse measure. When that happens, every lookup comes back None. To actually use this reliably, you may need your own recursive resolver.
No dependencies, Python 3.10+, MIT, version 0.2.0. uv add surblclient (or pip install surblclient); source at codeberg.org/filipsalo/surblclient, package on PyPI.
Quick roadmap note: v0.1 was released in 2009 and v0.2.0 in 2026, so at the current pace v0.3.0 would land comfortably in the 2040s. Mark your calendar.