openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Reverse DNS API
  summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
  description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.


    You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
  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: account_provisioning
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Reverse DNS
  description: Twilio SendGrid Reverse DNS API
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.**


        Always check the `valid` property of the response’s `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 — it may still be valid.


        If validity couldn’t be determined, you can check the value of `validation_results.a_record.reason` to find out why.


        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:
                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
  parameters:
    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
    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
  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.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid