IP Pools

IP Pools allow you to group your dedicated IPs into customized "pools" to help manage your sending reputation for different mail sending streams.

Remove an IP from the domain pool, unlink a DIPP or remove the domain pool

delete/v3/domains/{name}/ips/{ip}

The behavior of the endpoint depends on the value of the ip parameter. It can be one of the following:

  • a valid IP address: this IP address will be removed from the domain pool.
  • string all: the entire domain pool will be removed. As long as Tower is concerned, such domain will no longer exist.
  • string ip_pool: the DIPP which is currently linked to the domain will be unlinked.

Removing An IP

Note that it's impossible to alter domain IPs if a DIPP is linked to the domain.

If the account is not eligible for shared IPs, additional rules apply:

  • removing the last IP from the domain is not allowed;
  • if all of the remaining dedicated IPs are on warmup, an extra IP might be added to the domain pool.

Unlinking The DIPP

The account must have 'DIPPs' feature enabled.

Either ip or pool_id query parameter must be specified, but not both.

If the special value shared is used for the replacement IP, the account must be eligible for shared IPs. In this case the system will assign a shared IP as the replacement.

SecuritybasicAuth
Request
path Parameters
ip
required
string

One of the following: all, ip_pool or a valid IP address.

name
required
string

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

query Parameters
ip
string

Replacement IP or special value shared.

pool_id
string

Replacement DIPP id.

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
Request samples 
Response samples 
application/json
{
  • "message": "success"
}
Remove an IP from the domain pool, unlink a DIPP or remove the domain pool
delete/v3/domains/{name}/pool/{ip}
The behavior of the endpoint depends on the value of the ip parameter. It can be
one of the following:


    

  • a valid IP address: this IP address will be removed from the domain pool.
    • 

  • string all: the entire domain pool will be removed. As long as Tower is
concerned, such domain will no longer exist.
    • 

  • string ip_pool: the DIPP which is currently linked to the domain will be
unlinked.
    • 



Removing An IP


Note that it's impossible to alter domain IPs if a DIPP is linked to the domain.


If the account is not eligible for shared IPs, additional rules apply:


    

  • removing the last IP from the domain is not allowed;
    • 

  • if all of the remaining dedicated IPs are on warmup, an extra IP might be added to
the domain pool.
    • 



Unlinking The DIPP


The account must have 'DIPPs' feature enabled.


Either ip or pool_id query parameter must be specified, but not both.


If the special value shared is used for the replacement IP, the account must be
eligible for shared IPs. In this case the system will assign a shared IP as the
replacement.


SecuritybasicAuth 
Request 
path Parameters
ip
required
string
One of the following: all, ip_pool or a valid IP address.


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


 
query Parameters
ip
string
Replacement IP or special value shared.


 
pool_id
string
Replacement DIPP id.


 
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
 
Request samples 
Response samples 
application/json
{
  • "message": "success"
}
List dedicated IP pools of the account
get/v3/ip_pools
Description


Lists all dedicated IP pools of the account. For each pool
returns its basic properties (name, description, the list of IPs)
and indicates whether the pool is linked to any domains and
whether it's an inherited one. Only one pool can be inherited
from the parent account.


SecuritybasicAuth 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
{
  • "ip_pools": [
    • {
      }
    ],
  • "message": "success"
}
Add a new DIPP to the account
post/v3/ip_pools
The account must have 'DIPPs' feature enabled.


Returns the id of the newly created DIPP.


SecuritybasicAuth 
Request 
Request Body schema: multipart/form-data
required
description
required
string
Description of the DIPP


 
name
required
string
Short name of the DIPP


 
ip
string
IP address to add to the DIPP (may be specified multiple times)


 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
{
  • "message": "success",
  • "pool_id": "658041ae44842b99ee2eaa1b"
}
Get DIPP details
get/v3/ip_pools/{pool_id}
is_linked in the response indicates whether the DIPP is currently linked to any
domains. If it's true, linked_domain lists those domains.


SecuritybasicAuth 
Request 
path Parameters
pool_id
required
string
Id of the DIPP to get details about


 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
{
  • "message": "success",
  • "details": {
    • "name": "DIPP's short name",
    • "pool_id": "658041ae44842b99ee2eaa1b",
    • "description": "A long description of the DIPP",
    • "ips": [
      ],
    • "is_linked": true,
    • "linked_domains": [
      ]
    }
}
Delete the DIPP
delete/v3/ip_pools/{pool_id}
The DIPPs feature must be enabled for the account.


