openapi: 3.1.0 security: - BearerAuth: [] info: title: Twilio SendGrid Email Address Validation API summary: '' description: 'The Twilio SendGrid Email Address Validation API provides real-time detailed information on the validity of email addresses. You can integrate this validation process into your platform''s signup form and customize the best use of email address validation for your use case. Email Address Validation is available to [Email API Pro and Premier level accounts](https://sendgrid.com/pricing) only. Prior to upgrading your account to Pro or Premier, you will not see the option to create an Email Validation API key. An Email Validation API key is separate from and in addition to your other keys, including Full Access API keys. You can use this API to: - Indicate to users that the address they have entered into a form is invalid. - Drop invalid email addresses from your database. - Suppress invalid email addresses from your sending to decrease your bounce rate. See [**Email Address Validation**](https://docs.sendgrid.com/ui/managing-contacts/email-address-validation) for more information. You can also view your Email Validation results and metrics in the Validation section of the [Twilio SendGrid application user interface](https://docs.sendgrid.com/ui/managing-contacts/email-address-validation).' 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: email_validation servers: - url: https://api.sendgrid.com description: The Twilio SendGrid v3 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 /v3/validations/email/jobs: put: operationId: ListEmailJobForVerification summary: Request a presigned URL and headers for Bulk Email Address Validation list upload. tags: - Bulk Email Address Validation description: '**This endpoint returns a presigned URL and request headers. Use this information to upload a list of email addresses for verification.** Note that in a successful response the `content-type` header value matches the provided `file_type` parameter in the `PUT` request. Once you have an `upload_uri` and the `upload_headers`, you''re ready to upload your email address list for verification. For the expected format of the email address list and a sample upload request, see the [Bulk Email Address Validation Overview page](https://www.twilio.com/docs/sendgrid/ui/managing-contacts/email-address-validation/bulk-email-address-validation-overview). ' requestBody: content: application/json: schema: type: object properties: file_type: type: string description: The format of the file you wish to upload. $ref: '#/components/schemas/FileType' required: - file_type example: file_type: csv responses: '200': description: The request was successful. The response contains the URI and headers where you will upload your email address list. content: application/json: schema: $ref: '#/components/schemas/PutValidationsEmailJobs200Response' examples: response: value: job_id: 01H793APATD899ESMY25ZNPNCF upload_uri: https://example.com/ upload_headers: - header: x-amz-server-side-encryption value: aws:kms - header: content-type value: text/csv '400': description: Bad request. Invalid or missing `file_type` or malformed request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: Error message '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: error message get: operationId: GetValidationsEmailJobs summary: This request lists all of a user's Bulk Email Validation Jobs. tags: - Bulk Email Address Validation description: '**This endpoint returns a list of all of a user''s Bulk Email Validation Jobs.**' responses: '200': description: The request was successful. The response contains a list of all of your Bulk Email Validation Jobs. content: application/json: schema: $ref: '#/components/schemas/GetValidationsEmailJobs200Response' examples: response: value: result: - id: 01HV9ZZQAFEXW18KFEPTB9YD5E status: Queued started_at: 1712954639 finished_at: 0 '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: error message '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v3/validations/email/jobs/{job_id}: parameters: - name: job_id in: path description: The ID of the Bulk Email Address Validation Job you wish to retrieve. required: true schema: type: string get: operationId: GetEmailJobForVerification summary: This request returns a single Bulk Email Validation Job. tags: - Bulk Email Address Validation description: '**This endpoint returns a specific Bulk Email Validation Job. You can use this endpoint to check on the progress of a Job.** ' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetValidationsEmailJobsJobId200Response' example: response: value: result: id: 01HV9ZZQAFEXW18KFEPTB9YD5E status: Queued segments: 0 segments_processed: 0 is_download_available: false started_at: 1712954639 finished_at: 0 errors: [] '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: errors: - message: error message '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PutValidationsEmailJobs200Response: title: Update Email Validations Jobs 200 Response type: object properties: job_id: type: string description: The unique ID of the Bulk Email Address Validation Job. upload_uri: type: string description: The URI to use for the request to upload your list of email addresses. upload_headers: type: array description: Array containing headers and header values. items: type: object properties: header: type: string description: The name of the header that must be included in the upload request. value: type: string description: The value of the header that must be included in the upload request. GetValidationsEmailJobs200Response: title: GET Validations Email Jobs 200 Response type: object properties: result: type: array description: '' items: type: object properties: id: type: string description: The unique ID of the Bulk Email Address Validation Job. status: type: string description: The status of the Bulk Email Address Validation Job. $ref: '#/components/schemas/Status' started_at: description: The ISO8601 timestamp when the Job was created. This is the time at which the upload request was sent to the `upload_uri`. type: number finished_at: description: The ISO8601 timestamp when the Job was finished. type: number GetValidationsEmailJobsJobId200Response: title: GET Validations Email Jobs job_id 200 Response type: object properties: result: type: object description: '' properties: id: type: string description: The unique ID of the Bulk Email Address Validation Job. status: type: string description: The status of the Bulk Email Address Validation Job. $ref: '#/components/schemas/Status1' segments: type: number description: The total number of segments in the Bulk Email Address Validation Job. There are 1,500 email addresses per segment. The value is `0` until the Job `status` is `Processing`. segments_processed: type: number description: The number of segments processed at the time of the request. 100 segments process in parallel at a time. is_download_available: type: boolean description: Boolean indicating whether the results CSV file is available for download. started_at: description: The ISO8601 timestamp when the Job was created. This is the time at which the upload request was sent to the `upload_uri`. type: number finished_at: description: The ISO8601 timestamp when the Job was finished. type: number errors: type: array description: Array containing error messages related to the Bulk Email Address Validation Job. Array is empty if no errors ocurred. items: type: object properties: message: type: string description: Description of the error encountered during execution of the Bulk Email Address Validation Job. ErrorResponse: title: Error type: object properties: errors: type: array items: type: object properties: message: type: string description: The message representing the error from the API. field: type: string description: The field associated with the error. help: type: object description: Helper text or docs for troubleshooting. required: - message id: type: string description: ID representing the error. example: errors: - field: field_name message: error message Verdict: type: string enum: - Valid - Risky - Invalid FileType: type: string enum: - csv - zip Status: type: string enum: - Initiated - Queued - Ready - Processing - Done - Error Status1: type: string enum: - Initiated - Queued - Ready - Processing - Done - Error responses: {} parameters: {} 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: Email Address Validation description: The Twilio SendGrid Email Address Validation API - name: Bulk Email Address Validation description: The Twilio SendGrid Bulk Email Address Validation API externalDocs: description: Twilio SendGrid's official developer documentation. url: https://www.twilio.com/docs/sendgrid