Domain Authentication

All Domain Authentication(formerly known as 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.

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

Take note that IPs have records in line with domain authentication records, but are not assigned with these commands. Subusers can be assigned to a mismatched reverse DNS record, but should not be. There is no call at this time to note the reverse DNS 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 domain authentication records on the account

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

[
  {
    "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

<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 domain authentication record to a subuser removes any previously-attached record. 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 domain authentication record
user	Yes	Subuser must be under your account	Subuser whose domain authentication association will be modified
mail_domain	Yes	`sub.domain.com` format	Existing domain authentication record to attach to subuser

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

{
  "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

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

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

This documentation is for the SendGrid Web API v2

Need some help?

Thank you for your feedback!

Thanks for your feedback!

Step 1

Step 2

Step 3