SendGrid Sender Verification API

openapi: 3.2.0
info:
  title: Twilio SendGrid Verified Senders Sender Verification 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.
  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
security:
- BearerAuth: []
tags:
- name: Sender Verification
  description: Twilio SendGrid Sender Verification API
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.'
      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 — hard failure or soft failure**.


        Domains listed as hard failures will not deliver mail when used as a Sender Identity due to the domain''s DMARC policy settings.


        For 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.'
      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’s verification processes have been completed for an account**.


        This endpoint returns boolean values, `true` and `false`, for Domain Authentication, `domain_verified`, and Single Sender Verification, `sender_verified`, for the account.


        An 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:
  responses:
    VerifiedSenders403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    VerifiedSenders401:
      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
  schemas:
    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
    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
    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'
  requestBodies:
    PostPatchVerifiedSender:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerifiedSenderRequest'
  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