Menu

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.

Get the default authentication

Get the default authentication

GET /whitelabel/domains/default

This endpoint allows you to retrieve the default authentication for a domain.

When creating or updating a domain authentication, you can set the domain as a default. The default domain will be used to send all mail. If you have multiple authenticated domains, the authenticated domain matching the domain of the From address will be used, and the default will be overridden.

This endpoint will return a default domain and its details only if a default is set. You are not required to set a default. If you do not set a default domain, this endpoint will return general information about your domain authentication status.

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.

Query String

domain
string

The domain to find a default authentication.

default: None

Responses

array[object]
id
number

The ID of the authenticated domain.

user_id
number

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

subdomain
string

The subdomain to use for this authenticated domain.

domain
string

The domain to be authenticated.

username
string

The username that this domain will be associated with.

ips
array[string]

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

custom_spf
boolean

Indicates whether this authenticated domain uses custom SPF.

default
boolean

Indicates if this is the default authenticated domain.

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.

automatic_security
boolean

Indicates if this authenticated domain uses automated security.

valid
boolean

Indicates if this is a valid authenticated domain.

dns
object

The DNS records used to authenticate the sending domain.

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
subusers
array[object]
user_id
integer

The ID of the subuser that this authenticated domain will be associated with.

username
string

The username of the subuser that this authenticated domain is associated with.

last_validation_attempt_at
integer

A Unix epoch timestamp representing the last time of a validation attempt.

[
  {
    "id": 1,
    "user_id": 7,
    "subdomain": "mail",
    "domain": "example.com",
    "username": "jane@example.com",
    "ips": [
      "192.168.1.1",
      "192.168.1.2"
    ],
    "custom_spf": true,
    "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"
      }
    }
  },
  {
    "id": 2,
    "user_id": 8,
    "subdomain": "new",
    "domain": "example2.com",
    "username": "john@example2.com",
    "ips": [],
    "custom_spf": false,
    "default": true,
    "legacy": false,
    "automatic_security": true,
    "valid": false,
    "dns": {
      "mail_cname": {
        "valid": false,
        "type": "mx",
        "host": "news.example2.com",
        "data": "sendgrid.net"
      },
      "dkim1": {
        "valid": false,
        "type": "txt",
        "host": "example2.com",
        "data": "k=rsa; t=s; p=publicKey"
      },
      "dkim2": {
        "valid": false,
        "type": "txt",
        "host": "example2.com",
        "data": "k=rsa; t=s p=publicKey"
      }
    }
  }
]
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.

Thank you for your feedback!

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

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