Skip to main content

Blocklist

The Blocklist endpoints let you check whether IP addresses are listed on the LimesIndex aggregated blocklist, view listing history, and monitor recent additions.

Single IP Check​

GET /v1/blocklist/ip/{ip}

Check if a single IP address is currently blocklisted.

Path Parameters​

ParameterTypeRequiredDescription
ipstringYesIPv4 or IPv6 address to check

Query Parameters​

ParameterTypeDefaultDescription
historystringfalseSet to true to include listing history

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"
    },
    "history": [
      {
        "action": "listed",
        "reason": "High volume spam sending detected",
        "performed_by": "auto",
        "performed_at": "2026-03-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)
historyarrayListing history events (only when ?history=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)

History Item​

FieldTypeDescription
actionstringAction performed (listed, delisted, extended)
reasonstringReason for the action
performed_bystringWho performed it (auto, manual)
performed_atstringISO 8601 timestamp

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 are silently skipped

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
    }
  },
  "meta": {
    "processing_time_ms": 5
  }
}
FieldTypeDescription
total_activeintegerTotal number of active listings
by_typeobjectActive listing count broken down by type

Recent Listings​

GET /v1/blocklist/recent

Get the most recent active blocklist entries (up to 50). Useful for monitoring new listings.

Response (200)​

{
  "data": [
    {
      "type": "spam",
      "reason": "High bounce rate",
      "return_code": "127.0.0.2",
      "listed_at": "2026-04-13T08:00:00Z"
    },
    {
      "type": "malware",
      "reason": "Malware distribution",
      "return_code": "127.0.0.3",
      "listed_at": "2026-04-13T07:45:00Z"
    }
  ],
  "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/blocklist/ip/192.0.2.1" \
  -H "X-API-Key: YOUR_API_KEY"

# With history
curl -X GET "https://api.limesindex.com/v1/blocklist/ip/192.0.2.1?history=true" \
  -H "X-API-Key: YOUR_API_KEY"

# 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 listings
curl -X GET "https://api.limesindex.com/v1/blocklist/recent" \
  -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/blocklist/ip/192.0.2.1", headers=HEADERS)
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 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