Dynamic IP Pools

Dynamic IP Pools allow you to group your dedicated IPs into customized "pools" based on sender reputation. Domains enrolled in Dynamic IP Pools will be assigned to a pool based on the result of periodic health checks.

Enroll domain

post/v3/domains/{name}/dynamic_pools

Domains enrolled in the Dynamic IP pools feature will be assigned an IP pool based on reputation. The feature must be enabled and configured before enrolling domains.

SecuritybasicAuth
Request
path Parameters
name
required
string

Domain name. Converted to X-Mailgun-Domain-Id header by the middleware.

query Parameters
replacement_ip
required
string

A valid IP address or 'shared'

header Parameters
X-Mailgun-Account-Id
required
string

Account ID

X-Mailgun-Requestor
required
string

Email address of the user making the request.

X-Mailgun-Requestor-Client
required
string

Identifier of the client application making the request.

Responses
200

A 200 response

Response Schema: application/json
message
required
string

Response message

Request samples 
Response samples 
application/json
{
  • "message": "success"
}
Remove domain from dynamic IP pools
delete/v3/domains/{name}/dynamic_pools
The behavior of this endpoint depends on the value of the replacement_ip and replacement_pool_id parameters.
One of these parameters (but not both) must be provided. If replacement_ip is provided, the IP(s) will be assigned to the domain.
replacement_ip can include one of the following:


    

  • valid IP(s): this IP address or addresses will be added to the domain
    • 

  • string shared: if the account is eligible for shared IPs, a suitable shared IP will be chosen and added to the domain
The 'replacement_ip' parameter cannot include any IPs that are already assigned to a Dedicated IP Pool or a Dynamic IP Pool.
If replacement_pool_id is provided, the Dedicated IP Pool will be assigned to the domain.
    • 



SecuritybasicAuth 
Request 
path Parameters
name
required
string
Domain name


 
query Parameters
replacement_ip
required
string
A valid IP address or 'shared'. This field can be specified multiple times if all provided IPs are dedicated. Cannot not be provided if providing 'replacement_pool_id' param


 
replacement_pool_id
required
string
A valid dedicated IP pool ID to assign to the domain. Cannot not be provided if providing 'replacement_ip' param


 
header Parameters
X-Mailgun-Account-Id
required
string
Account ID


 
X-Mailgun-Requestor
required
string
Email address of the user making the request.


 
X-Mailgun-Requestor-Client
required
string
Identifier of the client application making the request.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
Response message


 
Request samples 
Response samples 
application/json
{
  • "message": "success"
}
List assignable domains
get/v3/domains/dynamic_pools/assignable
Lists all domains that are not already enrolled in dynamic IP pools.


SecuritybasicAuth 
Request 
query Parameters
subaccount_id
string
If provided, queries domains belonging to the subaccount. Must be a valid account ID


 
domain
string
Regex search term to query a domain by name


 
header Parameters
X-Mailgun-Account-Id
required
string
Account ID


 
X-Mailgun-Requestor
required
string
Email address of the user making the request.


 
X-Mailgun-Requestor-Client
required
string
Identifier of the client application making the request.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
Response message


 
Request samples 
Response samples 
application/json
{
  • "items": [
    • {
      }
    ]
}
Enroll all account domains
post/v3/domains/all/dynamic_pools/enroll
Begins an asynchronous background job to assign all domains to Dynamic IP Pools.
This can also include domains belonging to subaccounts depending on the provided parameters.
The Dynamic IP Pools feature must be enabled for the account and the request must come from a parent account user.


SecuritybasicAuth 
Request 
query Parameters
include_subaccounts
required
boolean
 Default:  false
If true, domains belonging to subaccounts will also be enrolled in Dynamic IP Pools


 
header Parameters
X-Mailgun-Account-Id
required
string
Account ID


 
X-Mailgun-Requestor
required
string
Email address of the user making the request.


 
X-Mailgun-Requestor-Client
required
string
Identifier of the client application making the request.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
Response message


 
Request samples 
Response samples 
application/json
{
  • "message": "started"
}
List all Dynamic IP pools
get/v3/dynamic_pools
Returns the list of IPs belonging to each of the account's Dynamic IP Pools.


SecuritybasicAuth 
Request 
header Parameters
X-Mailgun-Account-Id
required
string
Account ID


 
Responses 
200
A 200 response


