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: john@example.com
                      user_id: 7
                    - username: jane@example.com
                      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: john@example.com
                      user_id: 7
                    - username: jane@example2.com
                      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: john@example.com
                      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: john@example.com
          user_id: 7
        - username: jane@example.com
          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