{ "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.\n\nEmail 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.\n\nYou can use this API to:\n- Indicate to users that the address they have entered into a form is invalid.\n- Drop invalid email addresses from your database.\n- Suppress invalid email addresses from your sending to decrease your bounce rate.\n\nSee [**Email Address Validation**](https://docs.sendgrid.com/ui/managing-contacts/email-address-validation) for more information.\n\nYou 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.**\n\nNote that in a successful response the `content-type` header value matches the provided `file_type` parameter in the `PUT` request.\n\nOnce 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).\n", "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.**\n", "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" } }