Skip to content
This repository
branch: develop
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 213 lines (197 sloc) 5.326 kb
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 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
---
layout: page
weight: 0
title: IP Management
navigation:
   show: true
---

  <p>List</p>
  Obtain a complete list of all IP's and which are free, taken or available.
  <table class="table table-bordered table-striped"><tbody>
      <tr>
        <th>Parameter</th>
        <th>Required</th>
        <th>Requirements</th>
      </tr>
      <tr>
        <td>list</td>
        <td>Yes</td>
        <td>Must be set to either ( all / free / taken / available )</td>
      </tr>
    </tbody></table>
  Here is a brief explanation of each option available for the list parameter:
  <dl>
    <dt>all</dt>
    <dd>All IP addresses available to account, regardless of whether or not the IP is taken by a subuser</dd>
    <dt>free</dt>
    <dd>All free IP addresses for the account. If a subuser is using an IP, it will not show up on this list</dd>
    <dt>taken</dt>
    <dd>All taken IP addresses for the account. Only IP addresses that taken by subusers will show up on this list</dd>
    <dt>available</dt>
    <dd>All available IP addresses for the account including all free IP addresses. If a subuser is deactivated<em>and</em> is assigned an IP, that IP will show up on this list since that IP address is not being used by anyone</dd>
  </dl>
  
{% apiexample list POST https://api.sendgrid.com/apiv2/customer.ip api_user=your_sendgrid_username&api_key=your_sendgrid_password&list=all %}
  {% response json %}
[
  {
    "ip": "255.255.255.250"
  },
  {
    "ip": "255.255.255.251"
  },
  {
    "ip": "255.255.255.252"
  }
]
  {% endresponse %}
  {% response xml %}
<?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>
  {% endresponse %}
{% endapiexample %}

<hr/>
{% anchor h2 %}
Subuser IP Usage
{% endanchor %}
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.
<table class="table table-bordered table-striped"><tbody>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Requirements</th>
    </tr>
    <tr>
      <td>task</td>
      <td>Yes</td>
      <td>Must be set to <em>list</em>
      </td>
    </tr>
    <tr>
      <td>user</td>
      <td>Yes</td>
      <td>Subuser must be registered under your account</td>
    </tr>
  </tbody></table>
{% apiexample usage POST https://api.sendgrid.com/apiv2/customer.sendip api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=list&user=example@example.com %}
  {% response json %}
{
  "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"
  }
}
  {% endresponse %}
  {% response xml %}
<?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>
  {% endresponse %}
{% endapiexample %}

<hr/>

{% anchor h2 %}
Subuser IP Assignment
{% endanchor %}
You need to assign at least ONE IP to your subuser.
<table class="table table-bordered table-striped"><tbody>
    <tr>
      <th>Parameter</th>
      <th>Required</th>
      <th>Requirements</th>
    </tr>
    <tr>
      <td>task</td>
      <td>Yes</td>
      <td>Must be set to <em>append</em>
      </td>
    </tr>
    <tr>
      <td>user</td>
      <td>Yes</td>
      <td>Subuser must be registered under your account</td>
    </tr>
    <tr>
      <td>set</td>
      <td>Yes</td>
      <td>Must be either:
        <strong>none</strong>: Remove all ips.
        <strong>all</strong>: Apply all possible ips to subuser.
        <strong>specify</strong>: Specify the ips to the subser. Must be a valid set of IPs (use the list call to determine valid IPs)</td>
    </tr>
    <tr>
      <td>ip[]</td>
      <td>No</td>
      <td>If the <em>set</em> 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 ]</td>
    </tr>
  </tbody></table>
{% apiexample subuser POST https://api.sendgrid.com/apiv2/customer.sendip 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 json %}
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}
  {% endresponse %}
  {% response xml %}
<?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>
  {% endresponse %}
{% endapiexample %}

Something went wrong with that request. Please try again.