Skip to main content

Warmup & Pool Classification

The Warmup endpoints help manage IP warm-up schedules and classify IPs into sending pool tiers based on reputation, warm-up progress, and blocklist state.

Warm-Up Status​

GET /v1/email/ip/{ip}/warmup

Get warm-up advisor data for an IP. Returns the current warm-up status, recommended daily volume, and guidance on whether to pause sending.

Path Parameters​

ParameterTypeRequiredDescription
ipstringYesIPv4 or IPv6 address

Response (200)​

{
  "data": {
    "ip": "198.51.100.25",
    "status": "warming",
    "days_sending": 14,
    "reputation_score": 72,
    "recommended_daily_volume": 200,
    "auto_pause_recommended": false,
    "next_milestone": "2026-04-28",
    "next_milestone_volume": 500
  },
  "meta": {
    "processing_time_ms": 10
  }
}

Response Fields​

FieldTypeDescription
ipstringThe IP address (normalized)
statusstringCurrent warm-up status
days_sendingintegerDays since first observed sending activity
reputation_scoreintegerCurrent reputation score (0-100)
recommended_daily_volumeintegerRecommended max daily send volume
auto_pause_recommendedbooleanWhether sending should be paused
auto_pause_reasonstringReason for pause (when applicable)
next_milestonestringDate of next volume increase (YYYY-MM-DD)
next_milestone_volumeintegerVolume at the next milestone

Warm-Up Statuses​

StatusDescription
coldNo observed sending activity
warmingActive warm-up in progress (days 1-30)
warmPast initial warm-up, good reputation (days 30-90, score 60+)
establishedFully established sender (90+ days, score 60+)
damagedBlocklisted or reputation score below 30

Volume Ramp Schedule​

The recommended volume follows a standard warm-up ramp:

DaysRecommended Volume
1-750/day
8-14200/day
15-21500/day
22-301,000/day
31-452,500/day
46-605,000/day
61-9010,000/day
91+50,000/day

Volume is further adjusted based on reputation score:

  • Score below 50: volume halved
  • Score below 40: volume quartered
  • Listed or score below 30: volume set to 0 (do not send)

Auto-Pause Conditions​

The system recommends pausing when:

  • Reputation score falls below 40
  • IP is actively blocklisted

Pool Classification​

POST /v1/email/pool/classify

Classify a set of IPs into pool tiers based on their reputation, warm-up status, and blocklist state. Maximum 50 IPs per request.

Request Body​

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

Response (200)​

{
  "data": [
    {
      "ip": "198.51.100.25",
      "tier": "seasoned",
      "reputation_score": 78,
      "warmup_status": "warm",
      "listed": false,
      "recommendation": "IP has good reputation and is past warm-up \u2014 ready for the main sending pool"
    },
    {
      "ip": "203.0.113.50",
      "tier": "probation",
      "reputation_score": 45,
      "warmup_status": "warming",
      "listed": false,
      "recommendation": "IP needs more warm-up time and reputation building before joining the main pool"
    },
    {
      "ip": "192.0.2.100",
      "tier": "suspend",
      "reputation_score": 20,
      "warmup_status": "damaged",
      "listed": true,
      "recommendation": "IP is blocklisted or reputation is critically low \u2014 remove from sending pool"
    }
  ],
  "meta": {
    "processing_time_ms": 35
  }
}

Response Fields (per IP)​

FieldTypeDescription
ipstringThe IP address
tierstringAssigned pool tier
reputation_scoreintegerCurrent reputation score
warmup_statusstringCurrent warm-up status
listedbooleanWhether the IP is blocklisted
recommendationstringHuman-readable recommendation

Pool Tiers​

TierCriteriaAction
dedicated_candidateScore 80+, established/warm, volume 5000+Eligible for dedicated IP assignment
seasonedScore 70+, warm or establishedReady for the main sending pool
probationScore < 60, cold, or warmingNeeds more warm-up before main pool
suspendListed or score < 30Remove from sending pool immediately

Limits​

  • Maximum 50 IPs per request
  • Invalid IPs are silently skipped
  • If reputation data is unavailable, defaults to probation tier

Error Responses​

400 Bad Request​

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

400 Too Many IPs​

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

Code Examples​

cURL​

# Warm-up status
curl -X GET "https://api.limesindex.com/v1/email/ip/198.51.100.25/warmup" \
  -H "X-API-Key: YOUR_API_KEY"

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

Python​

import requests

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

# Check warm-up status for a new IP
resp = requests.get(
    f"{BASE_URL}/v1/email/ip/198.51.100.25/warmup",
    headers=HEADERS
)
warmup = resp.json()["data"]
print(f"Status: {warmup['status']}")
print(f"Days sending: {warmup['days_sending']}")
print(f"Recommended volume: {warmup['recommended_daily_volume']}/day")
if warmup["auto_pause_recommended"]:
    print(f"PAUSE RECOMMENDED: {warmup['auto_pause_reason']}")
else:
    print(f"Next milestone: {warmup['next_milestone']} ({warmup['next_milestone_volume']}/day)")

# Classify your entire pool
pool_ips = ["198.51.100.25", "203.0.113.50", "192.0.2.100"]
resp = requests.post(
    f"{BASE_URL}/v1/email/pool/classify",
    headers=HEADERS,
    json={"ips": pool_ips}
)
for item in resp.json()["data"]:
    print(f"{item['ip']}: tier={item['tier']} score={item['reputation_score']}")
    print(f"  {item['recommendation']}")

Use Cases​

  • Automated warm-up: Use recommended_daily_volume to throttle sending during IP warm-up
  • Pool management: Classify IPs daily to route traffic to healthy IPs and rest damaged ones
  • Dedicated IP promotion: Identify IPs ready for dedicated assignment to high-value customers
  • Incident response: Quickly identify which IPs need suspension after a reputation event
  • New IP onboarding: Monitor cold IPs as they progress through the warm-up schedule