Skip to main content

Email Reputation

The Email Reputation endpoints provide sending IP reputation scoring based on trap hits, blocklist status, telemetry signals, and behavioral analysis. Scores range from 0 (worst) to 100 (best).

Single IP Reputation​

GET /v1/email/ip/{ip}/reputation

Get the full sending reputation for an IP, including contributing factors, 30-day history, and subnet context.

Path Parameters​

ParameterTypeRequiredDescription
ipstringYesIPv4 or IPv6 address

Response (200)​

{
  "data": {
    "ip": "198.51.100.25",
    "score": 78,
    "level": "good",
    "factors": [
      {
        "name": "volume_consistency",
        "impact": 10,
        "detail": "Consistent sending volume over 30 days"
      },
      {
        "name": "blocklist_free",
        "impact": 15,
        "detail": "No active blocklist entries"
      },
      {
        "name": "complaint_rate",
        "impact": -5,
        "detail": "Complaint rate slightly above threshold"
      }
    ],
    "history": [
      {
        "score": 75,
        "level": "good",
        "computed_at": "2026-04-12T00:00:00Z"
      },
      {
        "score": 72,
        "level": "good",
        "computed_at": "2026-04-11T00:00:00Z"
      }
    ],
    "subnet": {
      "subnet": "198.51.100.0/24",
      "total_ips_seen": 12,
      "listed_count": 1,
      "avg_reputation": 65,
      "worst_score": 30,
      "contamination_level": "light"
    }
  },
  "meta": {
    "processing_time_ms": 12
  }
}

Response Fields​

Data Object​

FieldTypeDescription
ipstringThe queried IP address (normalized)
scoreintegerReputation score (0-100)
levelstringHuman-readable level
factorsarrayFactors contributing to the score
historyarray30-day score history
subnetobjectSubnet reputation context

Factor Object​

FieldTypeDescription
namestringFactor identifier
impactintegerPositive or negative impact on the score
detailstringHuman-readable explanation

History Point​

FieldTypeDescription
scoreintegerScore at that point
levelstringLevel at that point
computed_atstringISO 8601 timestamp

Score Ranges​

ScoreLevelDescription
80-100goodHealthy sender reputation
50-79mediumSome risk signals detected
20-49poorMultiple negative signals
0-19criticalSevere reputation issues

Batch Reputation​

POST /v1/email/reputation/batch

Get reputation scores for multiple IPs in a single request. Returns score and level for each IP.

Request Body​

{
  "ips": ["198.51.100.25", "203.0.113.50"]
}

Maximum 100 IPs per request.

Response (200)​

{
  "data": [
    {
      "ip": "198.51.100.25",
      "score": 78,
      "level": "good"
    },
    {
      "ip": "203.0.113.50",
      "score": 50,
      "level": "neutral"
    }
  ],
  "meta": {
    "processing_time_ms": 20
  }
}

Limits​

  • Maximum 100 IPs per request
  • Invalid IPs are silently skipped
  • If reputation data is unavailable for an IP, defaults to score 50 / level "neutral"

Subnet Neighbors​

GET /v1/email/ip/{ip}/neighbors

Analyze the /24 subnet reputation around an IP address. Shows how many neighbors are listed and the overall contamination level. Useful for understanding whether an IP is in a "bad neighborhood."

Path Parameters​

ParameterTypeRequiredDescription
ipstringYesIPv4 or IPv6 address

Response (200)​

{
  "data": {
    "subnet": "198.51.100.0/24",
    "total_ips_seen": 12,
    "listed_count": 1,
    "avg_reputation": 65,
    "worst_score": 30,
    "contamination_level": "light"
  },
  "meta": {
    "processing_time_ms": 8
  }
}

Response Fields​

FieldTypeDescription
subnetstringThe /24 subnet in CIDR notation
total_ips_seenintegerTotal IPs observed in this subnet
listed_countintegerNumber of IPs currently blocklisted
avg_reputationintegerAverage reputation score in the subnet
worst_scoreintegerLowest reputation score in the subnet
contamination_levelstringOverall level: clean, light, moderate, heavy

Contamination Levels​

LevelDescription
cleanNo blocklisted IPs in the subnet
light1-2 listed IPs, low risk to neighbors
moderateMultiple listed IPs, some risk of guilt-by-association
heavyMany listed IPs, significant shared-IP risk

Error Responses​

400 Bad Request​

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

Code Examples​

cURL​

# Single IP reputation
curl -X GET "https://api.limesindex.com/v1/email/ip/198.51.100.25/reputation" \
  -H "X-API-Key: YOUR_API_KEY"

# Batch reputation
curl -X POST "https://api.limesindex.com/v1/email/reputation/batch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["198.51.100.25", "203.0.113.50"]}'

# Subnet neighbors
curl -X GET "https://api.limesindex.com/v1/email/ip/198.51.100.25/neighbors" \
  -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}

# Get reputation for an IP
resp = requests.get(
    f"{BASE_URL}/v1/email/ip/198.51.100.25/reputation",
    headers=HEADERS
)
data = resp.json()["data"]
print(f"Score: {data['score']} ({data['level']})")
for factor in data["factors"]:
    sign = "+" if factor["impact"] > 0 else ""
    print(f"  {sign}{factor['impact']} {factor['name']}: {factor['detail']}")

# Check subnet health
resp = requests.get(
    f"{BASE_URL}/v1/email/ip/198.51.100.25/neighbors",
    headers=HEADERS
)
subnet = resp.json()["data"]
print(f"Subnet: {subnet['subnet']}")
print(f"Contamination: {subnet['contamination_level']}")
print(f"Listed neighbors: {subnet['listed_count']}/{subnet['total_ips_seen']}")

Use Cases​

  • Pre-campaign assessment: Check your sending IPs' reputation before a campaign
  • IP rotation decisions: Identify which IPs in your pool need rest or removal
  • Subnet risk: Understand shared-IP contamination risk before purchasing new IPs
  • Trend monitoring: Track reputation history to detect degradation early