openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Email Address Validation 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: Email Address Validation
  description: The Twilio SendGrid Email Address Validation API
paths:
  /v3/validations/email:
    post:
      operationId: ValidateEmail
      summary: Validate an email
      tags:
      - Email Address Validation
      description: '**This endpoint allows you to validate an email address.**'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: The email address that you want to validate.
                source:
                  type: string
                  description: A one-word classifier for where this validation originated.
              required:
              - email
              example:
                email: example@example.com
                source: signup
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    required:
                    - email
                    - verdict
                    - score
                    - local
                    - host
                    - checks
                    - ip_address
                    properties:
                      email:
                        type: string
                        description: The email being validated
                        format: email
                      verdict:
                        type: string
                        description: A generic classification of whether or not the email address is valid.
                        $ref: '#/components/schemas/Verdict'
                      score:
                        type: number
                        description: A numeric representation of the email validity.
                      local:
                        type: string
                        description: The local part of the email address.
                      host:
                        type: string
                        description: The domain of the email address.
                        format: hostname
                      suggestion:
                        type: string
                        description: A suggested correction in the event of domain name typos (e.g., gmial.com)
                      checks:
                        type: object
                        description: Granular checks for email address validity.
                        required:
                        - domain
                        - local_part
                        - additional
                        properties:
                          domain:
                            type: object
                            description: Checks on the domain portion of the email address.
                            required:
                            - has_valid_address_syntax
                            - has_mx_or_a_record
                            - is_suspected_disposable_address
                            properties:
                              has_valid_address_syntax:
                                type: boolean
                                description: Whether the email address syntax is valid.
                              has_mx_or_a_record:
                                type: boolean
                                description: 'Whether the email has appropriate DNS records to deliver a message. '
                              is_suspected_disposable_address:
                                type: boolean
                                description: Whether the domain appears to be from a disposable email address service.
                          local_part:
                            type: object
                            description: Checks on the local part of the email address.
                            required:
                            - is_suspected_role_address
                            properties:
                              is_suspected_role_address:
                                type: boolean
                                description: Whether the local part of email appears to be a role or group (e.g., hr, admin)
                          additional:
                            type: object
                            description: Additional checks on the email address.
                            required:
                            - has_known_bounces
                            - has_suspected_bounces
                            properties:
                              has_known_bounces:
                                type: boolean
                                description: Whether email sent to this address from your account has bounced.
                              has_suspected_bounces:
                                type: boolean
                                description: Whether our model predicts that the email address might bounce.
                      source:
                        type: string
                        description: The source of the validation, as per the API request.
                      ip_address:
                        type: string
                        description: The IP address associated with this email.
                required:
                - result
              examples:
                response:
                  value:
                    result:
                      email: cedric@fogowl.com
                      verdict: Valid
                      score: 0.85021
                      local: cedric
                      host: fogowl.com
                      checks:
                        domain:
                          has_valid_address_syntax: true
                          has_mx_or_a_record: true
                          is_suspected_disposable_address: false
                        local_part:
                          is_suspected_role_address: false
                        additional:
                          has_known_bounces: false
                          has_suspected_bounces: false
                      ip_address: 192.168.1.1
components:
  schemas:
    Verdict:
      type: string
      enum:
      - Valid
      - Risky
      - Invalid
  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