IP Pools

Enterprise customers, contact your TAM for details.

IP Pool Object

Example

{
  "id": "marketing_ip_pool",
  "name": "Marketing IP Pool",
  "signing_domain": "example.com",
  "fbl_signing_domain": "sparkpostmail.com",
  "ips": [
    {
      "external_ip": "54.244.54.135",
      "hostname": "mta472a.sparkpostmail.com",
      "auto_warmup_enabled": true,
      "auto_warmup_stage": 5
    }
  ],
  "auto_warmup_overflow_pool": "overflow_pool"
}

Request Body

id string

Unique pool identifier used through the Transmissions API and SMTP. Auto-generated when created.

name string

Name of the IP Pool

signing_domain string

DKIM-verified signing domain

fbl_signing_domain string

FBL Signing Domain for the pool. Used only for emails to domains that require DKIM for FBL.

ips array of objects

Sending IPs within the pool. Sending IP objects include fields external_ip,hostname, auto_warmup_enabled & auto_warmup_stage

auto_warmup_overflow_pool string

IP Pool ID to be used as an overflow pool during auto IP warmup. Can specify shared pool to overflow to the SparkPost Shared Pool if you have access.
The auto_warmup_overflow_pool shared pool is not available for Enterprise customers

Request

POST /api/v1/ip-pools

{
  "name": "Marketing IP Pool",
  "fbl_signing_domain": "sparkpostmail.com",
  "auto_warmup_overflow_pool": "overflow_pool"
}

Response

{
  "results": {
    "id": "marketing_ip_pool"
  }
}

{
  "errors": [
    {
      "message": "Auto Warmup Overflow Pool overflow_pool does not exist."
    }
  ]
}

{
  "errors": [
    {
      "message": "overflow_pool has an overflow pool and cannot be an overflow pool"
    }
  ]
}

Create an IP Pool

POST/api/v1/ip-pools

Creates an IP Pool and returns a unique ID based on the name. This ID is used for sending with this pool.

Request Body

name string required

Name of the IP Pool

signing_domain string

Domain to use as the DKIM verified signing domain

fbl_signing_domain string

FBL Signing Domain for the pool

auto_warmup_overflow_pool string

Request

GET /api/v1/ip-pools/marketing_ip_pool

Response

{
  "results": {
    "id": "marketing_ip_pool",
    "name": "Marketing IP Pool",
    "fbl_signing_domain": "sparkpostmail.com",
    "ips": [
      {
        "external_ip": "54.244.54.135",
        "hostname": "mta472a.sparkpostmail.com",
        "auto_warmup_enabled": true,
        "auto_warmup_stage": 5
      },
      {
        "external_ip": "54.244.54.137",
        "hostname": "mta474a.sparkpostmail.com",
        "auto_warmup_enabled": false
      }
    ],
    "signing_domain": "example.com",
    "auto_warmup_overflow_pool": "overflow_pool"
  }
}

{
  "errors": [
    {
      "message": "IP pool not found."
    }
  ]
}

Retrieve an IP Pool

GET/api/v1/ip-pools/{id}

Parameters

id string required

Returns a specific IP Pool.

Request

PUT /api/v1/ip-pools/marketing

{
  "name": "Updated Marketing Pool",
  "fbl_signing_domain": "sparkpostmail.com",
  "auto_warmup_overflow_pool": "overflow_pool"
}

Response

{
  "results": {
    "name": "Updated Marketing Pool",
    "fbl_signing_domain": "sparkpostmail.com",
    "id": "marketing",
    "auto_warmup_overflow_pool": "overflow_pool"
  }
}

{
  "errors": [
    {
      "message": "IP Pool default is reserved and cannot be updated."
    }
  ]
}

{
  "errors": [
    {
      "message": "Auto Warmup Overflow Pool overflow_pool does not exist."
    }
  ]
}

{
  "errors": [
    {
      "message": "overflow_pool has an overflow pool and cannot be an overflow pool"
    }
  ]
}

{
  "errors": [
    {
      "message": "overflow_pool is an overflow pool and cannot have an overflow pool"
    }
  ]
}

{
  "errors": [
    {
      "message": "IP Pool not_a_real_pool does not exist."
    }
  ]
}

Update an IP Pool

PUT/api/v1/ip-pools/{id}

Parameters

id string required

Request Body

name string required

Name of the IP Pool

signing_domain string

Domain to use as the DKIM verified signing domain. To remove it, set it to an empty string.

fbl_signing_domain string

FBL Signing Domain for the pool. To remove it, set it to an empty string.

auto_warmup_overflow_pool string

To update sending IP pool assignments see Sending IPs.

Request

DELETE /api/v1/ip-pools/marketing

Response

// Empty response body

{
  "errors": [
    {
      "message": "IP Pool default is reserved."
    }
  ]
}

{
  "errors": [
    {
      "message": "IP Pool marketing does not exist."
    }
  ]
}

Delete an IP Pool

DELETE/api/v1/ip-pools/{id}

Parameters

id string required

Deletes an IP Pool and moves all sending IPs in that pool to the default pool. The default pool cannot be deleted.

Request

GET /api/v1/ip-pools

Response

{
  "results": [
    {
      "id": "marketing_ip_pool",
      "name": "Marketing IP Pool",
      "ips": [],
      "signing_domain": "example.com",
      "fbl_signing_domain": "sparkpostmail.com",
      "auto_warmup_overflow_pool": "overflow_pool"
    },
    {
      "id": "default",
      "name": "Default",
      "ips": [
        {
          "external_ip": "54.244.54.135",
          "hostname": "mta472a.sparkpostmail.com",
          "auto_warmup_enabled": true,
          "auto_warmup_stage": 5
        }
      ]
    }
  ]
}

List IP Pools

GET/api/v1/ip-pools

Returns a list of all your IP Pools.