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.

Authenticate a domain

Authenticate a domain

POST /whitelabel/domains

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

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.