Integrations

Connect vspam.org to your infrastructure using the DNSBL, REST API, or threat feeds. Configuration snippets are provided for the most common mail servers and security tools. If you are designing policy around feeds, start with our pages on domain reputation, IPv6 intelligence, and ASN reputation.

1 · Your platform

2 · How much of it

One line in your resolver. No account, nothing to install, and it checks the connecting IP and the sender.

The DNSBL path is three lines in main.cf. The agent adds policy delegation, a local cache, and reporting.

3 · The file

smtpd_recipient_restrictions =
  ...
  reject_rbl_client dnsbl.vspam.org

4 · Check it worked

dig +short 19.72.234.185.dnsbl.vspam.org
# 127.0.0.2 means listed as phishing; no answer means not listed

Blocking something you should not be? Delist requests are reviewed by a human within 48 hours, need no account, and are tracked publicly by ID. Check what we hold on a host first with lookup.

More Than One Server

The builder above configures one host. For a fleet there is an Ansible role that installs the agent from the signed package repository, writes its config, starts it, waits until it actually answers, and — if you ask it to — points Postfix at it with a failure mode that lets mail through rather than deferring it.

git clone https://github.com/vspam-org/integrations
cd integrations/ansible
cp inventory.example.ini inventory.ini   # edit
ansible-playbook -i inventory.ini playbook.yml

Idempotent, so it is safe in a nightly run. Debian, Ubuntu, RHEL, Rocky and Alma. Role and variables.

DNSBL Return Codes

Each zone answers with a code describing why an indicator is listed. Matching anywhere in 127.0.0.0/8 on dnsbl.vspam.org treats every listing alike and always sees the whole list — that is the safe default and what most operators should use. The category subzones below are filtered views of that same list, so a subzone only returns anything for indicators observed in that category; several categories are defined here but sparsely populated or empty today, and querying one of those is not a fault, it is an empty answer. Phishing is by far the largest category.

Adding a subzone check gains you nothing over the main zone unless you intend to score that category differently.

Security Tools

# /etc/fail2ban/action.d/vspam.conf
[Definition]
actionban = curl -s -X POST https://api.vspam.org/api/v1/reports \
  -H "X-API-Key: <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"ioc_type":"ip","ioc_value":"<ip>","category":"spam","evidence":"Fail2Ban: <name> jail"}'

# Download and apply IPv6 exact-host blocklist
curl -s -H "X-API-Key: <KEY>" https://api.vspam.org/api/v1/feeds/ipv6-exact-host-malicious/csv \
  | tail -n +2 | cut -d',' -f2 | grep ':' \
  | while read ip; do iptables -A INPUT -s "$ip" -j DROP; done

Threat Feeds

Pull operator-focused feeds for phishing domains, exact IPv6 hosts, IPv6 prefix watch, and ASN abuse density in structured formats for OpenCTI, MISP, SIEM, or custom pipelines. CSV, JSON, and plain-text downloads are public. STIX and MISP are Pro, and TAXII is Enterprise.

API Quick Start

Common curl examples — replace <KEY> with your API key from the account page.

# Check an IP
curl https://api.vspam.org/api/v1/rbl/check?ip=192.0.2.1

# Check a phishing domain
curl "https://api.vspam.org/api/v1/public/operator-lookup?type=domain&value=login-paypa1.com"

# Check ASN reputation context
curl "https://api.vspam.org/api/v1/public/operator-lookup?type=asn&value=AS13335"

# Search reports
curl https://api.vspam.org/api/v1/public/reports?q=example.com

# Submit a phishing report (URLs normalize to canonical domains at ingest)
curl -X POST https://api.vspam.org/api/v1/reports \
  -H "X-API-Key: <KEY>" \
  -d '{"ioc_type":"url","ioc_value":"https://phish.example.com","category":"phishing"}'

SDK Examples

Query the vspam.org API from your application. Replace <KEY> with your API key.

import requests

API = "https://api.vspam.org/api/v1"
KEY = "<KEY>"

# Check a phishing domain
domain_lookup = requests.get(
    f"{API}/public/operator-lookup",
    params={"type": "domain", "value": "login-paypa1.com"},
)
print(domain_lookup.json())

# Check an exact IPv6 host
ipv6_lookup = requests.get(
    f"{API}/rbl/check",
    params={"ip": "2001:db8::42"},
)
print(ipv6_lookup.json())

# Submit a report
requests.post(f"{API}/reports",
    headers={"X-API-Key": KEY},
    json={"ioc_type": "url",
          "ioc_value": "https://phish.example.com",
          "category": "phishing"})

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    domainResp, _ := http.Get(
        "https://api.vspam.org/api/v1/public/operator-lookup?type=domain&value=login-paypa1.com")
    defer domainResp.Body.Close()
    domainBody, _ := io.ReadAll(domainResp.Body)
    fmt.Println(string(domainBody))

    ipResp, _ := http.Get(
        "https://api.vspam.org/api/v1/rbl/check?ip=2001:db8::42")
    defer ipResp.Body.Close()
    ipBody, _ := io.ReadAll(ipResp.Body)
    fmt.Println(string(ipBody))
}

const API = "https://api.vspam.org/api/v1";
const KEY = "<KEY>";

// Check a canonical domain
const domainRes = await fetch(
  `${API}/public/operator-lookup?type=domain&value=login-paypa1.com`);
console.log(await domainRes.json());

// Check an exact IPv6 host
const ipv6Res = await fetch(
  `${API}/rbl/check?ip=2001:db8::42`);
console.log(await ipv6Res.json());

// Submit a report
await fetch(`${API}/reports`, {
  method: "POST",
  headers: {
    "X-API-Key": KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ioc_type: "domain",
    ioc_value: "phish.example.com",
    category: "phishing",
  }),
});

$api = "https://api.vspam.org/api/v1"

# Check a phishing domain
Invoke-RestMethod "$api/public/operator-lookup?type=domain&value=login-paypa1.com"

# Check an exact IPv4 or IPv6 host
Invoke-RestMethod "$api/rbl/check?ip=192.0.2.1"

# Submit a report
$headers = @{ "X-API-Key" = "<KEY>" }
$body = @{
    ioc_type  = "ip"
    ioc_value = "185.234.72.19"
    category  = "spam"
} | ConvertTo-Json

Invoke-RestMethod "$api/reports" `
    -Method Post -Headers $headers `
    -Body $body -ContentType "application/json"

Say So On Your Site

A public SVG endpoint, no key needed, cached for an hour. Reporters get a second badge carrying their confirmed count — the snippet is on your account.

[![protected by vspam.org](https://api.vspam.org/api/v1/badge/protected.svg)](https://vspam.org/)