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 |
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 |
Link an IP Pool¶
POST /v3/domains/{domain_name}/ips
Links an IP Pool to a sending domain. Linking an IP Pool to a domain will replace any IPs already assigned (shared or dedicated) with the IPs assigned to the pool. Only a pool with dedicated IPs can be linked to a sendign domain.
Parameter | Description | |
---|---|---|
pool_id | string | id of the pool to assign |
Unlink an IP Pool¶
DELETE /v3/domains/{domain_name}/ips/ip_pool
Removes an IP Pool from a domain. You will need to supply 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 }