On this page

IP Management

(warning)

This documentation is for the SendGrid Web API v2

We will deprecate this version on February 10, 2025. To access all the latest features and upcoming developments, please see our v3 API. For assistance with transitioning, refer to our migration guide.

List

Obtain a complete list of all IPs associated with your account and whether they are free, taken, or available.

URI Parameter	Required	Requirements	Description
list	Yes	Must be set to one of the following: `all free` `taken` `available`	Will return the IPs on the account that match the argument

The list argument will restrict the IPs returned:

all: All IP addresses available on account, regardless of whether or not the IP is used by a subuser.
free: All free IP addresses for the account. IPs that are not in use by any subusers.
taken: All taken IP addresses for the account. IP addresses that are in use by one or more subusers.
available: All available IP addresses for the account including all free IP addresses. If a subuser is deactivated and assigned an IP, that IP will show up on this list since that IP address is not actually being used.

JSONXML

Call

`POST`	`https://api.sendgrid.com/apiv2/customer.ip.json`
`POST` Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&list=all`

Response

1[
2  {
3    "ip": "255.255.255.250"
4  },
5  {
6    "ip": "255.255.255.251"
7  },
8  {
9    "ip": "255.255.255.252"
10  }
11]

Subuser IP List

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `list`	Task to return the IPs in use by the subuser
user	Yes	Subuser must be under your account	Subuser to get the IPs of

JSONXML

Call

`POST`	`https://api.sendgrid.com/apiv2/customer.sendip.json`
`POST` Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=list&user=subuser_username`

Response

1{
2  "success": "success",
3  "outboundcluster": "SendGrid MTA",
4  "ips": [
5    {
6      "ip": "255.255.255.250"
7    },
8    {
9      "ip": "255.255.255.251"
10    },
11    {
12      "ip": "255.255.255.251"
13    },
14    {
15      "ip": "255.255.255.252"
16    },
17    {
18      "ip": "255.255.255.253"
19    },
20    {
21      "ip": "255.255.255.254"
22    }
23  ]
24}

Subuser IP Assignment

You need to assign at least ONE IP to your subuser.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `append`	Task to add IP to a subuser
user	Yes	Subuser must be under your account	Subuser that is adding IPs
set	Yes	Must be either: `none` `all` `specify`	`none`: Remove all IPs. `all`: Apply all possible IPs to subuser. `specify`: Specify the IPs to the subser
ip[]	No	Must be a valid set of IPs (use the list call to determine valid IPs)	If the `set` parameter is `specify`, then you must specify the IPs. Use the IP[] parameter to specify an IP: `ip[]=255.255.255.0[]=255.255.255.1`

JSONXML

Call

`POST`	`https://api.sendgrid.com/apiv2/customer.sendip.json`
`POST` Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=append&set=specify&user=subuser_username&ip[]=255.255.255.250&ip[]=255.255.255.255`

Response

1{
2  "message": "success"
3}