Skip to main content

Blocklist

The Blocklist endpoints let you check whether IP addresses are listed on the LimesIndex-owned blocklist and monitor recent listing/delisting activity.

Single IP Check​

GET /v1/public/blocklist/ip/{ip}

Check if a single IP address is currently blocklisted. This public endpoint is rate-limited and does not require an API key. API-key clients can also use the authenticated /v1/blocklist/ip/{ip} route.

Path Parameters​

ParameterTypeRequiredDescription
ipstringYesIPv4 or IPv6 address to check

Response (200)​

{
  "data": {
    "ip": "192.0.2.1",
    "listed": true,
    "listing": {
      "type": "spam",
      "reason": "High volume spam sending detected",
      "return_code": "127.0.0.2",
      "listed_at": "2026-03-15T10:30:00Z",
      "expires_at": "2026-04-15T10:30:00Z"
    }
  },
  "meta": {
    "processing_time_ms": 3
  }
}

Response Fields​

Data Object​

FieldTypeDescription
ipstringThe checked IP address (normalized)
listedbooleanWhether the IP is currently blocklisted
listingobjectActive listing details (only present when listed is true)

Listing Object​

FieldTypeDescription
typestringListing type (spam, malware, phishing)
reasonstringHuman-readable reason for the listing
return_codestringDNS return code for the listing
listed_atstringISO 8601 timestamp when the IP was listed
expires_atstringExpiration timestamp (null if permanent)

Batch Check​

POST /v1/blocklist/check

Check multiple IP addresses against the blocklist in a single request. Maximum 100 IPs.

Request Body​

{
  "ips": ["192.0.2.1", "198.51.100.5", "203.0.113.10"]
}

Response (200)​

{
  "data": [
    {
      "ip": "192.0.2.1",
      "listed": true,
      "listing": {
        "type": "spam",
        "reason": "High volume spam sending detected",
        "return_code": "127.0.0.2",
        "listed_at": "2026-03-15T10:30:00Z"
      }
    },
    {
      "ip": "198.51.100.5",
      "listed": false
    },
    {
      "ip": "203.0.113.10",
      "listed": false
    }
  ],
  "meta": {
    "processing_time_ms": 8
  }
}

Limits​

  • Maximum 100 IPs per request
  • Invalid IPs return 400 INVALID_IP; the response identifies the invalid input

Statistics​

GET /v1/blocklist/stats

Get aggregate statistics about current blocklist entries.

Response (200)​

{
  "data": {
    "total_active": 4523,
    "by_type": {
      "spam": 3200,
      "malware": 800,
      "phishing": 523
    },
    "new_listings_24h": 92,
    "delistings_24h": 17
  },
  "meta": {
    "processing_time_ms": 5
  }
}
FieldTypeDescription
total_activeintegerTotal number of active listings
by_typeobjectActive listing count broken down by type
new_listings_24hintegerNumber of listing events in the last 24 hours
delistings_24hintegerNumber of delisting events in the last 24 hours

Recent Events​

GET /v1/blocklist/recent

Get recent listing and delisting events. Results are ordered newest first and paginated.

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Number of events to return, capped at 100
offsetinteger0Number of events to skip

Response (200)​

{
  "data": {
    "events": [
      {
        "ip": "192.0.2.1",
        "action": "listed",
        "type": "spam",
        "reason": "High bounce rate",
        "return_code": "127.0.0.2",
        "listed_at": "2026-04-13T08:00:00Z",
        "expires_at": "2026-04-14T08:00:00Z",
        "performed_at": "2026-04-13T08:00:00Z"
      },
      {
        "ip": "198.51.100.5",
        "action": "delisted",
        "type": "malware",
        "reason": "false positive",
        "return_code": "127.0.0.4",
        "listed_at": "2026-04-12T07:45:00Z",
        "delisted_at": "2026-04-13T07:45:00Z",
        "performed_at": "2026-04-13T07:45:00Z"
      }
    ],
    "count": 2,
    "limit": 50,
    "offset": 0
  },
  "meta": {
    "processing_time_ms": 4
  }
}

Error Responses​

400 Bad Request​

{
  "data": {
    "error": "invalid IP address",
    "code": "INVALID_IP"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

400 Too Many IPs (Batch)​

{
  "data": {
    "error": "maximum 100 IPs per request",
    "code": "TOO_MANY_IPS"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

Code Examples​

cURL​

# Single IP check
curl -X GET "https://api.limesindex.com/v1/public/blocklist/ip/192.0.2.1"

# Batch check
curl -X POST "https://api.limesindex.com/v1/blocklist/check" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["192.0.2.1", "198.51.100.5"]}'

# Statistics
curl -X GET "https://api.limesindex.com/v1/blocklist/stats" \
  -H "X-API-Key: YOUR_API_KEY"

# Recent listing/delisting events
curl -X GET "https://api.limesindex.com/v1/blocklist/recent?limit=50&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

Python​

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.limesindex.com"
HEADERS = {"X-API-Key": API_KEY}

# Check single IP
resp = requests.get(f"{BASE_URL}/v1/public/blocklist/ip/192.0.2.1")
result = resp.json()
if result["data"]["listed"]:
    listing = result["data"]["listing"]
    print(f"Listed: {listing['type']} - {listing['reason']}")

# Batch check a pool of IPs
pool = ["192.0.2.1", "198.51.100.5", "203.0.113.10"]
resp = requests.post(
    f"{BASE_URL}/v1/blocklist/check",
    headers=HEADERS,
    json={"ips": pool}
)
for item in resp.json()["data"]:
    status = "LISTED" if item["listed"] else "clean"
    print(f"{item['ip']}: {status}")

Use Cases​

  • Pre-send check: Verify IPs before starting an email campaign
  • Monitoring: Poll /v1/blocklist/recent to detect new listings and delistings in your pool
  • Pool health: Batch-check your entire sending pool to identify contaminated IPs
  • Email Reputation - Full reputation scoring beyond blocklist status
  • Warmup - Warm-up guidance that factors in blocklist state