openapi: 3.0.1 info: title: Validation API description: The Validation API allows users to validate on or more email addresses. version: '1.0' servers: - url: https://api.touchbasepro.com/validate paths: /ValidateEmailList: post: tags: - validation summary: ValidateEmailList description: "Validate a list of email addresses. On a successful submission, an **RequestId** for the email validation job is returned. Please use the [GetListValidationStatus](getlistvalidationstatus) to verify the job is complete, then use [DownloadValidationResult](get-downloadvalidationresult) to download the results.\n\nIf webhook url is provided as **X-TBP-Webhook** header value, data similar to [GetListValidationStatus](getlistvalidationstatus) response will be posted back to specified url. Part of posted-back data is 'ReportId' value which can be used to fetch complete report by calling [DownloadValidationResult](get-downloadvalidationresult).\n\nTo verify multiple email addresses in single request, the request body should contain one email address per line." operationId: post-validateemaillist parameters: - name: Authorization in: header description: 'The authorization token. The token will be in the format "Bearer API_KEY". For example: "Authorization: Bearer 123456789". Please include the space between "Bearer" and "API_KEY".' required: true schema: enum: - Bearer API_KEY type: string default: Bearer API_KEY - name: X-TBP-Webhook in: header description: 'If a valid webhook URL is included, the Validation stats will be posted back to his URL (content similar to result of [GetListValidationStatus](getlistvalidationstatus) call, when job status is ''completed'')' schema: enum: - https://tbpelv.requestcatcher.com type: string default: https://tbpelv.requestcatcher.com requestBody: description: Plain-text list of email addresses to validate (one per row). content: text/csv: schema: $ref: '#/components/schemas/Body' example: email1@gmail.com email2@outlook.com email3@mail.com responses: '200': description: "Validation request accepted. Returned are:\n1. *RequestId* (int) - the id number of the batch job processing the validation request\n2. *IsSuccessful* (bool) - the status indicator\n3. *Message* (string) - text message (in case of an error)" content: application/json: schema: $ref: '#/components/schemas/ValidateEmailListResponse' example: RequestId: 123 IsSuccessful: true Message: '400': description: An invalid or incomplete request. Please check all information is formatted correctly and try again. content: application/json: example: status: 400 message: Webhook url is not valid. '401': description: The API key is invalid. Please verify it is correct and try again. content: application/json: example: status: 401 message: API key is invalid. '403': description: Your account has been suspended. Please check with your account representative for more information. content: application/json: example: status: 403 message: Your account has been suspended! Please check with your account representative for more information. '405': description: There's not enough credits on your account content: application/json: example: status: 405 message: There's not enough credits on your account! '429': description: The number of API calls has been exceeded. The return will include the number of seconds (represented by (number of seconds) in the example) until the API call can be tried again. content: application/json: example: status: 429 message: 'Rate limit is exceeded. Try again in {number of seconds} seconds.' '500': description: Some error occurred in the processing request. Please try it again at a later time. content: application/json: example: status: 500 message: "An internal error has occurred. We have been notified about it and\nwill restore service functionality as soon as possible." /ValidateEmailAddress: get: tags: - validation summary: ValidateEmailAddress description: "Validates a single email address. This API analyzes the email address and returns information on the quality of the address. The information returned includes the emails value (aka - how likely is it to belong to a person), what role it plays, and other factors that help the user determine if the email is useful as a contact or should be passed over for more valuable targets.\n\nValidating an email address helps the user verify that the address is to a real person, detect possible errors, and the level of \"quality\" of the email address (for example - steve.rogers@avengers.com is a better email address than abc123@random.com)." operationId: get-validateemailaddress parameters: - name: email in: query description: 'The email address to be validated, as a URL-encoded string.' required: true schema: enum: - name@mail.com type: string default: name@mail.com - name: Authorization in: header description: 'The authorization token. The token will be in the format "Bearer API_KEY". For example: "Authorization: Bearer 123456789". Please include the space between "Bearer" and "API_KEY".' required: true schema: enum: - Bearer API_KEY type: string default: Bearer API_KEY - name: X-TBP-Webhook in: header description: The Webhook URL schema: type: string responses: '200': description: "Returns an application/json object in the response body. The fields return include:\n\n1. *Result* (string) - The verification result. Values include: \n* deliverable \n* undeliverable\n* risky\n* unknown\n2. *Reason* (string) - The reason for the result. Possible reasons are:\n* invalid_email - Specified email is not a valid email address syntax\n* invalid_domain - Domain for email does not exist\n* rejected_email - Email address was rejected by the SMTP server, email address does not exist\n* accepted_email - Email address was accepted by the SMTP server\n* low_quality - Email address has quality issues that may make it a risky or low-value address\n* low_deliverability - Email address appears to be deliverable, but deliverability cannot be guaranteed\n* no_connect - Could not connect to SMTP server\n* timeout - SMTP session timed out\n* invalid_smtp - SMTP server returned an unexpected/invalid response\n* unavailable_smtp - SMTP server was unavailable to process our request\n* unexpected_error - An unexpected error has occurred\n3. *IsRole* (boolean) - true if the email address is a role address (postmaster@example.com, support@example.com, etc)\n4. *IsFree* (boolean) - true if the email address uses a free email service like gmail.com or yahoo.com.\n5. *IsDisposable* (boolean) - true if the email address uses a disposable domain like trashmail.com or mailinator.com.\n6. *AcceptAll* (boolean) - true if the email was accepted, but the domain appears to accept all emails addressed to that domain.\n7. *DidYouMean* (string) - Returns a suggested email if a possible spelling error was detected. (bill.lumbergh@gamil.com -> bill.lumbergh@gmail.com)\n8. *QualityScore* (float) - A quality score of the provided email address ranging between 0 (no quality) and 1 (perfect quality)\n9. *Email* (string) - Returns a normalized version of the provided email address. (BoB@example.com -> bob@example.com)\n10. *User* (string) - The user (a.k.a local part) of the provided email address. (bob@example.com -> bob)\n11. *Domain* (string) - The domain of the provided email address. (bob@example.com -> example.com)\n12. *IsSuccess* (boolean) - true if the API request was successful (i.e., no authentication or unexpected errors occurred)" content: application/json: schema: $ref: '#/components/schemas/ValidateEmailResponse' example: Result: risky Reason: low_deliverability IsRole: false IsFree: false IsDisposable: false AcceptAll: true DidYouMean: QualityScore: 0.71 Email: atom.ant@touchbasepro.com User: atom.ant Domain: touchbasepro.com IsSuccess: true Message: '400': description: The request was not properly formatted. The email address must be URL encoded. content: text/html: example: Email address was not valid. application/json: { } '401': description: The API key is invalid. Please verify it is correct and try again. content: application/json: example: status: 401 message: API key is invalid. text/html: { } '403': description: Your account has been suspended! Please check with your account representative for more information. content: application/json: example: status: 403 message: Your account has been suspended! Please check with your account representative for more information. text/html: { } '405': description: There is not enough credits on your account content: application/json: example: status: 405 message: There's not enough credits on your account! text/html: { } '429': description: The number of API calls has been exceeded. The return will include the number of seconds (represented by (number of seconds) in the example) until the API call can be tried again. content: application/json: example: status: 429 message: 'Rate limit is exceeded. Try again in {number of seconds} seconds.' text/html: { } '500': description: Some error occurred in the processing request. Please try it again at a later time. content: application/json: example: status: 500 message: "An internal error has occurred. We have been notified about it and\nwill restore service functionality as soon as possible." text/html: { } /DownloadValidationResult: get: tags: - validation summary: DownloadValidationResult description: "When a [ValidateEmailList](post-validateemaillist) request has been submitted, it returned an RequestId value.\nIf webhook URL was provided, when processing is completed, to provided URL result will be submitted, part of which is **ReportId** value. If no webhook URL is provided, [GetListValidationStatus](getlistvalidationstatus) is to be called, until returned job status is set to 'completed', at which point **ReportId** value is returned, along with other information.\nCalling DownloadValidationResult with this ReportId returns a csv file with detailed report." operationId: get-downloadvalidationresult parameters: - name: id in: query description: Report ID to fetch results for required: true schema: type: string - name: Authorization in: header description: 'The authorization token. The token will be in the format "Bearer API_KEY". For example: "Authorization: Bearer 123456789". Please include the space between "Bearer" and "API_KEY".' required: true schema: enum: - Bearer API_KEY type: string default: Bearer API_KEY responses: '200': description: "Returns a CSV file with the results of the batch job. The fields included are: \n\n1. *result* (string) - The verification result. Values include: \n* deliverable \n* undeliverable\n* risky\n* unknown\n2. *reason* (string) - The reason for the result. Possible reasons are:\n* invalid_email - Specified email is not a valid email address syntax\n* invalid_domain - Domain for email does not exist\n* rejected_email - Email address was rejected by the SMTP server, email address does not exist\n* accepted_email - Email address was accepted by the SMTP server\n* low_quality - Email address has quality issues that may make it a risky or low-value address\n* low_deliverability - Email address appears to be deliverable, but deliverability cannot be guaranteed\n* no_connect - Could not connect to SMTP server\n* timeout - SMTP session timed out\n* invalid_smtp - SMTP server returned an unexpected/invalid response\n* unavailable_smtp - SMTP server was unavailable to process our request\n* unexpected_error - An unexpected error has occurred\n3. *role* (boolean) - true if the email address is a role address (postmaster@example.com, support@example.com, etc)\n4. *free* (boolean) - true if the email address uses a free email service like gmail.com or yahoo.com.\n5. *disposable* (boolean) - true if the email address uses a disposable domain like trashmail.com or mailinator.com.\n6. *accept_all* (boolean) - true if the email was accepted, but the domain appears to accept all emails addressed to that domain.\n7. *did_you_mean* (string) - Returns a suggested email if a possible spelling error was detected. (bill.lumbergh@gamil.com -> bill.lumbergh@gmail.com)\n8. *QualityScore* (float) - A quality score of the provided email address ranging between 0 (no quality) and 1 (perfect quality)9. email string - Returns a normalized version of the provided email address. (BoB@example.com -> bob@example.com)\n10. *user* (string) - The user (a.k.a local part) of the provided email address. (bob@example.com -> bob)\n11. *domain* (string) - The domain of the provided email address. (bob@example.com -> example.com)\n12. *success* (boolean) - true if the API request was successful (i.e., no authentication or unexpected errors occurred)" headers: Content-disposition: description: A file is attached to the response. schema: type: string Content-type: description: The file attachment is a text file. schema: type: string content: text/html: example: "200 OK \nContent-Type: text/plain\nContent-Disposition: attachment; filename=\"ValidationResult.csv\"" application/json: { } '401': description: The API key is invalid. Please verify it is correct and try again. content: application/json: example: status: 400 message: API key is invalid. text/html: { } '403': description: There is not enough credits on your account or your account has been suspended. Please check with your account representative for more information. content: application/json: example: status: 403 message: Not enough credits in this account. text/html: { } '429': description: The number of API calls has been exceeded. The return will include the number of seconds (represented by (number of seconds) in the example) until the API call can be tried again. content: application/json: example: status: 429 message: 'Rate limit is exceeded. Try again in {number of seconds} seconds.' text/html: { } '500': description: Some error occurred in the processing request. Please try it again at a later time. content: application/json: example: status: 500 message: "An internal error has occurred. We have been notified about it and\nwill restore service functionality as soon as possible." text/html: { } /balance: get: tags: - account summary: CreditBalance description: By calling this method you can retrieve your credit balance for the making Validation requests. operationId: balance parameters: - name: Authorization in: header description: 'The authorization token. The token will be in the format "Bearer API_KEY". For example: "Authorization: Bearer 123456789". Please include the space between "Bearer" and "API_KEY".' required: true schema: enum: - Bearer API_KEY type: string default: Bearer API_KEY responses: '200': description: Call succeeded content: application/json: example: CreditCount: 100 '400': description: The submitted request was improperly formatted. Please verify the request and try again. content: application/json: example: status: 400 message: The request was not properly formatted. '401': description: The API key is invalid. Please verify it is correct and try again. content: application/json: example: status: 401 message: API key is invalid. '403': description: There is not enough credits on your account or your account has been suspended. Please check with your account representative for more information. content: application/json: example: status: 403 message: Not enough credits in this account. '429': description: The number of API calls has been exceeded. The return will include the number of seconds (represented by (number of seconds) in the example) until the API call can be tried again. content: application/json: example: status: 429 message: 'Rate limit is exceeded. Try again in {number of seconds} seconds.' /GetListValidationStatus: get: tags: - validation summary: GetListValidationStatus description: 'Returns email list validation status, and upon successful completion other useful statistics.' operationId: getlistvalidationstatus parameters: - name: RequestId in: query description: RequestId value received as response of list validation API call required: true schema: type: integer - name: Authorization in: header description: 'The authorization token. The token will be in the format "Bearer API_KEY". For example: "Authorization: Bearer 123456789". Please include the space between "Bearer" and "API_KEY".' required: true schema: enum: - Bearer API_KEY type: string default: Bearer API_KEY responses: '200': description: "Returns the current status of the ValidateEmailList request. \n\nBased on processing status of the request,, different information is provided.\n\nWhen processing status is \"starting\", the following information is provided:\n\n* *RequestId* (integer) - The identifier for this ValidateEmailList request.\n* *Status* (string) - Status of the ValidateEmailList request.\n* *IsSuccessful* (boolean) - Indicator of success of current API call.\n* *Message* (string) - Additional information in case of failed API call.\n\n\nWhen processing status is \"processing\", the following information is provided:\n\n* *RequestId* (integer) - The identifier for this ValidateEmailList request.\n* *Status* (string) - Status of the ValidateEmailList request.\n* *IsSuccessful* (boolean) - Indicator of success of current API call.\n* *Message* (string) - Additional information in case of failed API call.\n* *TotalAddresses* (integer) - Total number of email addresses sent for validation.\n* *TotalDeliverable* (integer) - How many email addresses can be delivered to.\n* *TotalUndeliverable* (integer) - How many email addresses can not be delivered to.\n* *TotalRisky* (integer) - Number of email addresses with quality issues that may make it a risky or low-value address.\n* *TotalUnknown* (integer) - Total number of email addresses with unknown validation status.\n* *TotalUnprocessed* (integer) - Total number of unprocessed email addresses.\n\n\nWhen processing status is \"completed\", the following information is provided:\n\n* *RequestId* (integer) - The identifier for this ValidateEmailList request.\n* *Name* (string) - The name of the validation list batch.\n* *ReportId* (string) - The identifier of report, that is to be provided as input argument to [DownloadValidationResult](get-downloadvalidationresult) api call, when complete report is to be downloaded.\n* *Date* (date) - Processing date.\n* *ErrorMessage* (string) - Error message returned for email list sent for validation.\n* *Status* (string) - Status of the ValidateEmailList request.\n* *TotalAddresses* (integer) - Total number of email addresses sent for validation.\n* *TotalDeliverable* (integer) - How many email addresses can be delivered to.\n* *TotalUndeliverable* (integer) - How many email addresses can not be delivered to.\n* *TotalRisky* (integer) - Number of email addresses with quality issues that may make it a risky or low-value address.\n* *TotalUnknown* (integer) - Total number of email addresses with unknown validation status.\n* *QualityScore* (float) - Average quality score for email list sent for validation.\n* *Duration* (integer) - Time taken to validate list of email addresses sent (in seconds).\n* *Message* (string) - Additional information in case of failed API call.\n* *IsSuccessful* (boolean) - Indicator of success of current API call.\n\n\nWhen processing status is \"failed\", the following information is provided:\n\n* *RequestId* (integer) - The identifier for this ValidateEmailList request.\n* *Status* (string) - Status of the ValidateEmailList request.\n* *IsSuccessful* (boolean) - Indicator of success of current API call.\n* *Message* (string) - Additional information in case of failed API call.\n* *Name* (string) - The name of the validation list batch.\n* *Date* (date) - Processing date.\n* *ErrorMessage* (string) - Error message returned for email list sent for validation.\n* *Duration* (integer) - Time taken to validate list of email addresses sent (in seconds)." content: application/json: schema: $ref: '#/components/schemas/ValidateEmailListStarting' example: RequestId: 123 Status: failed IsSuccessful: true Message: Name: Batch API Process - 01-01-2019-00-00-00 Date: '2019-01-01T12:00:00.0000000+00:00' ErrorMessage: Error description... Duration: 10 '401': description: The API key is invalid. Please verify it is correct and try again. content: application/json: example: status: 401 message: API key is invalid. '403': description: There is not enough credits on your account or your account has been suspended. Please check with your account representative for more information. content: application/json: example: status: 403 message: Not enough credits in this account. '429': description: The number of API calls has been exceeded. The return will include the number of seconds (represented by (number of seconds) in the example) until the API call can be tried again. content: application/json: example: status: 429 message: 'Rate limit is exceeded. Try again in {number of seconds} seconds.' '500': description: Some error occurred in the processing request. Please try it again at a later time. content: application/json: example: status: 500 message: "An internal error has occurred. We have been notified about it and\nwill restore service functionality as soon as possible." components: schemas: ValidateEmailListPostRequest: example: "email1@gmail.com\nemail2@outlook.com\nemail3@mail.com" ValidateEmailResponse: type: object properties: Result: type: string Reason: type: string IsRole: type: boolean IsFree: type: boolean IsDisposable: type: boolean AcceptAll: type: boolean DidYouMean: type: string QualityScore: type: number Email: type: string User: type: string Domain: type: string IsSuccess: type: boolean Message: type: string ValidateEmailListResponse: type: object properties: RequestId: type: integer IsSuccessful: type: boolean Message: type: string Body: example: "email1@gmail.com \nemail2@outlook.com\nemail3@mail.com" ValidateEmailListStarting: type: object properties: RequestId: type: integer Status: type: string IsSuccessful: type: boolean Message: type: string ValidateEmailListProgress: type: object properties: RequestId: type: integer Status: type: string IsSuccessful: type: boolean Message: type: string TotalAddresses: type: integer TotalDeliverable: type: integer TotalUndeliverable: type: integer TotalRisky: type: integer TotalUnknown: type: integer TotalUnprocessed: type: integer ValidateEmailListSuccess: type: object properties: RequestId: type: integer Name: type: string ReportId: type: string Date: type: string ErrorMessage: type: string Status: type: string TotalAddresses: type: integer TotalDeliverable: type: integer TotalUndeliverable: type: integer TotalRisky: type: integer TotalUnknown: type: integer QualityScore: type: number Duration: type: integer Message: type: string IsSuccessful: type: boolean ValidateEmailListFailure: type: object properties: RequestId: type: integer Name: type: string Status: type: string IsSuccessful: type: boolean Message: type: string TotalAddresses: type: integer TotalDeliverable: type: integer TotalUndeliverable: type: integer TotalRisky: type: integer TotalUnknown: type: integer TotalUnprocessed: type: integer