Domain Whitelabels

A domain whitelabel consists of a subdomain and domain that will be used to set the appropriate DKIM, SPF, and Return-Path. There is an option to allow SendGrid to manage security or the customers may manage their own DNS records. For customers using the manual security option, they will need to create the appropriate MX, DKIM, and SPF records with their hosting provider. With automatic security, the customer will just need to create a few CNAMEs to SendGrid, and SendGrid will manage the MX, DKIM and SPF records.

List all Domains [GET]

URI Parameter Required Requirements Description
limit No number Number of domains to return. Defaults to 50.
Example: 50
offset No number Paging offset. Defaults to 0.
Example: 0
exclude_subusers No boolean Exclude subuser domains from the results. Defaults to "false".
Example: true
username No string Search for domain whitelabels belonging to the given user.
Example: john
domain No string Search for domain whitelabels that match the given domain.
Example: example.com

Request

1
GET https://api.sendgrid.com/v3/whitelabel/domains?exclude_subusers={exclude_subusers}&limit={limit}&offset={offset}&username={username}&domain={domain} 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
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
HTTP/1.1 200
[
  {
    "id": 1,
    "domain": "example.com",
    "subdomain": "mail",
    "username": "john@example.com",
    "user_id": 7,
    "ips": [
      "192.168.1.1",
      "192.168.1.2"
    ],
    "custom_spf": true,
    "default": true,
    "legacy": false,
    "automatic_security": true,
    "valid": true,
    "dns": {
      "mail_cname": {
        "host": "mail.example.com",
        "type": "cname",
        "data": "u7.wl.sendgrid.net",
        "valid": true
      },
      "spf": {
        "host": "example.com",
        "type": "txt",
        "data": "v=spf1 include:u7.wl.sendgrid.net -all",
        "valid": true
      },
      "dkim1": {
        "host": "s1.<em>domainkey.example.com",
        "type": "cname",
        "data": "s1.<em>domainkey.u7.wl.sendgrid.net",
        "valid": true
      },
      "dkim2": {
        "host": "s2._domainkey.example.com",
        "type": "cname",
        "data": "s2._domainkey.u7.wl.sendgrid.net",
        "valid": true
      }
    }
  },
  {
    "id": 2,
    "domain": "example2.com",
    "subdomain": "news",
    "username": "jane@example2.com",
    "user</em>id": 8,
    "ips": [

    ],
    "custom_spf": false,
    "default": true,
    "legacy": false,
    "automatic_security": true,
    "valid": false,
    "dns": {
      "mail_server": {
        "host": "news.example2.com",
        "type": "mx",
        "data": "sendgrid.net",
        "valid": false
      },
      "subdomain</em>spf": {
        "host": "news.example2.com",
        "type": "txt",
        "data": "v=spf1 include:sendgrid.net ~all",
        "valid": false
      },
      "domain_spf": {
        "host": "example2.com",
        "type": "txt",
        "data": "v=spf1 include:news.example2.com -all",
        "valid": false
      },
      "dkim": {
        "host": "s1._domainkey.example2.com",
        "type": "txt",
        "data": "k=rsa; t=s; p=publicKey",
        "valid": false
      }
    }
  }
]

Create a Domain [POST]

You may create up to a maximum of 1500 domain whitelabels.

Request Attribute Required Requirements Description
domain Yes string Domain being whitelabeled.
Example: example.com
subdomain Yes string Subdomain being whitelabeled.
Example: news
automatic_security No boolean Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.
Example: false
custom_spf No boolean Specify whether to use a custom spf or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security.
Example: true
default No boolean Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain.
Example: false

Request

1
POST https://api.sendgrid.com/v3/whitelabel/domains HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12
{
  "domain": "example.com",
  "subdomain": "news",
  "username": "john@example.com",
  "ips": [
    "192.168.1.1",
    "192.168.1.2"
  ],
  "custom_spf": true,
  "default": true,
  "automatic_security": false
}

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
HTTP/1.1 201
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [
    "192.168.1.1",
    "192.168.1.2"
  ],
  "custom_spf": true,
  "default": true,
  "legacy": false,
  "automatic_security": true,
  "valid": true,
  "dns": {
    "mail_cname": {
      "host": "mail.example.com",
      "type": "cname",
      "data": "u7.wl.sendgrid.net",
      "valid": true
    },
    "spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:u7.wl.sendgrid.net -all",
      "valid": true
    },
    "dkim1": {
      "host": "s1.<em>domainkey.example.com",
      "type": "cname",
      "data": "s1._domainkey.u7.wl.sendgrid.net",
      "valid": true
    },
    "dkim2": {
      "host": "s2.</em>domainkey.example.com",
      "type": "cname",
      "data": "s2._domainkey.u7.wl.sendgrid.net",
      "valid": true
    }
  }
}

Retrieve a Domain [GET]

URI Parameter Required Requirements Description
id Yes number The ID of the domain you're whitelabeling
Example: 1234

Request

