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"
}

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
header Parameters
X-Mailgun-Account-Id
required
string

Account ID

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

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
{
  • "message": "success",
  • "details": {
    • "ips": [
      ],
    • "is_linked": true,
    • "linked_domains": [
      ],
    • "name": "DIPP's short name",
    • "pool_id": "658041ae44842b99ee2eaa1b",
    • "description": "A long description of the DIPP"
    }
}

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": {
    • "dedicated": 1,
    • "shared": 2
    }
}

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
remove_ip
string

The IP to remove 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

name
string

The new short for the DIPP

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"
}