Menu

Expand
Rate this page:

Domain Authentication

An authenticated domain allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will get 2 TXT records and 1 MX record.

Domain Authentication was formerly called "Domain Whitelabel".

For more information, please see How to set up domain authentication.

Authenticate a domain

POST /v3/whitelabel/domains

Base url: https://api.sendgrid.com

This endpoint allows you to authenticate a domain.

If you are authenticating a domain for a subuser, you have two options: 1. Use the "username" parameter. This allows you to authenticate a domain on behalf of your subuser. This means the subuser is able to see and modify the authenticated domain. 2. Use the Association workflow (see Associate Domain section). This allows you to authenticate a domain created by the parent to a subuser. This means the subuser will default to the assigned domain, but will not be able to see or modify that authenticated domain. However, if the subuser authenticates their own domain it will overwrite the assigned domain.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required
on-behalf-of
string
default: The subuser's username. This header generates the API call as if the subuser account was making the call.

Request Body

object
domain
string

Domain being authenticated.

required
subdomain
string

The subdomain to use for this authenticated domain.

username
string

The username associated with this domain.

ips
array[string]

The IP addresses that will be included in the custom SPF record for this authenticated domain.

custom_spf
boolean

Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to authenticated domains set up for manual security.

default
boolean

Whether to use this authenticated domain as the fallback if no authenticated domains match the sender's domain.

automatic_security
boolean

Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.

custom_dkim_selector
string

Add a custom DKIM selector. Accepts three letters or numbers.

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

Responses

object
id
number

The ID of the authenticated domain.

required
user_id
number

The ID of the user that this domain is associated with.

required
subdomain
string

The subdomain to use for this authenticated domain.

required
domain
string

The domain to be authenticated.

required
username
string

The username that this domain will be associated with.

required
ips
array[string]

The IPs to be included in the custom SPF record for this authenticated domain.

required
custom_spf
boolean

Indicates whether this authenticated domain uses custom SPF.

required
default
boolean

Indicates if this is the default authenticated domain.

required
legacy
boolean

Indicates if this authenticated domain was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create a new authenticated domain if you need to update it.

required
automatic_security
boolean

Indicates if this authenticated domain uses automated security.

required
valid
boolean

Indicates if this is a valid authenticated domain.

required
dns
object

The DNS records used to authenticate the sending domain.

required
mail_cname
object

The CNAME for your sending domain that points to sendgrid.net.

required
valid
boolean

Indicates if this is a valid CNAME.

required
type
string

The type of DNS record.

required
host
string

The domain that this CNAME is created for.

format: hostname
required
data
string

The CNAME record.

required
dkim1
object

A DNS record.

required
valid
boolean

Indicates if this is a valid DNS record.

required
type
string

The type of DNS record.

required
host
string

The domain that this DNS record was created for.

required
data
string

The DNS record.

required
dkim2
object

A DNS record.

required
valid
boolean

Indicates if this is a valid DNS record.

required
type
string

The type of DNS record.

required
host
string

The domain that this DNS record was created for.

required
data
string

The DNS record.

required
{
  "id": 45373692,
  "user_id": 66036447,
  "subdomain": "sub",
  "domain": "example.com",
  "username": "jdoe",
  "ips": [
    "127.0.0.1"
  ],
  "custom_spf": false,
  "default": true,
  "legacy": false,
  "automatic_security": true,
  "valid": true,
  "dns": {
    "mail_cname": {
      "valid": true,
      "type": "cname",
      "host": "mail.example.com",
      "data": "u7.wl.sendgrid.net"
    },
    "dkim1": {
      "valid": true,
      "type": "cname",
      "host": "s1._domainkey.example.com",
      "data": "s1._domainkey.u7.wl.sendgrid.net"
    },
    "dkim2": {
      "valid": true,
      "type": "cname",
      "host": "s2._domainkey.example.com",
      "data": "s2._domainkey.u7.wl.sendgrid.net"
    }
  }
}
        
        
        
        Rate this page:

        Need some help?

        We all do sometimes. Get help now from the Twilio SendGrid Support Team.

        Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

              
              
              

              Thank you for your feedback!

              Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

              Sending your feedback...
              🎉 Thank you for your feedback!
              Something went wrong. Please try again.

              Thanks for your feedback!

              Refer us and get $10 in 3 simple steps!

              Step 1

              Get link

              Get a free personal referral link here

              Step 2

              Give $10

              Your user signs up and upgrade using link

              Step 3

              Get $10

              1,250 free SMSes
              OR 1,000 free voice mins
              OR 12,000 chats
              OR more