The Twilio SendGrid Domain Authentication API allows you to manage your authenticated domains and their settings. Domain Authentication is a required step when setting up your Twilio SendGrid account because it's essential to ensuring the deliverability of your email. Domain Authentication signals trustworthiness to email inbox providers and your recipients by approving SendGrid to send email on behalf of your domain.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Domain Authentication API
summary: The Twilio SendGrid Domain Authentication API allows you to manage your
authenticated domains and their settings.
description: 'The Twilio SendGrid Domain Authentication API allows you to manage
your authenticated domains and their settings.
Domain Authentication is a required step when setting up your Twilio SendGrid
account because it''s essential to ensuring the deliverability of your email.
Domain Authentication signals trustworthiness to email inbox providers and your
recipients by approving SendGrid to send email on behalf of your domain. For more
information, see [**How to Set Up Domain Authentication**](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/).
Each user may have a maximum of 3,000 authenticated domains and 3,000 link brandings.
This limit is at the user level, meaning each Subuser belonging to a parent account
may have its own 3,000 authenticated domains and 3,000 link brandings.'
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: domain_authentication
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
paths:
/v3/whitelabel/dns/email:
post:
operationId: EmailDnsRecord
summary: Email DNS records to a co-worker
tags:
- Domain Authentication
description: "**This endpoint is used to share DNS records with a colleagues**\n\
\nUse this endpoint to send SendGrid-generated DNS record information to a\
\ co-worker so they can enter it into your DNS provider to validate your domain\
\ and link branding. \n\nWhat type of records are sent will depend on whether\
\ you have chosen Automated Security or not. When using Automated Security,\
\ SendGrid provides you with three CNAME records. If you turn Automated Security\
\ off, you are instead given TXT and MX records.\n\nIf you pass a `link_id`\
\ to this endpoint, the generated email will supply the DNS records necessary\
\ to complete [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/)\
\ setup. If you pass a `domain_id` to this endpoint, the generated email will\
\ supply the DNS records needed to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/).\
\ Passing both IDs will generate an email with the records needed to complete\
\ both setup steps.\n\nYou can retrieve all your domain IDs from the returned\
\ `id` fields for each domain using the \"List all authenticated domains\"\
\ endpoint. You can retrieve all of your link IDs using the \"Retrieve all\
\ branded links\" endpoint."
requestBody:
content:
application/json:
schema:
type: object
properties:
link_id:
type: integer
minimum: 0
description: The ID of the branded link.
domain_id:
type: integer
minimum: 0
description: The ID of your SendGrid domain record.
email:
type: string
format: email
description: The email address to send the DNS information to.
message:
type: string
default: Please set these DNS records in our hosting solution.
description: A custom text block to include in the email body sent
with the records.
required:
- link_id
- domain_id
- email
example:
link_id: 29719392
domain_id: 46873408
email: [email protected]
message: DNS Record for verification
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
error:
type: string
field:
type: string
/v3/whitelabel/domains:
get:
operationId: ListAuthenticatedDomain
summary: List all authenticated domains
tags:
- Domain Authentication
description: '**This endpoint allows you to retrieve a paginated list of all
domains you have authenticated.**
You can use the `limit` query parameter to set the page size. If your list
contains more items than the page size permits, you can make multiple requests.
Use the `offset` query parameter to control the position in the list from
which to start retrieving additional items.'
parameters:
- name: limit
in: query
description: '`limit` sets the page size, i.e. maximum number of items from
the list to be returned for a single API request. If omitted, the default
page size is used.'
schema:
type: integer
- $ref: '#/components/parameters/PaginationCommonOffset'
- name: exclude_subusers
in: query
description: Exclude subuser domains from the result.
schema:
type: boolean
- name: username
in: query
description: The username associated with an authenticated domain.
schema:
type: string
- name: domain
in: query
description: Search for authenticated domains.
schema:
type: string
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
$ref: '#/components/responses/DomainAuthentication200'
post:
operationId: AuthenticateDomain
summary: Authenticate a domain
tags:
- Domain Authentication
description: '**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.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
type: object
properties:
domain:
type: string
description: Domain being authenticated.
subdomain:
type: string
description: The subdomain or custom return-path to use for this
authenticated domain.
username:
type: string
description: The username associated with this domain.
ips:
type: array
description: The IP addresses that will be included in the custom
SPF record for this authenticated domain.
items:
type: string
custom_spf:
type: boolean
description: 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:
type: boolean
description: Whether to use this authenticated domain as the fallback
if no authenticated domains match the sender's domain.
automatic_security:
type: boolean
description: Whether to allow SendGrid to manage your SPF records,
DKIM keys, and DKIM key rotation.
custom_dkim_selector:
type: string
description: Add a custom DKIM selector. Accepts three letters or
numbers.
region:
type: string
description: The region of the domain. Allowed values are `global`
and `eu`. The default value is `global`.
required:
- domain
example:
domain: example.com
subdomain: news
username: [email protected]
ips:
- 192.168.1.1
- 192.168.1.2
custom_spf: true
default: true
automatic_security: false
custom_dkim_selector: string
region: global
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticatedDomain'
examples:
response:
value:
id: 302183
user_id: 1446226
subdomain: example
domain: example.com
username: mbernier
ips: []
custom_spf: false
default: true
legacy: false
automatic_security: true
valid: false
dns:
mail_cname:
valid: false
type: cname
host: example.example.com
data: u1446226.wl.sendgrid.net
dkim1:
valid: false
type: cname
host: s1._domainkey.example.com
data: s1.domainkey.u1446226.wl.sendgrid.net
dkim2:
valid: false
type: cname
host: s2._domainkey.example.com
data: s2.domainkey.u1446226.wl.sendgrid.net
/v3/whitelabel/domains/{domain_id}:
parameters:
- name: domain_id
in: path
required: true
schema:
type: string
get:
operationId: GetAuthenticatedDomain
summary: Retrieve an authenticated domain
tags:
- Domain Authentication
description: '**This endpoint allows you to retrieve a specific authenticated
domain.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticatedDomain'
examples:
response:
value:
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
patch:
operationId: UpdateAuthenticatedDomain
summary: Update an authenticated domain
tags:
- Domain Authentication
description: '**This endpoint allows you to update the settings for an authenticated
domain.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
type: object
properties:
default:
type: boolean
default: false
description: Indicates whether this is the default authenticated
domain.
custom_spf:
type: boolean
default: false
description: Indicates whether to generate a custom SPF record for
manual security.
example:
default: false
custom_spf: true
responses:
'200':
$ref: '#/components/responses/DomainAuthentication200'
delete:
operationId: DeleteAuthenticatedDomain
summary: Delete an authenticated domain.
tags:
- Domain Authentication
description: '**This endpoint allows you to delete an authenticated domain.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'204':
description: ''
/v3/whitelabel/domains/{domain_id}/subuser:
post:
operationId: AssociateSubuserWithDomain
summary: Associate an authenticated domain with a given user.
tags:
- Domain Authentication
description: '**This endpoint allows you to associate a specific authenticated
domain with a subuser.**
Authenticated domains can be associated with (i.e. assigned to) subusers from
a parent account. This functionality allows subusers to send mail using their
parent''s domain. To associate an authenticated domain with a subuser, the
parent account must first authenticate and validate the domain. The parent
may then associate the authenticated domain via the subuser management tools.
[You can associate more than one domain with a subuser using the `v3/whitelabel/domains/{domain_id}/subuser:add`
endpoint](https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication/associate-an-authenticated-domain-with-a-subuser-multiple).'
parameters:
- name: domain_id
in: path
description: ID of the authenticated domain to associate with the subuser.
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: Username to associate with the authenticated domain.
required:
- username
example:
username: jdoe
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticatedDomainSpf'
examples:
response:
value:
id: 1
domain: example.com
subdomain: mail
username: jdoe
user_id: 7
ips: []
custom_spf: true
default: false
legacy: false
automatic_security: false
valid: false
dns:
mail_server:
host: mail.example.com
type: mx
data: sendgrid.net
valid: false
subdomain_spf:
host: mail.example.com
type: txt
data: v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all
valid: false
domain_spf:
host: example.com
type: txt
data: v=spf1 include:mail.example.com -all
valid: false
dkim:
host: s1._domainkey.example.com
type: txt
data: k=rsa; t=s; p=publicKey
valid: false
delete:
operationId: DisassociateSubuserFromDomain
summary: Disassociate an authenticated domain from a given user for users with
up to five associated domains.
tags:
- Domain Authentication
description: "**This endpoint allows you to disassociate a specific authenticated\
\ domain from a subuser, for users with up to five associated domains.**\n\
\n\nThis functionality allows subusers to send mail using their parent's domain.\
\ Authenticated domains can be associated with (i.e. assigned to) subusers\
\ kknt, and a subuser can have up to five associated authenticated domains.\
\ \n\nYou can dissociate an authenticated domain from any subuser that has\
\ one or more authenticated domains using this endpoint."
parameters:
- name: username
in: query
description: Username for the subuser to find associated authenticated domain.
schema:
type: string
- name: domain_id
in: path
description: ID of the authenticated domain to be disassociated with the subuser.
required: true
schema:
type: integer
responses:
'204':
description: ''
/v3/whitelabel/domains/{domain_id}/subuser:add:
parameters:
- name: domain_id
in: path
description: ID of the authenticated domain to associate with the subuser.
required: true
schema:
type: integer
post:
operationId: AssociateSubuserWithDomainMultiple
summary: Associate an authenticated domain with a given user, for up to five
domains.
tags:
- Domain Authentication
description: "**This endpoint allows you to associate a specific authenticated\
\ domain with a subuser. It can be used to associate up to five authenticated\
\ domains.**\n\n\nThis functionality allows subusers to send mail using their\
\ parent's domain. Authenticated domains can be associated with (i.e. assigned\
\ to) subusers from a parent account. To associate an authenticated domain\
\ with a subuser, the parent account must first authenticate and validate\
\ the domain. The parent may then associate the authenticated domain via the\
\ subuser management tools.\n\n\nA subuser can have up to five associated\
\ authenticated domains. To see the domains that have already been associated\
\ with this user, you can [use the API to list the domains currently associated\
\ with the subuser](https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication/list-the-authenticated-domain-associated-with-a-subuser-multiple).\n\
\n\nWhen selecting a domain to send email from, SendGrid checks for domains\
\ in the following order and chooses the first one that appears in the hierarchy:\
\ \n1. Domain assigned by the subuser that matches the email's `From` address\
\ domain. \n2. The subuser's default domain. \n3. Domain assigned by the parent\
\ user that matches the `From` address domain. \n4. Parent user's default\
\ domain. \n5. sendgrid.net"
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: Username to associate with the authenticated domain.
required:
- username
example:
username: jdoe
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticatedDomainSpf'
examples:
response:
value:
id: 1
domain: example.com
subdomain: mail
username: jdoe
user_id: 7
ips: []
custom_spf: true
default: false
legacy: false
automatic_security: false
valid: false
dns:
mail_server:
host: mail.example.com
type: mx
data: sendgrid.net
valid: false
subdomain_spf:
host: mail.example.com
type: txt
data: v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all
valid: false
domain_spf:
host: example.com
type: txt
data: v=spf1 include:mail.example.com -all
valid: false
dkim:
host: s1._domainkey.example.com
type: txt
data: k=rsa; t=s; p=publicKey
valid: false
/v3/whitelabel/domains/{id}/ips:
parameters:
- name: id
in: path
description: ID of the domain to which you are adding an IP
required: true
schema:
type: integer
post:
operationId: AddIpToAuthenticatedDomain
summary: Add an IP to an authenticated domain
tags:
- Domain Authentication
description: '**This endpoint allows you to add an IP address to an authenticated
domain.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
type: object
properties:
ip:
type: string
description: IP to associate with the domain. Used for manually
specifying IPs for custom SPF.
required:
- ip
example:
ip: 192.168.0.1
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticatedDomainSpf'
examples:
response:
value:
id: 1
domain: example.com
subdomain: mail
username: [email protected]
user_id: 7
ips: []
custom_spf: true
default: false
legacy: false
automatic_security: false
valid: false
dns:
mail_server:
host: mail.example.com
type: mx
data: sendgrid.net
valid: false
subdomain_spf:
host: mail.example.com
type: txt
data: v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all
valid: false
domain_spf:
host: example.com
type: txt
data: v=spf1 include:mail.example.com -all
valid: false
dkim:
host: s1._domainkey.example.com
type: txt
data: k=rsa; t=s; p=publicKey
valid: false
/v3/whitelabel/domains/{id}/ips/{ip}:
parameters:
- name: id
in: path
description: ID of the domain to delete the IP from.
required: true
schema:
type: integer
- name: ip
in: path
description: IP to remove from the domain.
required: true
schema:
type: string
delete:
operationId: DeleteIpFromAuthenticatedDomain
summary: Remove an IP from an authenticated domain.
tags:
- Domain Authentication
description: '**This endpoint allows you to remove an IP address from that domain''s
authentication.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticatedDomainSpf'
examples:
response:
value:
id: 1
domain: example.com
subdomain: mail
username: [email protected]
user_id: 7
ips: []
custom_spf: true
default: false
legacy: false
automatic_security: false
valid: false
dns:
mail_server:
host: mail.example.com
type: mx
data: sendgrid.net
valid: false
subdomain_spf:
host: mail.example.com
type: txt
data: v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all
valid: false
domain_spf:
host: example.com
type: txt
data: v=spf1 include:mail.example.com -all
valid: false
dkim:
host: s1._domainkey.example.com
type: txt
data: k=rsa; t=s; p=publicKey
valid: false
/v3/whitelabel/domains/{id}/validate:
parameters:
- name: id
in: path
description: ID of the domain to validate.
required: true
schema:
type: integer
post:
operationId: ValidateAuthenticatedDomain
summary: Validate a domain authentication.
tags:
- Domain Authentication
description: '**This endpoint allows you to validate an authenticated domain.
If it fails, it will return an error message describing why the domain could
not be validated.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: The ID of the authenticated domain.
valid:
type: boolean
description: Indicates if this is a valid authenticated domain.
validation_results:
type: object
description: The individual DNS records that are checked when
validating, including the reason for any invalid DNS records.
properties:
mail_cname:
type: object
description: The CNAME record for the authenticated domain.
properties:
valid:
type: boolean
description: Indicates if this DNS record is valid.
reason:
description: The reason this record is invalid.
nullable: true
type: string
dkim1:
type: object
description: A DNS record for this authenticated domain.
properties:
valid:
type: boolean
description: Indicates if the DNS record is valid.
reason:
nullable: true
type: string
dkim2:
type: object
description: A DNS record for this authenticated domain.
properties:
valid:
type: boolean
description: Indicates if the DNS record is valid.
reason:
nullable: true
type: string
spf:
type: object
description: The SPF record for the authenticated domain.
properties:
valid:
type: boolean
description: Indicates if the SPF record is valid.
reason:
nullable: true
type: string
examples:
response:
value:
id: 1
valid: true
validation_resuts:
mail_cname:
valid: false
reason: Expected your MX record to be "mx.sendgrid.net" but
found "example.com".
dkim1:
valid: true
reason: null
dkim2:
valid: true
reason: null
spf:
valid: true
reason: null
'500':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
description: A message explaining the reason for the error.
required:
- message
examples:
response:
value:
errors:
- message: internal error getting TXT
/v3/whitelabel/domains/default:
get:
operationId: ListDefaultAuthenticatedDomain
summary: Get the default authentication
tags:
- Domain Authentication
description: '**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.'
parameters:
- name: domain
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_domain_authentication_v3.yaml