View and Edit

Whitelabel

All Whitelabel records that are successfully created on the parent account are available here. These can be attached to one or more subusers. mail_domain and url_domain should be the same in almost all cases.

Whitelabel records cannot be created via API, only via the web UI. The API is used to create and modify subuser-whitelabel relationships.

Take note that IPs have records in line with Whitelabel records, but are not assigned with these commands. Subusers can be assigned to a mismatched whitelabel and IP, but should not be. There is no call at this time to note the whitelabeled rDNS record on the IP, DNS commands can be used to query these public records.

List

URI Parameter Required Requirements Description
task Yes Must be set to list Task to list existing whitelabel records on the account
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.whitelabel.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=list

Response

1
2
3
4
5
6
7
8
9
10

[
  {
    "mail_domain": "em.domain1.com",
    "url_domain": "em.domain1.com"
  },
  {
    "mail_domain": "em.domain2.com",
    "url_domain": "em.domain2.com"
  }
]

Call

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

Response

1
2
3
4
5
6
7
8
9
10

<whitelabels>
   <whitelabel>
      <mail_domain>em.domain1.com</mail_domain>
      <url_domain>em.domain1.com</url_domain>
   </whitelabel>
   <whitelabel>
      <mail_domain>em.domain2.com</mail_domain>
      <url_domain>em.domain2.com</url_domain>
   </whitelabel>
</whitelabels>

Attach

Attaching a new whitelabel record to a subuser also removes any previously-attached whitelabel. This does not affect already-sent messages.

URI Parameter Required Requirements Description
task Yes Must be set to append Task to attach subuser to existing whitelabel record
user Yes Subuser must be under your account Subuser to modify whitelabel association of
mail_domain Yes sub.domain.com format Existing whitelabel record to attach to subuser
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.whitelabel.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=append&user=subuser_username&mail_domain=em.domain1.com

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.whitelabel.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=append&user=subuser_username&mail_domain=em.domain1.com

Response

1
2
3

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