Response Schema: application/json
property name*
additional property
object
 
Request samples 
Response samples 
application/json
{
  • "good_reputation": [
    • "1.0.0.1",
    • "1.0.0.2"
    ],
  • "poor_reputation": [
    • "1.0.0.3"
    ],
  • "new_senders": [
    • "1.0.0.4"
    ],
  • "pools": [
    • {
      },
    • {
      },
    • {
      }
    ]
}
Initialize/set IPs for all pools
post/v3/dynamic_pools/all
Any existing IPs in dynamic IP pools will be replaced. All IPs must be dedicated IPs and
belong to the account. Additionally, each dynamic IP pool must contain at least 1 IP that
is not currently warming.


SecuritybasicAuth 
Request 
header Parameters
X-Mailgun-Account-Id
required
string
Account ID


 
Request Body schema: multipart/form-data
required
good_reputation
required
string
IP(s) to include in the good_reputation pool


 
poor_reputation
required
string
IP(s) to include in the poor_reputation pool


 
new_senders
required
string
IP(s) to include in the new_senders pool


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
Response message


 
Request samples 
Response samples 
application/json
{
  • "good_reputation": [
    • "1.0.0.1",
    • "1.0.0.2"
    ],
  • "poor_reputation": [
    • "1.0.0.3"
    ],
  • "new_senders": [
    • "1.0.0.4"
    ]
}
Add IP to Dynamic IP Pool
post/v3/dynamic_pools/{pool_name}/{ip}
Adds a given IP to a Dynamic IP Pool. The IP must be dedicated and belong to the account.


SecuritybasicAuth 
Request 
path Parameters
pool_name
required
string
The name of the Dynamic IP Pool to add the IP to (ex: dynamic_good, dynamic_poor, etc.)


 
ip
required
string
The ip to add to the given Dynamic IP Pool


 
header Parameters
X-Mailgun-Account-Id
required
string
Account ID


 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
"this is needed just so that examples are included into the output"
Update pool IPs
patch/v3/dynamic_pools/{pool_name}
Adds and/or removes IPs to/from the specified dynamic IP pool.
A given pool is required to have at least 1 IP that is not
actively warming. Additionally, a single IP cannot be assigned to
multiple dynamic pools.


SecuritybasicAuth 
Request 
path Parameters
pool_name
required
string
The name of the dynamic IP pool


 
header Parameters
X-Mailgun-Account-Id
required
string
Account ID


 
Request Body schema: multipart/form-data
required
add_ip
required
string
IP(s) to add to the pool


 
remove_ip
required
string
IP(s) to remove from the pool


 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
{
  • "message": "success"
}
List all domains assigned to dynamic IP pools
get/v1/dynamic_pools/domains
Retrieves all domains enrolled in dynamic IP pools across the parent account and subaccounts.


SecuritybasicAuth 
Request 
query Parameters
limit
integer  [ 1 .. 100 ] 
The maximum number of domains to return


 
account
integer
Filter domains by account ID. Can be specified multiple times.


 
pool
string
Filter domains to a specific Dynamic IP Pool. Can be specified multiple times.


 
sort_by
string
 Default:  "name"
Specify which field to use to sort domains


 Enum Value Description
bounce_rate
Sort domains by bounce rate


complaint_rate
Sort domains by complaint rate


name
Sort domains alphabetically by name


 
sort_order
string
 Default:  "ascending"
Specify which field to use to sort domains


 Enum Value Description
ascending
Sort domains ascending by the specified sort_by field


descending
Sort domains descending by the specified sort_by field


 
header Parameters
X-Mailgun-Account-Id
required
string
Mailgun account ID


 
Responses 
200
A 200 response


Response Schema: application/json
required
Array of objects
 
total_items
required
integer <int32> 
 
required
object
 
400
A 400 response


Request samples 
Response samples 
application/json
{
  • "items": [
    • {
      },
    • {
      }
    ],
  • "total_items": 2,
  • "paging": { }
}
Preview domain assignment
get/v1/dynamic_pools/domains/{name}/preview
Runs a health check on a domain and returns which pool it would be placed in. It does NOT enroll the domain or set the band


SecuritybasicAuth 
Request 
path Parameters
name
required
string
The domain name


 
header Parameters
X-Mailgun-Account-Id
required
string
Mailgun account ID


 
Responses 
200
A 200 response


