The Twilio SendGrid Reverse DNS API (formerly IP Whitelabel) allows you to configure reverse DNS settings for your account. Mailbox providers verify the sender of your emails by performing a reverse DNS lookup. When setting up Reverse DNS, Twilio SendGrid will provide an A Record (address record) for you to add to the DNS records of your sending domain. The A record maps your sending domain to a dedicated Twilio SendGrid IP address.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Reverse DNS API
summary: The Twilio SendGrid Reverse DNS API (formerly IP Whitelabel) allows you
to configure reverse DNS settings for your account.
description: 'The Twilio SendGrid Reverse DNS API (formerly IP Whitelabel) allows
you to configure reverse DNS settings for your account. Mailbox providers verify
the sender of your emails by performing a reverse DNS lookup.
When setting up Reverse DNS, Twilio SendGrid will provide an A Record (address
record) for you to add to the DNS records of your sending domain. The A record
maps your sending domain to a dedicated Twilio SendGrid IP address. Once Twilio
SendGrid has verified that the appropriate A record for the IP address has been
created, the appropriate reverse DNS record for the IP address is generated.
Reverse DNS is available for [dedicated IP addresses](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/)
only.
You can also manage your reverse DNS settings in the Sender Authentication setion
of the [Twilio SendGrid application user interface](https://app.sendgrid.com/settings/sender_auth).
See [**How to Set Up Reverse DNS**](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/)
for more information.'
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: reverse_dns
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/ips:
post:
operationId: SetUpReverseDns
summary: Set up reverse DNS
tags:
- Reverse DNS
description: '**This endpoint allows you to set up reverse DNS.**'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
type: object
properties:
ip:
type: string
description: The IP address for which you want to set up reverse
DNS.
subdomain:
type: string
description: The subdomain that will be used to send emails from
the IP address. This should be the same as the subdomain used
to set up an authenticated domain.
domain:
type: string
description: The root, or sending, domain that will be used to send
message from the IP address.
required:
- ip
- domain
example:
ip: 192.168.1.1
subdomain: email
domain: example.com
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ReverseDns'
examples:
response:
value:
id: 123
ip: 192.168.1.2
rdns: o1.email.example.com
users: []
subdomain: email
domain: example.com
valid: true
legacy: false
a_record:
valid: true
type: a
host: o1.email.example.com
data: 192.168.1.2
get:
operationId: ListReverseDns
summary: Retrieve all reverse DNS records
tags:
- Reverse DNS
description: '**This endpoint allows you to retrieve a paginated list of all
the Reverse DNS records created by this account.**
You may include a search key by using the `ip` query string parameter. This
enables you to perform a prefix search for a given IP segment (e.g., `?ip="192."`).
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: ip
in: query
description: The IP address segment that you'd like to use in a prefix search.
schema:
type: string
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ReverseDns'
examples:
response:
value:
- id: 1
ip: 192.168.1.1
rdns: o1.email.example.com
users:
- username: [email protected]
user_id: 7
- username: [email protected]
user_id: 8
subdomain: email
domain: example.com
valid: true
legacy: false
a_record:
valid: true
type: a
host: o1.email.example.com
data: 192.168.1.1
- id: 2
ip: 192.168.1.2
rdns: o2.email.example.com
users:
- username: [email protected]
user_id: 7
- username: [email protected]
user_id: 9
subdomain: email
domain: example.com
valid: true
legacy: false
a_record:
valid: true
type: a
host: o2.email.example.com
data: 192.168.1.2
/v3/whitelabel/ips/{id}:
parameters:
- name: id
in: path
description: The ID of the reverse DNS record that you would like to retrieve.
required: true
schema:
type: string
get:
operationId: GetReverseDns
summary: Retrieve a reverse DNS record
tags:
- Reverse DNS
description: '**This endpoint allows you to retrieve a reverse DNS record.**
You can retrieve the IDs associated with all your reverse DNS records using
the "Retrieve all reverse DNS records" endpoint.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ReverseDns'
examples:
response:
value:
id: 123
ip: 192.168.1.1
rdns: o1.email.example.com
users:
- username: [email protected]
user_id: 7
subdomain: email
domain: example.com
valid: true
legacy: false
a_record:
valid: true
type: a
host: o1.email.example.com
data: 192.168.1.1
delete:
operationId: DeleteReverseDns
summary: Delete a reverse DNS record
tags:
- Reverse DNS
description: '**This endpoint allows you to delete a reverse DNS record.**
A call to this endpoint will respond with a 204 status code if the deletion
was successful.
You can retrieve the IDs associated with all your reverse DNS records using
the "Retrieve all reverse DNS records" endpoint.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'204':
description: ''
/v3/whitelabel/ips/{id}/validate:
parameters:
- name: id
in: path
description: The ID of the reverse DNS record that you would like to validate.
required: true
schema:
type: string
post:
operationId: ValidateReverseDns
summary: Validate a reverse DNS record
tags:
- Reverse DNS
description: "**This endpoint allows you to validate a reverse DNS record.**\n\
\nAlways check the `valid` property of the response\u2019s `validation_results.a_record`\
\ object. This field will indicate whether it was possible to validate the\
\ reverse DNS record. If the `validation_results.a_record.valid` is `false`,\
\ this indicates only that Twilio SendGrid could not determine the validity\
\ your reverse DNS record \u2014 it may still be valid.\n\nIf validity couldn\u2019\
t be determined, you can check the value of `validation_results.a_record.reason`\
\ to find out why.\n\nYou can retrieve the IDs associated with all your reverse\
\ DNS records using the \"Retrieve all reverse DNS records\" endpoint."
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: The ID of the reverse DNS record.
valid:
type: boolean
description: Indicates if the reverse DNS record is valid.
$ref: '#/components/schemas/Valid'
validation_results:
type: object
description: The specific results of the validation.
properties:
a_record:
type: object
properties:
valid:
type: boolean
description: Indicates if the reverse DNS record could
be validated.
$ref: '#/components/schemas/Valid1'
reason:
description: The reason the reverse DNS record could not
be validated. Is `null` if the reverse DNS record was
validated.
nullable: true
type: string
required:
- valid
- reason
required:
- id
- valid
- validation_results
examples:
response:
value:
id: 123456
valid: false
validation_results:
a_record:
valid: false
reason: 'Failed to resolve A Record at o1.ptr4283.example.com:
lookup o1.ptr4283.example.com on 192.168.0.10:53: no such
host'
'404':
description: Unexpected error in API call. See HTTP response body for details.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
description: The error messages for the failed validation.
items:
type: object
properties:
message:
type: string
description: A message describing why the reverse DNS could
not be validated.
required:
- message
required:
- errors
examples:
response:
value:
errors:
- message: Reverse DNS record not found.
'500':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
description: The error messages for the failed validation.
items:
type: object
properties:
message:
type: string
description: A message describing why the IP whitelabel
could not be validated.
required:
- message
required:
- errors
examples:
response:
value:
errors:
- message: internal error getting rDNS
components:
schemas:
ReverseDns:
title: Reverse DNS
type: object
properties:
id:
type: integer
description: The ID of the Reverse DNS.
ip:
type: string
description: The IP address that this Reverse DNS was created for.
rdns:
type: string
description: The reverse DNS record for the IP address. This points to the
Reverse DNS subdomain.
users:
type: array
description: The users who are able to send mail from the IP address.
items:
type: object
properties:
username:
type: string
description: The username of a user who can send mail from the IP
address.
user_id:
type: integer
description: The ID of a user who can send mail from the IP address.
required:
- username
- user_id
subdomain:
type: string
description: The subdomain created for this reverse DNS. This is where the
rDNS record points.
domain:
type: string
description: The root, or sending, domain.
valid:
type: boolean
description: Indicates if this is a valid Reverse DNS.
legacy:
type: boolean
description: Indicates if this Reverse DNS 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 Reverse DNS if you need to update it.
last_validation_attempt_at:
type: integer
description: A Unix epoch timestamp representing the last time of a validation
attempt.
a_record:
type: object
required:
- valid
- type
- host
- data
properties:
valid:
type: boolean
description: Indicates if the a_record is valid.
type:
type: string
description: The type of DNS record.
host:
type: string
description: This is the web address that will be mapped to the IP address.
data:
type: string
description: The IP address being set up with Reverse DNS.
required:
- id
- ip
- rdns
- users
- domain
- valid
- legacy
- a_record
example:
id: 1
ip: 192.168.1.1
rdns: o1.email.example.com
users:
- username: [email protected]
user_id: 7
- username: [email protected]
user_id: 8
subdomain: email
domain: example.com
valid: true
legacy: false
a_record:
valid: true
type: a
host: o1.email.example.com
data: 192.168.1.1
Valid:
type: boolean
enum:
- true
- false
Valid1:
type: boolean
enum:
- true
- false
responses: {}
parameters:
OnBehalfOf:
name: on-behalf-of
in: header
description: 'The `on-behalf-of` header allows you to make API calls from a
parent account on behalf of the parent''s Subusers or customer accounts. You
will use the parent account''s API key when using this header. When making
a call on behalf of a customer account, the property value should be "account-id"
followed by the customer account''s ID (e.g., `on-behalf-of: account-id <account-id>`).
When making a call on behalf of a Subuser, the property value should be the
Subuser''s username (e.g., `on-behalf-of: <subuser-username>`). See [**On
Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of)
for more information.'
required: false
schema:
type: string
PaginationCommonOffset:
name: offset
in: query
required: false
description: The number of items in the list to skip over before starting to
retrieve the items for the requested page. The default `offset` of `0` represents
the beginning of the list, i.e. the start of the first page. To request the
second page of the list, set the `offset` to the page size as determined by
`limit`. Use multiples of the page size as your `offset` to request further
consecutive pages. E.g. assume your page size is set to `10`. An `offset`
of `10` requests the second page, an `offset` of `20` requests the third page
and so on, provided there are sufficiently many items in your list.
schema:
type: integer
minimum: 0
default: 0
examples: {}
requestBodies: {}
headers: {}
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Twilio SendGrid requires you to authenticate with its APIs using
an API key. The API key must be sent as a bearer token in the Authorization
header.
tags:
- name: Reverse DNS
description: Twilio SendGrid Reverse DNS API
externalDocs:
description: Twilio SendGrid's official developer documentation.
url: https://www.twilio.com/docs/sendgrid