openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Verified Senders API
  summary: The Twilio SendGrid Verified Senders API allows you to programmatically
    manage the Sender Identities that are authorized to send email for your account.
  description: 'The Twilio SendGrid Verified Senders API allows you to programmatically
    manage the Sender Identities that are authorized to send email for your account.
    You can also manage Sender Identities in the [SendGrid application user interface](https://app.sendgrid.com/settings/sender_auth).
    See [**Single Sender Verification**](https://sendgrid.com/docs/ui/sending-email/sender-verification/)
    for more information.


    You an use this API to create new Sender Identities, retrieve a list of existing
    Sender Identities, check the status of a Sender Identity, update a Sender Identity,
    and delete a Sender Identity.


    This API offers additional operations to check for domains known to implement
    DMARC and resend verification emails to Sender Identities that have yet to complete
    the verification process.'
  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: verified_senders
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/verified_senders:
    post:
      operationId: CreateVerifiedSender
      summary: Create Verified Sender Request
      tags:
      - Sender Verification
      description: '**This endpoint allows you to create a new Sender Identify**.


        Upon successful submission of a `POST` request to this endpoint, an identity
        will be created, and a verification email will be sent to the address assigned
        to the `from_email` field. You must complete the verification process using
        the sent email to fully verify the sender.


        If you need to resend the verification email, you can do so with the Resend
        Verified Sender Request, `/resend/{id}`, endpoint.


        If you need to authenticate a domain rather than a Single Sender, see the
        [Domain Authentication API](https://docs.sendgrid.com/api-reference/domain-authentication/authenticate-a-domain).'
      requestBody:
        $ref: '#/components/requestBodies/PostPatchVerifiedSender'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedSenderResponse'
              examples:
                response:
                  value:
                    id: 1234
                    nickname: Example Orders
                    from_email: orders@example.com
                    from_name: Example Orders
                    reply_to: orders@example.com
                    reply_to_name: Example Orders
                    address: 1234 Fake St.
                    address2: PO Box 1234
                    state: CA
                    city: San Francisco
                    country: USA
                    zip: '94105'
                    verified: true
                    locked: false
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
                required:
                - errors
        '401':
          $ref: '#/components/responses/VerifiedSenders401'
        '403':
          $ref: '#/components/responses/VerifiedSenders403'
        '404':
          $ref: '#/components/responses/VerifiedSenders404'
        '500':
          $ref: '#/components/responses/VerifiedSenders500'
    get:
      operationId: ListVerifiedSender
      summary: Get All Verified Senders
      tags:
      - Sender Verification
      description: '**This endpoint allows you to retrieve all the Sender Identities
        associated with an account.**


        This endpoint will return both verified and unverified senders.


        You can limit the number of results returned using the `limit`, `lastSeenID`,
        and `id` query string parameters.


        * `limit` allows you to specify an exact number of Sender Identities to return.

        * `lastSeenID` will return senders with an ID number occuring after the passed
        in ID. In other words, the `lastSeenID` provides a starting point from which
        SendGrid will iterate to find Sender Identities associated with your account.

        * `id` will return information about only the Sender Identity passed in the
        request.'
      parameters:
      - name: limit
        in: query
        description: Specifies the number of results to be returned by the API. This
          parameter can be used to limit the results returned or in combination with
          the `lastSeenID` parameter to iterate through paginated results.
        schema:
          type: number
      - name: lastSeenID
        in: query
        description: Returns senders with an ID number occurring after the passed
          in ID. In other words, the `lastSeenID` provides a starting point from which
          SendGrid will iterate to find Sender Identities associated with your account.
        schema:
          type: number
      - name: id
        in: query
        description: Returns information about only the Sender Identity passed in
          the request.
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/VerifiedSenderResponse'
              examples:
                response:
                  value:
                    results:
                    - id: 1234
                      nickname: Example Orders
                      from_email: orders@example.com
                      from_name: Example Orders
                      reply_to: orders@example.com
                      reply_to_name: Example Orders
                      address: 1234 Fake St.
                      address2: PO Box 1234
                      state: CA
                      city: San Francisco
                      country: USA
                      zip: '94105'
                      verified: true
                      locked: false
                    - id: 1235
                      nickname: Example Support
                      from_email: support@example.com
                      from_name: Example Support
                      reply_to: support@example.com
                      reply_to_name: Example Support
                      address: 1234 Fake St.
                      address2: PO Box 1234
                      state: CA
                      city: San Francisco
                      country: USA
                      zip: '94105'
                      verified: true
                      locked: false
        '401':
          $ref: '#/components/responses/VerifiedSenders401'
        '403':
          $ref: '#/components/responses/VerifiedSenders403'
        '404':
          $ref: '#/components/responses/VerifiedSenders404'
        '500':
          $ref: '#/components/responses/VerifiedSenders500'
  /v3/verified_senders/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    patch:
      operationId: UpdateVerifiedSender
      summary: Edit Verified Sender
      tags:
      - Sender Verification
      description: '**This endpoint allows you to update an existing Sender Identity**.


        Pass the `id` assigned to a Sender Identity to this endpoint as a path parameter.
        Include any fields you wish to update in the request body in JSON format.


        You can retrieve the IDs associated with Sender Identities by passing a `GET`
        request to the Get All Verified Senders endpoint, `/verified_senders`.


        **Note:** Unlike a `PUT` request, `PATCH` allows you to update only the fields
        you wish to edit. Fields that are not passed as part of a request will remain
        unaltered.'
      requestBody:
        $ref: '#/components/requestBodies/PostPatchVerifiedSender'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedSenderResponse'
              examples:
                response:
                  value:
                    id: 1234
                    nickname: Example Orders
                    from_email: orders@example.com
                    from_name: Example Orders
                    reply_to: orders@example.com
                    reply_to_name: Example Orders
                    address: 1234 Fake St.
                    address2: PO Box 1234
                    state: CA
                    city: San Francisco
                    country: USA
                    zip: '94105'
                    verified: true
                    locked: false
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
                required:
                - errors
        '401':
          $ref: '#/components/responses/VerifiedSenders401'
        '403':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
                required:
                - errors
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
                required:
                - errors
        '500':
          $ref: '#/components/responses/VerifiedSenders500'
    delete:
      operationId: DeleteVerifiedSender
      summary: Delete Verified Sender
      tags:
      - Sender Verification
      description: '**This endpoint allows you to delete a Sender Identity**.


        Pass the `id` assigned to a Sender Identity to this endpoint to delete the
        Sender Identity from your account.


        You can retrieve the IDs associated with Sender Identities using the "Get
        All Verified Senders" endpoint.'
      responses:
        '204':
          description: ''
        '401':
          $ref: '#/components/responses/VerifiedSenders401'
        '403':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
                required:
                - errors
        '500':
          $ref: '#/components/responses/VerifiedSenders500'
  /v3/verified_senders/domains:
    get:
      operationId: ListVerifiedSenderDomain
      summary: Domain Warn List
      tags:
      - Sender Verification
      description: "**This endpoint returns a list of domains known to implement DMARC\
        \ and categorizes them by failure type \u2014 hard failure or soft failure**.\n\
        \nDomains listed as hard failures will not deliver mail when used as a [Sender\
        \ Identity](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/)\
        \ due to the domain's DMARC policy settings.\n\nFor example, using a `yahoo.com`\
        \ email address as a Sender Identity will likely result in the rejection of\
        \ your mail. For more information about DMARC, see [Everything about DMARC](https://sendgrid.com/docs/ui/sending-email/dmarc/)."
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    required:
                    - soft_failures
                    - hard_failures
                    properties:
                      soft_failures:
                        type: array
                        items:
                          type: string
                      hard_failures:
                        type: array
                        items:
                          type: string
                required:
                - results
              examples:
                response:
                  value:
                    results:
                      soft_failures:
                      - gmail.com
                      hard_failures:
                      - yahoo.com
        '401':
          $ref: '#/components/responses/VerifiedSenders401'
        '403':
          $ref: '#/components/responses/VerifiedSenders403'
        '404':
          $ref: '#/components/responses/VerifiedSenders404'
        '500':
          $ref: '#/components/responses/VerifiedSenders500'
  /v3/verified_senders/resend/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: ResendVerifiedSender
      summary: Resend Verified Sender Request
      tags:
      - Sender Verification
      description: '**This endpoint allows you to resend a verification email to a
        specified Sender Identity**.


        Passing the `id` assigned to a Sender Identity to this endpoint will resend
        a verification email to the `from_address` associated with the Sender Identity.
        This can be useful if someone loses their verification email or needs to have
        it resent for any other reason.


        You can retrieve the IDs associated with Sender Identities by passing a "Get
        All Verified Senders" endpoint.'
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
                required:
                - errors
        '401':
          $ref: '#/components/responses/VerifiedSenders401'
        '403':
          $ref: '#/components/responses/VerifiedSenders403'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
                required:
                - errors
        '500':
          $ref: '#/components/responses/VerifiedSenders500'
  /v3/verified_senders/steps_completed:
    get:
      operationId: ListVerifiedSenderStepsCompleted
      summary: Completed Steps
      tags:
      - Sender Verification
      description: "**This endpoint allows you to determine which of SendGrid\u2019\
        s verification processes have been completed for an account**.\n\nThis endpoint\
        \ returns boolean values, `true` and `false`, for [Domain Authentication](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#domain-authentication),\
        \ `domain_verified`, and [Single Sender Verification](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#single-sender-verification),\
        \ `sender_verified`, for the account.\n\nAn account may have one, both, or\
        \ neither verification steps completed. If you need to authenticate a domain\
        \ rather than a Single Sender, see the \"Authenticate a domain\" endpoint."
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      sender_verified:
                        type: boolean
                      domain_verified:
                        type: boolean
              examples:
                response:
                  value:
                    results:
                      domain_verified: true
                      sender_verified: true
        '401':
          $ref: '#/components/responses/VerifiedSenders401'
        '403':
          $ref: '#/components/responses/VerifiedSenders403'
        '404':
          $ref: '#/components/responses/VerifiedSenders404'
        '500':
          $ref: '#/components/responses/VerifiedSenders500'
  /v3/verified_senders/verify/{token}:
    parameters:
    - name: token
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: VerifySenderToken
      summary: Verify Sender Request
      tags:
      - Sender Verification
      description: '**This endpoint allows you to verify a sender requests.**


        The token is generated by SendGrid and included in a verification email delivered
        to the address that''s pending verification.'
      responses:
        '204':
          description: ''
        '401':
          $ref: '#/components/responses/VerifiedSenders401'
        '403':
          $ref: '#/components/responses/VerifiedSenders403'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        error_id:
                          type: string
                      required:
                      - message
                      - error_id
                required:
                - errors
        '500':
          $ref: '#/components/responses/VerifiedSenders500'
components:
  schemas:
    VerifiedSenderRequest:
      title: Verified Sender Request Schema
      type: object
      properties:
        nickname:
          type: string
          maxLength: 100
        from_email:
          type: string
          maxLength: 256
          format: email
        from_name:
          type: string
          maxLength: 256
        reply_to:
          type: string
          maxLength: 256
          format: email
        reply_to_name:
          type: string
          maxLength: 256
        address:
          type: string
          maxLength: 100
        address2:
          type: string
          maxLength: 100
        state:
          type: string
          maxLength: 2
        city:
          type: string
          maxLength: 150
        zip:
          type: string
          maxLength: 10
        country:
          type: string
          maxLength: 100
      required:
      - nickname
      - from_email
      - reply_to
      example:
        nickname: Orders
        from_email: orders@example.com
        from_name: Example Orders
        reply_to: orders@example.com
        reply_to_name: Example Orders
        address: 1234 Fake St
        address2: PO Box 1234
        state: CA
        city: San Francisco
        country: USA
        zip: '94105'
    VerifiedSenderResponse:
      title: Verified Sender Response Schema
      type: object
      properties:
        id:
          type: integer
        nickname:
          type: string
        from_email:
          type: string
        from_name:
          type: string
        reply_to:
          type: string
        reply_to_name:
          type: string
        address:
          type: string
        address2:
          type: string
        state:
          type: string
        city:
          type: string
        zip:
          type: string
        country:
          type: string
        verified:
          type: boolean
        locked:
          type: boolean
      example:
        id: 1234
        nickname: Example Orders
        from_email: orders@example.com
        from_name: Example Orders
        reply_to: orders@example.com
        reply_to_name: Example Orders
        address: 1234 Fake St.
        address2: PO Box 1234
        state: CA
        city: San Francisco
        country: USA
        zip: '94105'
        verified: true
        locked: false
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: An error message.
              field:
                description: When applicable, this property value will be the field
                  that generated the error.
                nullable: true
                type: string
              help:
                type: object
                description: When applicable, this property value will be helper text
                  or a link to documentation to help you troubleshoot the error.
        id:
          type: string
          description: When applicable, this property value will be an error ID.
      example:
        errors:
        - field: field_name
          message: error message
  responses:
    VerifiedSenders401:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    VerifiedSenders403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    VerifiedSenders404:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    VerifiedSenders500:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
  parameters: {}
  examples: {}
  requestBodies:
    PostPatchVerifiedSender:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerifiedSenderRequest'
  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: Sender Verification
  description: Twilio SendGrid Sender Verification API
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid