List

Obtain a complete list of all IP’s and which are free, taken or available.
Parameter Required Requirements
list Yes Must be set to either ( all / free / taken / available )
Here is a brief explanation of each option available for the list parameter:
all
All IP addresses available to account, regardless of whether or not the IP is taken by a subuser
free
All free IP addresses for the account. If a subuser is using an IP, it will not show up on this list
taken
All taken IP addresses for the account. Only IP addresses that taken by subusers will show up on this list
available
All available IP addresses for the account including all free IP addresses. If a subuser is deactivatedand is assigned an IP, that IP will show up on this list since that IP address is not being used by anyone

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
4
5
6
7
8
9
10
11
[
  {
    "ip": "255.255.255.250"
  },
  {
    "ip": "255.255.255.251"
  },
  {
    "ip": "255.255.255.252"
  }
]

Call

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

Response

1
2
3
4
5
6
7
<?xml version="1.0" encoding="ISO-8859-1"?>

<ips>
   <ip>255.255.255.250</ip>
   <ip>255.255.255.251</ip>
   <ip>255.255.255.252</ip>
</ips>

Subuser IP Usage

If your account has more than one IP address, you can manage what IPs your subusers are allowed to send from. If you remove all IPs from a specified user, they will use all IPs from from your list.
Parameter Required Requirements
task Yes Must be set to list
user Yes Subuser must be registered under your account

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=example@example.com

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "success": "success",
  "outboundcluster": "o1.sendgrid.net",
  "ips": [
    {
      "ip": "255.255.255.250"
    },
    {
      "ip": "255.255.255.251"
    },
    {
      "ip": "255.255.255.251"
    },
    {
      "ip": "255.255.255.252"
    },
    {
      "ip": "255.255.255.253"
    },
    {
      "ip": "255.255.255.254"
    }
  ]
}

//error
{
  "error": {
    "code": 400,
    "message": "User does not exist"
  }
}

Call

POST https://api.sendgrid.com/apiv2/customer.sendip.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=list&user=example@example.com

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?xml version="1.0" encoding="ISO-8859-1"?>

<sendips>
   <ocluster>o1.sendgrid.net</ocluster>
   <ips>
      <ip>255.255.255.250</ip>
      <ip>255.255.255.251</ip>
      <ip>255.255.255.252</ip>
      <ip>255.255.255.253</ip>
      <ip>255.255.255.254</ip>
   </ips>
</sendips>

<!-- error -->
<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>User does not exist</message>
</result>

Subuser IP Assignment

You need to assign at least ONE IP to your subuser.
Parameter Required Requirements
task Yes Must be set to append
user Yes Subuser must be registered under your account
set Yes Must be either: none: Remove all ips. all: Apply all possible ips to subuser. specify: Specify the ips to the subser. Must be a valid set of IPs (use the list call to determine valid IPs)
ip[] No If the set parameter is set, then you must specify the IPs. Use the ip[] parameter to specify an IP. [ IE - ip[]=255.255.255.0&ip[]=255.255.255.1 ]

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=example@example.com&ip[]=255.255.255.250&ip[]=255.255.255.255

Response

1
2
3
4
5
6
7
8
9
10
11
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

Call

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>success</message>
</result>

<!-- error -->
<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error</message>
   <errors>
      ...
      <error>... error messages ...</error>
      ...
   </errors>
</result>