1
GET https://api.sendgrid.com/v3/whitelabel/domains/{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
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [
    "192.168.1.1",
    "192.168.1.2"
  ],
  "custom_spf": true,
  "default": true,
  "legacy": false,
  "automatic_security": true,
  "valid": true,
  "dns": {
    "mail_cname": {
      "host": "mail.example.com",
      "type": "cname",
      "data": "u7.wl.sendgrid.net",
      "valid": true
    },
    "spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:u7.wl.sendgrid.net -all",
      "valid": true
    },
    "dkim1": {
      "host": "s1.<em>domainkey.example.com",
      "type": "cname",
      "data": "s1._domainkey.u7.wl.sendgrid.net",
      "valid": true
    },
    "dkim2": {
      "host": "s2.</em>domainkey.example.com",
      "type": "cname",
      "data": "s2._domainkey.u7.wl.sendgrid.net",
      "valid": true
    }
  }
}

Update a Domain [PATCH]

URI Parameter Required Requirements Description
id Yes number The ID of the domain you're whitelabeling
Example: 1234
Request Attribute Required Requirements Description
default No boolean Inidcates whether this domain whitelabel should be considered the default. Defaults to false.
Example: false
custom_spf No boolean Indicates whether to generate a custom SPF record for manual security. Defaults to false.
Example: false

Request

1
PATCH https://api.sendgrid.com/v3/whitelabel/domains/{id} HTTP/1.1
Request Body
1
2
3
4
{
  "default": false,
  "custom_spf": true
}

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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Delete a Domain [DELETE]

URI Parameter Required Requirements Description
id Yes number The ID of the domain you're whitelabeling
Example: 1234

Request

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

Response

1
HTTP/1.1 204

Default Domain [GET]

URI Parameter Required Requirements Description
domain No string The sending domain against which to compare the domain whitelabel.
Example: em.example.com

Request

1
GET https://api.sendgrid.com/v3/whitelabel/domains/default?domain={domain} 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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [
    "192.168.1.1"
  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Add an IP to a Domain [POST]

URI Parameter Required Requirements Description
id Yes number ID of the domain to which you are adding an IP.
Example: 1234
Request Attribute Required Requirements Description
ip Yes string IP to associate with the domain. Used for manually specifying IPs for custom SPF.
Example: 192.168.0.1

Request

1
POST https://api.sendgrid.com/v3/whitelabel/domains/{id}/ips HTTP/1.1
Request Body
1
2
3
{
  "ip": "192.168.0.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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Remove an IP from a Domain [DELETE]

URI Parameter Required Requirements Description
id Yes int ID of the domain whitelabel to delete the IP from.
Example: 1234
ip Yes string IP to remove from the domain whitelabel.
Example: 127.0.0.1

Request

1
DELETE https://api.sendgrid.com/v3/whitelabel/domains/{id}/ips/{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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "mail@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Validate Domain [POST]

URI Parameter Required Requirements Description
id Yes int ID of the domain whitelabel to validate.
Example: 1234

Request

1
POST https://api.sendgrid.com/v3/whitelabel/domains/{id}/validate 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
HTTP/1.1 200
{
  "id": 1,
  "valid": true,
  "validation_resuts": {
    "mail_cname": {
      "valid": false,
      "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\"."
    },
    "dkim1": {
      "valid": true,
      "reason": null
    },
    "dkim2": {
      "valid": true,
      "reason": null
    },
    "spf": {
      "valid": true,
      "reason": null
    }
  }
}
URI Parameter Required Requirements Description
id Yes int ID of the domain whitelabel to validate.
Example: 1234

Request

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

Response

1
2
3
4
5
6
7
8
HTTP/1.1 500
{
  "errors": [
    {
      "message": "internal error getting TXT"
    }
  ]
}
Domain Whitelabels can be associated with subusers via parent accounts. This functionality allows subusers to send mail off their parent's Whitelabels. To associate a Whitelabel, the parent account must first create a Whitelabel and validate it. Then the parent may associate the Whitelabel in subuser management.

List Associated Domain [GET]

URI Parameter Required Requirements Description
username Yes string Username of the subuser to find associated whitelabels for.

Request

1
GET https://api.sendgrid.com/v3/whitelabel/domains/subuser?username={username} 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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "mail@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Disassociate Domain [DELETE]

URI Parameter Required Requirements Description
username Yes string Username of the subuser to find associated whitelabels for.

Request

1
DELETE https://api.sendgrid.com/v3/whitelabel/domains/subuser HTTP/1.1

Response

1
HTTP/1.1 204

Associate Domain [POST]

URI Parameter Required Requirements Description
domain_id Yes integer Id of the domain whitelabel to associate with the subuser.
Example: 1234
Request Attribute Required Requirements Description
username Yes string Username to associate with the domain whitelabel.
Example: jane@example.com

Request

1
POST https://api.sendgrid.com/v3/whitelabel/domains/{domain_id}/subuser HTTP/1.1
Request Body
1
2
3
{
  "username": "jane@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
33
34
35
36
37
38
39
40
41
42
HTTP/1.1 201
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "mail@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}