IPs

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

v3/ips

Note

You can manage your IPs from the Control Panel. Click on IP Management in the settings dropdown menu.

GET /ips

Returns a list of IPs assigned to your account. See examples below.

Parameter Description
dedicated Return only dedicated IPs if set to true. (all are returned by default)
GET /ips/<ip>

Returns information about the specified IP. See examples below.

GET /domains/<domain>/ips

Returns a list of IPs currently assigned to the specified domain.

POST /domains/<domain>/ips

Assign a dedicated IP to the domain specified.

Note

Only dedicated IPs can be assigned to a domain.

Parameter Description
ip IP address that should be assigned to the domain pool.
DELETE /domains/<domain>/ips/<ip>

Unassign an IP from the domain specified.

Example

Get a list of all IPs.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/ips \
    -d dedicated="true"
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getIPs() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v3/ips")
            .basicAuth("api", API_KEY)
            .queryString("dedicated", "true")
            .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');

# Issue the call to the client.
$result = $mgClient->ips->index();
def get_ips():
    return requests.get(
        "https://api.mailgun.net/v3/ips",
        params={"dedicated": "true"},
        auth=("api", "YOUR_API_KEY"))
def get_ips
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/ips?dedicated=true"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetIPsChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetIPs ().Content.ToString ());
    }

    public static IRestResponse GetIPs ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "ips";
        request.AddParameter ("dedicated", "true");
        return client.Execute (request);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func ListIPS(domain, apiKey string) ([]mailgun.IPAddress, error) {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    // Pass 'true' to only return dedicated ips
    return mg.ListIPS(ctx, true)
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get('ips', function (error, body) {
  console.log(body);
});
{
  "items": ["192.161.0.1", "192.168.0.2"],
  "total_count": 2
}

Get a single IP.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/ips/127.0.01
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getIP() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v3/ips/127.0.0.1")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$ip       = '127.0.0.1';

# Issue the call to the client.
$result = $mgClient->ips()->show($ip);
def get_ip():
    return requests.get(
        "https://api.mailgun.net/v3/ips/127.0.0.1",
        auth=("api", "YOUR_API_KEY"))
def get_ip
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/ips/127.0.0.1"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetIPChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetIP ().Content.ToString ());
    }

    public static IRestResponse GetIP ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("ip", "127.0.0.1", ParameterType.UrlSegment);
        request.Resource = "/ips/{ip}";
        return client.Execute (request);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func GetIP(domain, apiKey string) (mailgun.IPAddress, error) {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.GetIP(ctx, "127.0.0.1")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get('/ips/127.0.0.1', function (error, body) {
  console.log(body);
});
{
  "ip": "192.161.0.1",
  "dedicated": true,
  "rdns": "luna.mailgun.net"
}

Get a list of IPs from the domain pool.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getDomainIPs() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v3/domains/" + YOUR_DOMAIN_NAME + "/ips")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain = "YOUR_DOMAIN_NAME";

# Issue the call to the client.
$result = $mgClient->ips()->domainIndex($domain);
def get_domain_ips():
    return requests.get(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips",
        auth=("api", "YOUR_API_KEY"))
def get_domain_ips
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetDomainIPsChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetDomainIPs ().Content.ToString ());
    }

    public static IRestResponse GetDomainIPs ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "/domains/{domain}/ips";
        return client.Execute (request);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func ListDomainIPS(domain, apiKey string) ([]mailgun.IPAddress, error) {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.ListDomainIPS(ctx)
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get(`/domains/${DOMAIN}/ips`, function (error, body) {
  console.log(body);
});
{
  "items": ["192.161.0.1", "192.168.0.2"],
  "total_count": 2
}

Assign a dedicated IP to the domain pool.

curl -s --user 'api:YOUR_API_KEY' \
   -X POST https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips \
   -F ip='127.0.0.1'
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode addDomainIP() throws UnirestException {

        HttpResponse<JsonNode> jsonResponse = Unirest.post("https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips")
            .basicAuth("api", API_KEY)
            .field("ip", "127.0.0.1")
            .asJson();

        return jsonResponse.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain   = 'YOUR_DOMAIN_NAME';
$ip       = '127.0.0.1';

# Issue the call to the client.
$result = $mgClient->ips()->assign($domain, $ip);
def add_domain_ip():
    return requests.post(
        "https://api.mailgun.net/v3/domains/YOUR_NEW_DOMAIN_NAME/ips",
        auth=("api", "YOUR_API_KEY"),
        data={"smtp_password": "127.0.0.1"})
def add_domain_ip
  RestClient.post("https://api:YOUR_API_KEY"\
                  "@api.mailgun.net/v3/domains/YOUR_NEW_DOMAIN_NAME/ips",
                  :ip => '127.0.0.1')
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddDomainIPChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (AddDomainIP ().Content.ToString ());
    }

    public static IRestResponse AddDomainIP ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3/");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "{domain}/ips";
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.AddParameter ("ip", "127.0.0.1");
        request.Method = Method.POST;
        return client.Execute (request);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func AddDomainIPS(domain, apiKey string) error {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.AddDomainIP(ctx, "127.0.0.1")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.post(`/${DOMAIN}/ips`, {'ip': '127.0.0.1'}, function (error, body) {
  console.log(body);
});
{
  "message": "success"
}

Remove an IP from the domain pool.

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips/127.0.0.1
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode deleteDomainIP() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.delete("https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips/127.0.0.1")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain   = 'YOUR_DOMAIN_NAME';
$ip       = '127.0.0.1';

# Issue the call to the client.
$result = $mgClient->ips->unassign($domain, $ip);
def delete_domain_ip():
    return requests.delete(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips/127.0.0.1",
        auth=("api", "YOUR_API_KEY"))
def delete_domain_ip
  RestClient.delete "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/ips/127.0.0.1"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class DeleteDomainIPChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (DeleteDomainIP ().Content.ToString ());
    }

    public static IRestResponse DeleteDomainIP ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "{domain}/ips/{ip}";
        request.AddUrlSegment ("ip", "127.0.0.1");
        request.Method = Method.DELETE;
        return client.Execute (request);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func DeleteDomainIP(domain, apiKey string) error {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.DeleteDomainIP(ctx, "127.0.0.1")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.delete(`/${DOMAIN}/ips/127.0.0.1`, function (error, body) {
  console.log(body);
});
{
  "message": "success"
}