Response Schema: application/json
property name*
additional property
object
 
Request samples 
Response samples 
application/json
{
  • "pool": "dynamic_poor",
  • "bounce_rate": {
    • "band": "dynamic_poor",
    • "value": 0.25
    },
  • "complaint_rate": {
    • "value": 0.0002,
    • "band": "dynamic_good"
    }
}
List domain history
get/v1/dynamic_pools/domains/{name}/history
Retrieves a domain's history records


SecuritybasicAuth 
Request 
path Parameters
name
required
string
The domain name


 
header Parameters
X-Mailgun-Account-Id
required
string
Mailgun account ID


 
Responses 
200
A 200 response


Response Schema: application/json
id
required
string
 
owning_account_id
required
string
 
account_id
required
string
 
account_name
required
string
 
domain_id
required
string
 
domain_name
required
string
 
new_band
required
string
 
prev_band
required
string
 
reason
required
string
 
bounce_rate
required
number or null <float> 
 
timestamp
required
string <date-time> 
 
complaint_rate
number or null <float> 
 
processed_count
integer or null <int64> 
 
initiated_by
string
 
Request samples 
Response samples 
application/json
{
  • "id": "000000000000000000000000",
  • "owning_account_id": "000000000000000000000000",
  • "account_id": "685da027b1d02ec00a83fda0",
  • "domain_id": "685da027b1d02ec00a83fd9f",
  • "domain_name": "test.com",
  • "new_band": "dynamic_good",
  • "prev_band": "dynamic_poor",
  • "reason": "Multiple metrics in good threshold",
  • "bounce_rate": 0.2,
  • "complaint_rate": 0.1,
  • "processed_count": 100,
  • "timestamp": "2025-06-26T14:31:51.870037-05:00"
}
Override domain assignment
put/v1/dynamic_pools/domains/{name}/override
Overrides a domain's dynamic IP pool assignment. A domain's pool will not be updated by health checks while an override is present.


SecuritybasicAuth 
Request 
path Parameters
name
required
string
The domain name


 
header Parameters
X-Mailgun-Account-Id
required
string
Mailgun account ID


 
Request Body schema: multipart/form-data
required
pool
required
string
The name of the Dynamic IP pool to override the domain with. Must be a valid pool name (ex: dynamic_good, dynamic_new, etc.)


 
Responses 
200
A 200 response


Response Schema: application/json
property name*
additional property
object
 
400
A 400 response


Request samples 
Response samples 
application/json
{
  • "message": "success"
}
Remove override
delete/v1/dynamic_pools/domains/{name}/override
Removes any dynamic IP pool override for a domain. The domain's pool assignment will be managed by health checks.


SecuritybasicAuth 
Request 
path Parameters
name
required
string
The domain name


 
header Parameters
X-Mailgun-Account-Id
required
string
Mailgun account ID


 
Responses 
200
A 200 response


Response Schema: application/json
property name*
additional property
object
 
Request samples 
Response samples 
application/json
{
  • "message": "success"
}
List account history
get/v1/dynamic_pools/history
Retrieve history records for all domains assigned to Dynamic IP Pools across the parent and subaccounts.


SecuritybasicAuth 
Request 
query Parameters
Limit
integer  [ 1 .. 100 ] 
The maximum number of events to return


 
include_subaccounts
boolean
If true, includes events from all subaccounts in addition to events from the parent account


 
domain
string
Filter events by domain name


 
before
string
Filter events emitted before a given timestamp (Format: Mon, 02 Jan 2006 15:04:05 MST)


 
after
string
Filter events emitted after a given timestamp (Format: Mon, 02 Jan 2006 15:04:05 MST)


 
moved_to
string
Filter events by which Dynamic Pool a domain was moved to (ex. dynamic_good, dynamic_poor, etc.)


 
moved_from
string
Filter events by which Dynamic Pool a domain was moved from (ex. dynamic_good, dynamic_poor, etc.)


 
header Parameters
X-Mailgun-Account-Id
required
string
Mailgun account ID


 
Responses 
200
A 200 response


Response Schema: application/json
required
Array of objects
 
total_items
required
integer <int32> 
 
required
object
 
400
A 400 response


Request samples 
Response samples 
application/json
{
  • "items": [
    • {
      },
    • {
      }
    ],
  • "total_items": 2,
  • "paging": { }
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.