IP Whitelabel

A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the customer has created the appropriate A record for their IP, SendGrid will create the appropriate reverse DNS record for the IP.

List all IPs [GET]

Return list of IPs. If search key is provided, returns IPs that matches.
URI Parameter Required Requirements Description
ip No string Performs prefix search with given segment of IP. For example: 192.*
limit No integer Max number of IPs to return
offset No integer Page number to begin from. Works with limit to provide pagination.

Request

1
GET https://api.sendgrid.com/v3/whitelabel/ips{?limit,offset,ip} HTTP/1.1

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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
HTTP/1.1 200
[
  {
    "id": 1,
    "ip": "192.168.1.1",
    "rdns": "o1.email.example.com",
    "users": [
      {
        "username": "john@example.com",
        "user_id": 7
      },
      {
        "username": "janeexampexample@example.com",
        "user_id": 8
      }
    ],
    "subdomain": "email",
    "domain": "example.com",
    "valid": true,
    "legacy": false,
    "a_record": {
      "valid": true,
      "type": "a",
      "host": "o1.email.example.com",
      "data": "192.168.1.1"
    }
  },
  {
    "id": 2,
    "ip": "192.168.1.2",
    "rdns": "o2.email.example.com",
    "users": [
      {
        "username": "john@example.com",
        "user_id": 7
      },
      {
        "username": "jane@example2.com",
        "user_id": 9
      }
    ],
    "subdomain": "email",
    "domain": "example.com",
    "valid": true,
    "legacy": false,
    "a_record": {
      "valid": true,
      "type": "a",
      "host": "o2.email.example.com",
      "data": "192.168.1.2"
    }
  }
]

Create an IP [POST]

Request Attribute Required Requirements Description
ip Yes string IP to whitelabel.
Example: 192.168.1.1
domain Yes string Domain that will be used to send messages on the IP.
Example: example.com
subdomain Yes string Subdomain that will be used to send messages on the IP.
Example: email

Request

1
POST https://api.sendgrid.com/v3/whitelabel/ips HTTP/1.1
Request Body
1
2
3
4
5
{
  "ip": "192.168.1.1",
  "subdomain": "email",
  "domain": "example.com"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
HTTP/1.1 201
{
  "id": 123,
  "ip": "192.168.1.2",
  "rdns": "o1.email.example.com",
  "users": [

  ],
  "subdomain": "email",
  "domain": "example.com",
  "valid": true,
  "legacy": false,
  "a_record": {
    "valid": true,
    "type": "a",
    "host": "o1.email.example.com",
    "data": "192.168.1.2"
  }
}

Retrieve an IP [GET]

Request

1
GET https://api.sendgrid.com/v3/whitelabel/ips/{id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 200
{
  "ip": "192.168.1.1",
  "rdns": "o1.email.example.com",
  "users": [
    {
      "username": "john@example.com",
      "user_id": 7
    }
  ],
  "subdomain": "email",
  "domain": "example.com",
  "valid": true,
  "legacy": false,
  "a_record": {
    "valid": true,
    "type": "a",
    "host": "o1.email.example.com",
    "data": "192.168.1.1"
  }
}

Delete an IP [DELETE]

Request

1
DELETE https://api.sendgrid.com/v3/whitelabel/ips/{id} HTTP/1.1

Response

1
HTTP/1.1 204

Validate an IP [POST]

Request

1
POST https://api.sendgrid.com/v3/whitelabel/ips/{id}/validate HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1 200
{
  "id": 1,
  "valid": true,
  "validation_results": {
    "a_record": {
      "valid": true,
      "reason": null
    }
  }
}

Request

1
POST https://api.sendgrid.com/v3/whitelabel/ips/{id}/validate HTTP/1.1

Response

1
2
3
4
5
6
7
8
HTTP/1.1 500
{
  "errors": [
    {
      "message": "internal error getting rDNS"
    }
  ]
}