Link Whitelabel

A link whitelabel consists of a subdomain and domain that will be used to rewrite links in mail messages. Our customer will be asked to create a couple CNAME records for the links to be rewritten to and for us to verify that they are the domain owners.

List all Links [GET]

Request

1
GET https://api.sendgrid.com/v3/whitelabel/links 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
HTTP/1.1 200
[
  {
    "id": 1,
    "domain": "example.com",
    "subdomain": "mail",
    "username": "john@example.com",
    "user_id": 7,
    "default": true,
    "valid": true,
    "legacy": false,
    "dns": {
      "domain_cname": {
        "valid": true,
        "type": "cname",
        "host": "mail.example.com",
        "data": "sendgrid.net"
      },
      "owner_cname": {
        "valid": true,
        "type": "cname",
        "host": "7.example.com",
        "data": "sendgrid.net"
      }
    }
  },
  {
    "id": 2,
    "domain": "example2.com",
    "subdomain": "news",
    "username": "john@example.com",
    "user_id": 8,
    "default": false,
    "valid": false,
    "legacy": false,
    "dns": {
      "domain_cname": {
        "valid": true,
        "type": "cname",
        "host": "news.example2.com",
        "data": "sendgrid.net"
      },
      "owner_cname": {
        "valid": false,
        "type": "cname",
        "host": "8.example2.com",
        "data": "sendgrid.net"
      }
    }
  }
]

Create a Link [POST]

Request Attribute Required Requirements Description
domain Yes string Domain to create the whitelabel for.
Example: example.com
subdomain Yes string Subdomain to create the whitelabel for.
Example: mail
default No boolean Whether to use this link whitelabel as the fallback when a match cannot be found.
Example: true

Request

1
POST https://api.sendgrid.com/v3/whitelabel/links HTTP/1.1
Request Body
1
2
3
4
5
{
  "domain": "example.com",
  "subdomain": "mail",
  "default": 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
HTTP/1.1 201
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "default": false,
  "valid": true,
  "legacy": false,
  "dns": {
    "domain_cname": {
      "valid": true,
      "type": "cname",
      "host": "mail.example.com",
      "data": "sendgrid.net"
    },
    "owner_cname": {
      "valid": true,
      "type": "cname",
      "host": "7.example.com",
      "data": "sendgrid.net"
    }
  }
}

Retrieve a Link [GET]

URI Parameter Required Requirements Description
ID Yes integer The ID of your link whitelabel
Example: 1234

Request

1
GET https://api.sendgrid.com/v3/whitelabel/links/{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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "default": false,
  "valid": true,
  "legacy": false,
  "dns": {
    "domain_cname": {
      "valid": true,
      "type": "cname",
      "host": "mail.example.com",
      "data": "sendgrid.net"
    },
    "owner_cname": {
      "valid": true,
      "type": "cname",
      "host": "7.example.com",
      "data": "sendgrid.net"
    }
  }
}

Update a Link [PATCH]

URI Parameter Required Requirements Description
ID Yes integer The ID of your link whitelabel
Example: 1234

Request

1
PATCH https://api.sendgrid.com/v3/whitelabel/links/{id} HTTP/1.1
Request Body
1
2
3
{
  "default": 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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "default": true,
  "valid": true,
  "legacy": false,
  "dns": {
    "domain_cname": {
      "valid": true,
      "type": "cname",
      "host": "mail.example.com",
      "data": "sendgrid.net"
    },
    "owner_cname": {
      "valid": true,
      "type": "cname",
      "host": "7.example.com",
      "data": "sendgrid.net"
    }
  }
}

Delete a Link [DELETE]

URI Parameter Required Requirements Description
ID Yes integer The ID of your link whitelabel
Example: 1234

Request

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

Response

1
HTTP/1.1 204
Default link is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order:
  • Validated link whitelabels marked as "default"
  • Legacy link whitelabels (migrated from the whitelabel wizard)
  • Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net)

Default Link [GET]

URI Parameter Required Requirements Description
domain No string Domain to match against when finding a corresponding link whitelabel.

Request

1
GET https://api.sendgrid.com/v3/whitelabel/links/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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "default": false,
  "valid": true,
  "legacy": false,
  "dns": {
    "domain_cname": {
      "valid": true,
      "type": "cname",
      "host": "mail.example.com",
      "data": "sendgrid.net"
    },
    "owner_cname": {
      "valid": true,
      "type": "cname",
      "host": "7.example.com",
      "data": "sendgrid.net"
    }
  }
}

Validate a Link [POST]

Request

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 200
{
  "id": 1,
  "valid": true,
  "validation_results": {
    "domain_cname": {
      "valid": false,
      "reason": "Expected CNAME to match \"sendgrid.net.\" but found \"example.com.\"."
    },
    "owner_cname": {
      "valid": true,
      "reason": null
    }
  }
}

Request

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

Response

1
2
3
4
5
6
7
8
HTTP/1.1 500
{
  "errors": [
    {
      "message": "internal error getting CNAME"
    }
  ]
}
Link 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 Link [GET]

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

Request

1
GET https://api.sendgrid.com/v3/whitelabel/links/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
HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "default": false,
  "valid": true,
  "legacy": false,
  "dns": {
    "domain_cname": {
      "valid": true,
      "type": "cname",
      "host": "mail.example.com",
      "data": "sendgrid.net"
    },
    "owner_cname": {
      "valid": true,
      "type": "cname",
      "host": "7.example.com",
      "data": "sendgrid.net"
    }
  }
}

Disassociate Link [DELETE]

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

Request

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

Response

1
HTTP/1.1 204

Associate Link [POST]

URI Parameter Required Requirements Description
link_id Yes string Username of the subuser to retrieve associated links for.
Request Attribute Required Requirements Description
username Yes string User to associate with the link whitelabel.
Example: jane@example.com

Request

1
POST https://api.sendgrid.com/v3/whitelabel/links/{link_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
HTTP/1.1 201
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "default": false,
  "valid": true,
  "legacy": false,
  "dns": {
    "domain_cname": {
      "valid": true,
      "type": "cname",
      "host": "mail.example.com",
      "data": "sendgrid.net"
    },
    "owner_cname": {
      "valid": true,
      "type": "cname",
      "host": "7.example.com",
      "data": "sendgrid.net"
    }
  }
}