Skip to main content

IP Pool Management Guide

IP pools allow you to manage dedicated IP addresses for email sending, providing better control over deliverability and sender reputation.

Overview​

IP pools enable you to:

  • Segment traffic - Separate transactional and marketing emails
  • Protect reputation - Isolate different email types
  • Scale sending - Distribute load across multiple IPs
  • Warm up IPs - Gradually increase volume on new IPs

Supported Providers​

Currently, IP pools are supported for:

ProviderPool ID Format
SparkPostCustom pool name

Create an IP Pool​

Endpoint​

POST /v1/ip-pool/add

Purpose​

Creates a new IP pool for organizing and managing dedicated IP addresses.

Request Body​

FieldTypeRequiredDescription
providerstring✅ YesEmail service provider. Currently supported: "sparkpost"
pool_idstring✅ YesUnique identifier for the pool. Use descriptive names like "transactional", "marketing", "priority"

Example Request​

curl -X POST https://api.sparrowmailer.com/v1/ip-pool/add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "sparkpost",
    "pool_id": "transactional-emails"
  }'

Response​

{
  "success": true,
  "message": "IP pool created successfully",
  "data": {
    "pool_id": "transactional-emails",
    "provider": "sparkpost",
    "created_at": "2024-01-15T10:30:00Z",
    "details": {}
  }
}

Get an IP Pool​

Endpoint​

GET /v1/ip-pool/get

Purpose​

Retrieves details of a specific IP pool.

Query Parameters​

ParameterTypeRequiredDescription
providerstring✅ YesThe provider name (e.g., "sparkpost")
pool_idstring✅ YesThe pool identifier

Example Request​

curl -X GET "https://api.sparrowmailer.com/v1/ip-pool/get?provider=sparkpost&pool_id=transactional-emails" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response​

{
  "success": true,
  "message": "IP pool retrieved successfully",
  "data": {
    "pool_id": "transactional-emails",
    "provider": "sparkpost",
    "created_at": "2024-01-15T10:30:00Z",
    "deleted_at": null,
    "details": {
      "ips": ["192.168.1.1", "192.168.1.2"],
      "status": "active"
    }
  }
}

List IP Pools​

Endpoint​

GET /v1/ip-pool/list

Purpose​

Retrieves a paginated list of all IP pools, optionally filtered by provider.

Query Parameters​

ParameterTypeRequiredDescription
providerstringNoFilter pools by provider
page_tokenstringNoPagination token for next page

Example Request - All Pools​

curl -X GET "https://api.sparrowmailer.com/v1/ip-pool/list" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Request - Filter by Provider​

curl -X GET "https://api.sparrowmailer.com/v1/ip-pool/list?provider=sparkpost" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response​

{
  "success": true,
  "message": "IP pools listed successfully",
  "data": {
    "ip_pools": [
      {
        "pool_id": "transactional-emails",
        "provider": "sparkpost",
        "created_at": "2024-01-15T10:30:00Z",
        "details": {}
      },
      {
        "pool_id": "marketing-campaigns",
        "provider": "sparkpost",
        "created_at": "2024-01-10T08:00:00Z",
        "details": {}
      }
    ],
    "next_page_token": null,
    "total_count": 2
  }
}

Delete an IP Pool​

Endpoint​

DELETE /v1/ip-pool/delete

Purpose​

Permanently deletes an IP pool.

⚠️ Warning: Ensure no active sending configurations use this pool before deletion.

Query Parameters​

ParameterTypeRequiredDescription
providerstring✅ YesThe provider name
pool_idstring✅ YesThe pool identifier to delete

Example Request​

curl -X DELETE "https://api.sparrowmailer.com/v1/ip-pool/delete?provider=sparkpost&pool_id=old-pool" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response​

{
  "success": true,
  "message": "IP pool deleted successfully"
}

Using IP Pools When Sending​

Reference an IP pool in the email send request:

curl -X POST https://api.sparrowmailer.com/v1/email/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "notifications@mail.yourcompany.com",
      "name": "YourCompany"
    },
    "to": [
      { "email": "recipient@example.com" }
    ],
    "subject": "Order Confirmation",
    "content": [
      { "type": "text/html", "value": "<p>Your order is confirmed!</p>" }
    ],
    "mailer_id": "domain_01JC3BBW8S9YGX2VNKG5MD7BTA",
    "settings": {
      "ip_pool": "transactional-emails",
      "open_tracking": { "enable": true }
    }
  }'

Best Practices​

1. Segment by Email Type​

Create separate pools for different email categories:

Pool NameUse Case
transactionalPassword resets, order confirmations, receipts
marketingNewsletters, promotions, announcements
onboardingWelcome series, user activation
alertsSecurity alerts, system notifications

2. IP Warming​

When using new IPs:

  • Start with low volume (50-100 emails/day)
  • Gradually increase over 2-4 weeks
  • Focus on engaged recipients initially
  • Monitor deliverability metrics

Warming Schedule Example:

WeekDaily Volume
150-100
2200-500
31,000-2,000
45,000-10,000
5+Production volume

3. Monitor Reputation​

Track metrics per pool:

  • Bounce rates
  • Spam complaints
  • Inbox placement
  • Engagement rates

4. Fallback Strategy​

If a pool's reputation degrades:

  • Temporarily route to a different pool
  • Investigate and fix the cause
  • Re-warm if necessary

Common Errors​

ErrorCauseSolution
IP pool already existsPool ID is takenUse a unique pool_id
IP pool not foundInvalid pool_id or providerVerify the pool exists
Invalid providerUnsupported providerUse a supported provider
Pool in usePool is referenced by sending configsUpdate configs before deleting