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.mailgun.api.v3.MailgunIPsApi;
import com.mailgun.model.ips.IPsResult;

// ...

public IPsResult getIPs() {
    MailgunIPsApi mailgunIPsApi = MailgunClient.config(API_KEY)
        .createApi(MailgunIPsApi.class);

    return mailgunIPsApi.getDedicatedIPs(true);
}

# 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)
}

const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const ips = await client.ips.list();
    console.log('ips', ips);
  } catch (error) {
    console.error(error);
  }
})();

{
  "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.mailgun.api.v3.MailgunIPsApi;
import com.mailgun.model.ips.IPResult;

// ...

public IPResult getIP() {
    MailgunIPsApi mailgunIPsApi = MailgunClient.config(API_KEY)
        .createApi(MailgunIPsApi.class);

    return mailgunIPsApi.getSpecifiedIP("127.0.0.1");
}

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

const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const ip = await client.ips.get('127.0.0.1'); // use interested ip instead of 127.0.0.1
    console.log('ip', ip);
  } catch (error) {
    console.error(error);
  }
})();

{
  "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.mailgun.api.v3.MailgunIPsApi;
import com.mailgun.model.ips.IPsResult;

// ...

public IPsResult getDomainIPs() {
    MailgunIPsApi mailgunIPsApi = MailgunClient.config(API_KEY)
        .createApi(MailgunIPsApi.class);

    return mailgunIPsApi.getDomainIPs(YOUR_DOMAIN_NAME);
}

# 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)
}

const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const getIps = await client.domains.getIps(DOMAIN);
    console.log('getIps', getIps);
  } catch (error) {
    console.error(error);
  }
})();

{
  "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.mailgun.api.v3.MailgunIPsApi;
import com.mailgun.model.ResponseWithMessage;

// ...

public ResponseWithMessage addDomainIP() {
    MailgunIPsApi mailgunIPsApi = MailgunClient.config(API_KEY)
        .createApi(MailgunIPsApi.class);

    return mailgunIPsApi.assignIPToDomain(YOUR_DOMAIN_NAME, "127.0.0.1");
}

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

const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
    try {
        const addedIp = await client.domains.assignIp(DOMAIN, '127.0.0.1');
        console.log('addedIp', addedIp);
    } catch (error) {
        console.error(error);
    }
})();

{
  "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.mailgun.api.v3.MailgunIPsApi;
import com.mailgun.model.ResponseWithMessage

// ...

public ResponseWithMessage deleteDomainIP() {
    MailgunIPsApi mailgunIPsApi = MailgunClient.config(API_KEY).createApi(MailgunIPsApi.class);

    return mailgunIPsApi.unassignIPFromDomain(YOUR_DOMAIN_NAME, "127.0.0.1");
}

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

const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const deletedIp = await client.domains.deleteIp(DOMAIN, '127.0.0.1');
    console.log('deletedIp', deletedIp);
  } catch (error) {
    console.error(error);
  }
})();

{
  "message": "success"
}