IPs

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

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


 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
{
  • "assignable_to_pools": [
    • "5.6.7.8"
    ],
  • "items": [
    • "1.2.3.4",
    • "5.6.7.8"
    ],
  • "total_count": 2,
  • "details": [
    • {
      },
    • {
      }
    ]
}
Get details about account IP
get/v3/ips/{ip}
SecuritybasicAuth 
Request 
path Parameters
ip
required
string
IP address to get details about


 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
{
  • "dedicated": true,
  • "ip": "1.2.3.4",
  • "rdns": "ip1-2-3-4.mailgun.net"
}
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


 
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


 
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 
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 
Responses 
200
A 200 response


Response Schema: application/json
string
 
Request samples 
Response samples 
application/json
{
  • "message": "success"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.