Edit

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. The IP Pools endpoint is available at:

v1/ip_pools

Note

You can manage IP Pools from the Control Panel. Click on IP Pools in the Settings dropdown menu.

Create IP Pool

POST /v1/ip_pools

Creates a new IP Pool and returns a unique ID

Note

Only dedicated IPs that are not on a warmup can be added to an IP Pool.

Parameter   Description
name string Name of the IP Pool being created
description string (Optional) Description of the IP Pool being created
ips string (Optional) A comma separated list of IP addresses to be assigned to this IP Pool

Get IP Pools

GET /v1/ip_pools

Returns a list of all IP Pools on an account

Update an IP Pool

PATCH /v1/ip_pools/{pool_id}

Update the name, description, or dedicated IPs assigned to an IP Pool.

Note

Only dedicated IPs that are not on a warmup can be added to an IP Pool.

Parameter   Description
name string Name of the IP Pool being created
description string Description of the IP Pool being created
add_ip string IP address that you want to add to the pool. Can be specified any number of times
remove_ip string IP address that you want to remove from the pool. Can be specified any number of times

Delete an IP Pool

DELETE /v1/ip_pools/{pool_id}

Deletes an IP Pool. If an IP Pool is assigned to a domain, you must provide a replacement IP option (shared, dedicated or another IP Pool).

Parameter   Description
ip string Provide a replacement dedicated IP or shared to use a shared IP (automatically assigned) as a replacement
pool_id string Replacement IP Pool

Examples

Creating IP Pool:

curl -s --user 'api:YOUR_API_KEY' \
   https://api.mailgun.net/v1/ip_pools \
   -F name='ip_pool_name' \
   -F description='pool description' \
   -F ips='127.0.0.1'

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 poolName = 'ip_pool_name';
    const createdIpPool = await client.ip_pools.create({ name: poolName, description: 'description for the ip pool', ips: ['127.0.0.1'] });
    console.log('createdIpPool', createdIpPool);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{ message: 'success', pool_id: 'some_pool_id' }

Getting IP Pools list:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v1/ip_pools

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 ipPoolsList = await client.ip_pools.list();
    console.log('ipPoolsList', ipPoolsList);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  'ip_pools': [
    {
      description: 'Test description 1',
      ips: ['127.0.0.1'],
      is_linked: false,
      name: 'test_pool1',
      pool_id: 'some_pool_id'
      },
      {
      description: 'Test description 2',
      ips: ['127.0.0.1'],
      is_linked: true,
      name: 'test_pool2',
      pool_id: 'some_pool_id_2'
    },
   'message':'success'
  ]
}

Updating an IP Pool:

curl -s --user 'api:YOUR_API_KEY' -X PATCH \
  https://api.mailgun.net/v1/ip_pools/$your_pool_id \
  -F name='new ip pool name' \
  -F description='new pool description' \
  -F ips='127.0.0.2'

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 poolName = 'new_ip_pool_name';
    const updatedIpPool = await client.ip_pools.update('your_ip_pool_id', { name: poolName, description: 'updated pool for testing purposes', ips: '127.0.0.1' });
    console.log('updatedIpPool', updatedIpPool);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{ message: 'success' }

Deleting an IP Pool:

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
  https://api.mailgun.net/v1/ip_pools/$your_pool_id

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 deletedIpPool = await client.ip_pools.delete('61b70962dc62320ca808bd39');
    console.log('deletedIpPool', deletedIpPool);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{ message: 'started' }

Linking an IP Pool:

curl -s --user 'api:YOUR_API_KEY' \
   https://api.mailgun.net/v3/domains/$YOUR_DOMAIN/ips \
   -F pool_id='$pool_id'

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 linkedIpPool = await client.domains.linkIpPool(DOMAIN, 'your_ip_pool_id');
    console.log('linkedIpPool', linkedIpPool);
  } catch (error) {
      console.error(error);
  }
})();

Sample response:

{ body: { message: 'success' }, status: 200 }

Unlink an IP Pool:

#IP as a replacement
curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN/ips/ip_pool\?ip='REPLACEMENT_IP'

#IP pool id as replacement
curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN/ips/ip_pool\?pool_id='REPLACEMENT_POOL_ID'

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 unlinkedIpPoll = await client.domains.unlinkIpPoll(DOMAIN, {pool_id: 'your_ip_pool_id'});
    console.log('unlinkedIpPoll', unlinkedIpPoll);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{ body: { message: 'success' }, status: 200 }