It is not allowed to delete a DIPP inherited from the parent account.


If the DIPP is delegated to subaccounts, those will also be updated.


If the replacement DIPP is specified, all domains linked to the deleted DIPP will be
relinked to the replacement DIPP. The latter must contain at least one IP.


If the replacement IP is specified, all domains linked to the deleted DIPP will be
unlinked, and the replacement IP will be assigned to them. It is not allowed to
delete a DIPP inherited from the parent account and replace it with an IP
(subaccounts do not explicitly manage their IPs).


The replacement IP must be a dedicated one; it can't belong to another DIPP. If a
special value shared is used, appropriate shared IPs will be used (the account must
be eligible for shared IPs in this case).


Omitting both replacement DIPP and replacement IP is allowed only if the DIPP being
deleted contains no IPs.


The processing of affected domains and subaccounts happens asynchronously after the
endpoint returns a response.


SecuritybasicAuth 
Request 
path Parameters
pool_id
required
string
Id of the DIPP to delete


 
query Parameters
ip
required
string
Replacement IP or a special value shared


 
pool_id
required
string
Id of the replacement DIPP


 
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
string
 
Request samples 
Response samples 
application/json
{
  • "allowed": {
    • "shared": 2,
    • "dedicated": 1
    }
}
Edit DIPP
patch/v3/ip_pools/{pool_id}
The account must have 'DIPPs' feature enabled.


It's not allowed to edit a DIPP inherited from the parent account.


IPs being added to the DIPP must be dedicated ones and belong to the account.


If IPs of the DIPP end up modified, and the DIPP is linked to domains, the domains
will be updated asynchronously (after this endpoint returns response).


Returns an error if the passed parameters won't result in any changes.


SecuritybasicAuth 
Request 
path Parameters
pool_id
required
string
Id of the DIPP to edit


 
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.


 
Request Body schema: multipart/form-data
required
unlink_domain
string
The ID of the domain to unlink from the DIPP (may be specified multiple times)


 
add_ip
string
The IP to add to the DIPP (may be specified multiple times)


 
description
string
The new description for the DIPP


 
link_domain
string
The ID of the domain link to the DIPP (may be specified multiple times)


 
name
string
The new short for the DIPP


 
remove_ip
string
The IP to remove from the DIPP (may be specified multiple times)


 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
{
  • "message": "success"
}
Add an IP to a DIPP
put/v3/ip_pools/{pool_id}/ips/{ip}
The account must have 'DIPPs' feature enabled.


It is not allowed to modify a DIPP inherited from the parent account.


The IP must be a dedicated one, belong to the account and not belong to any other
DIPP.


All domains linked to the DIPP will be updated so that their IPs include the newly
added address. If the DIPP is delegated to subaccounts, those will also be updated.


The processing of affected domains and subaccounts happens asynchronously after the
endpoint returns a response.


SecuritybasicAuth 
Request 
path Parameters
ip
required
string
IP to add to the DIPP


 
pool_id
required
string
Id of the DIPP to update


 
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
string
 
Request samples 
Response samples 
application/json
{
  • "message": "started"
}
Remove an IP from a DIPP
delete/v3/ip_pools/{pool_id}/ips/{ip}
The account must have 'DIPPs' feature enabled.


It's not allowed to edit a DIPP inherited from the parent account.


If the DIPP is linked to domains, the domains will be updated asynchronously (after
this endpoint returns response).


SecuritybasicAuth 
Request 
path Parameters
ip
required
string
The IP to remove


 
pool_id
required
string
The id of the DIPP


 
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
string
 
Request samples 
Response samples 
application/json
{
  • "message": "started"
}
Add multiple IPs to the DIPP
post/v3/ip_pools/{pool_id}/ips.json
The account must have 'DIPPs' feature enabled.


It is not allowed to modify a DIPP inherited from the parent account.


All IPs must be dedicated ones, belong to the account and not belong to any other
DIPP.


All domains linked to the DIPP will be updated so that their IPs include the newly
added addresses. If the DIPP is delegated to subaccounts, those will also be updated.


The processing of affected domains and subaccounts happens asynchronously after the
endpoint returns a response.


SecuritybasicAuth 
Request 
path Parameters
pool_id
required
string
Id of the DIPP to update


 
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.


 
Request Body schema: application/json
optional
ips
required
Array of strings
IPs to add to the DIPP


 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
application/json
{
  • "ips": [
    • "1.2.3.4",
    • "5.6.7.8"
    ]
}
Response samples 
application/json
{
  • "message": "started"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.