Menu

Expand

This documentation is for the SendGrid Web API v2

To access all the latest features and upcoming developments, please see our v3 API.

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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.