IPs

The IP API endpoint allows you to access information regarding the IPs allocated to your Mailgun account that are used for outbound sending.

List account IPs

get/v3/ips

assignable_to_pool in response lists which IPs can be assigned to DIPPs; this field is present only if the account has 'DIPPs' feature enabled.

total_count contains the number of items returned in items (this depends on the filters applied).

SecuritybasicAuth
Request
query Parameters
dedicated
boolean

Return only dedicated IPs

enabled
boolean

Return only enabled IPs

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
{
  • "items": [
    • "1.2.3.4",
    • "5.6.7.8"
    ],
  • "total_count": 2,
  • "assignable_to_pools": [
    • "5.6.7.8"
    ],
  • "details": [
    • {
      },
    • {
      }
    ]
}

Get details about account IP

get/v3/ips/{ip}
SecuritybasicAuth
Request
path Parameters
ip
required
string

IP address 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
{
  • "ip": "1.2.3.4",
  • "rdns": "ip1-2-3-4.mailgun.net",
  • "dedicated": true
}

Get all domains of an account where a specific IP is assigned

get/v3/ips/{ip}/domains

The IP must belong to the account.

Matching domains are ordered by increasing id, then the limit and skip parameters are applied.

If the search parameter is present, it is used to limit the results to domains whose names match the search query. The search query is split into words by whitespace and punctuation, then the logical OR is applied.

SecuritybasicAuth
Request
path Parameters
ip
required
string

The IP to filter on

query Parameters
limit
required
integer

The limit to apply to the returned domains

search
required
string

The search query that the returned domains' names must match

skip
required
integer

The number of matching domains to skip in the response

header Parameters
X-Mailgun-Account-Id
required
string

Account ID

Responses
200

A 200 response

Response Schema: application/json
required
Array of objects
total_count
required
integer <int32>
Request samples
Response samples
application/json
{
  • "items": [
    • {
      },
    • {
      }
    ],
  • "total_count": 2
}

Place account IP into a dedicated IP band

post/v3/ips/{addr}/ip_band

The Dedicated IP Bands feature must be enabled for the account.

The IP must be a dedicated one belonging to the account.

SecuritybasicAuth
Request
path Parameters
addr
required
string

IP address

header Parameters
X-Mailgun-Account-Id
required
string

Account ID

Request Body schema: multipart/form-data
required
ip_band
required
string

Dedicated IP band to place the IP address into

Responses
200

A 200 response

Response Schema: application/json
string
Request samples
Response samples
application/json
{
  • "message": "success"
}

Return the number of IPs available to the account per its billing plan

get/v3/ips/request/new

This endpoint remains active for backwards compatibility. Do not use it in new code.

Field shared in the response is deprecated and should not be used.

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

Add a new dedicated IP to the account

post/v3/ips/request/new

A new IP can be assigned only if billing limits allow that.

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

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