--- updatedAt: 2025-06-12T09:02:45.000Z agentTools: projectIndex: https://api-documentation.versium.com/llms.txt --- # Email Validation API **Format** Here's the format to call the Email Validation API: ![](https://files.readme.io/3aaef0269107802b85a9e8d2b5fa322823fd6f670dbe59707fada192efa7eea3-image.png)
**Data Tool** This API accepts the following data tool: | | | | ------------------- | ----------------------------------------------------------- | | **Data Tool Value** | **Description** | | emailValidation | enables to obtain a validation for the email used as input. | **Inputs - what the API uses to search** Inputs are information that the Email Validation API will use to search in the Versium REACH back end. This API service accepts a consumer first and last name, and any other known consumer contact information in [Common API Parameters](https://api-documentation.versium.com/reference/common-api-inputs-and-options). It matches your inputs with consumers in the Versium Data store, and returns consumer information, as available. | **value** | **description** | **example** | | --------- | ------------------------- | ------------------ | | email | A valid MD5 or SHA256 HEM | | \*For Hashed input details, please visit the Developer Portal on `` The API will then match your inputs with consumers in the Versium Data store, and returns business information, as available. **Optional Parameters** At present, the Email Validation API accepts the following optional parameters. {`


name	description	value type	possible values	notes
output[]	Whether to include an alternate, valid email, in the output response, if the input email is invalid.	string	email_validation_alternate
rcfg_exlude_domains[]	A list of domains to not return alternate emails from.	string - an email provider domain	aol.com, http://yahoo.com	Like output[], this param uses bracket syntax, so a GET request would look like: rcfg_exlude_domains[]=http://aol.com &rcfg_exlude_domains[]=http://yahoo.com Only applies when email_validation_alternate is passed as an output[]
rcfg_snake_case	A boolean to tell the Versium API to return key names in snake case, instead of upper case with spaces.	boolean	1	Inside the “results” array: “Email Address” → email_address “Is Input Email Valid” → is_input_email_valid

`} **Optional search params** - use with output\[]=email\_validation\_alternate These additional search parameters will help REACH find an alternative valid email if the input email address is invalid. | **name** | **description** | **example** | | ---------- | ------------------------------------------------------- | ------------------ | | first | A person’s first name | John | | last | A person’s last name | Doe | | address | A house/building number and street | 123 Main St | | address\_2 | The unit # of an address | Apt 12 or Unit 510 | | city | A city name | Seattle | | state | A US state or Canadian province two letter abbreviation | WA or BC | | zip | A 5 digit US ZIP code or Canadian Postal code | 98052 or V6Y-1H3 | | country | A 2 digit country code - only US is supported | US | | phone | A valid 10 digit North American phone number | 2061235555 | ## Example queries 1. Validate an email only: 2. `emailValidation?email=[jdoe@versium.com](mailto:jdoe@versium.com)` 3. Validate a HEM: 4. `emailValidation?email=42a35e2648d4e1782cc3d1357d73bddd` 5. Validate an email and return an alternate email if the input one is invalid: 6. `emailValidation?output\[\]=email\_validation\_alternate&email=[jdoe@versium.com](mailto:jdoe@versium.com)` 7. Validate an email, return an alternate email if the input one is invalid, but don’t return any [aol.com](http://aol.com/) or `` alternate emails 8. `emailValidation?output\[\]=email\_validation\_alternate&email=[jdoe@versium.com](mailto:jdoe@versium.com)&rcfg\_exclude\_domains\[\]= &rcfg\_exclude\_domains\[\]=` ## Response Structure The api only supports returning json. #### Successful response structure ```json json { "versium": { "version":"2.0", "match_counts":{}, "num_matches":0, "num_results":0, "query_id":"48f9238a-ba98-4c45-97df-74f405c97527", "query_time":7.340619087219238, "results":[{}], "input_query":{} } } ```
#### Structure of record in “results” Unless an error occurs, the email validation will always return the following fields, as part of an object, inside the “results” array: {`

name	value type	description	example
Email Address	string	The input “email” value if it is valid.	jdoe@versium.com
Is Input Email Valid	boolean	A boolean indicating whether the input email is valid.	true
Is Alternate Email	boolean	A boolean indicating whether the value in the “Email Address” field is the original, input email, or an alternate, valid email supplied by Versium. This field only is only returned when `output[]=email_validation_alternate` is pased.	false
Email Validation Status	string	The primary validation status of the input email address. The possible values are: invalid valid unknown spamtrap catch-all abuse do_not_mail	spamtrap
Email Validation Sub-status	string	A secondary, more descriptive validation status: invalid valid catch_all timeout_exceeded failed_syntax_check global_suppression no_dns_entries mailbox_not_found mailbox_quota_exceeded does_not_accept_mail toxic possible_trap exception_occurred disposable alias greylisted mail_server_temporary_error mail_server_did_not_respond forcible_disconnect failed_smtp_connection role_based unroutable_ip_address domain_cant_receive_emails	failed_syntax_check

`} #### Status descriptions * **invalid** - emails were determined to be invalid, please delete them from your mailing list. * **valid** - emails were determined to be valid. * **unknown** - emails were not validated for one reason or another. * **spamtrap** - emails are believed to be spamtraps and should not be mailed. * **catch-all** - emails are impossible to validate without sending a real email and waiting for a bounce. * **abuse** - emails are of people who are known to click the abuse links in emails, therefore abusers or complainers. * **do\_not\_mail** - emails are of companies, role-based, or people you just want to avoid emailing to. #### Sub-status descriptions * **timeout\_exceeded (Unknown)** - These emails belong to a mail server that is responding extremely slow. * **failed\_syntax\_check (Invalid)** - Emails that do not meet RFC syntax protocols * **global\_suppression (do\_not\_mail)** - These emails are found in many popular **global suppression lists** (GSL). * **no\_dns\_entries (Invalid)**- These emails are valid in syntax, but the domain doesn't have any records in DNS or have incomplete DNS Records. * **mailbox\_not\_found (Invalid)** - These emails addresses are valid in syntax, but do not exist. * **mailbox\_quota\_exceeded (Invalid)** - These emails exceeded their space quota and are not accepting emails. * **does\_not\_accept\_mail (Invalid)** - These domains only send mail and don't accept it. * **toxic (do\_not\_email)** - These email addresses are known to be abuse, spam, or bot created emails. * **possible\_trap (do\_not\_email)** - These are emails of commonly misspelled popular domains. * **exception\_occurred (unknown)** - These emails caused an exception when validating. * **disposable (do\_not\_email)** - These are temporary emails created for the sole purpose to sign up to websites without giving their real email address. These emails are short lived from 15 minutes to around 6 months. There is only 2 values (True and False). If you have valid emails with this flag set to TRUE, you shouldn't email them. * **alias (Valid)** - These emails addresses act as forwarders/aliases and are not real inboxes. * **greylisted (Unknown)** - Emails where we are temporarily unable to validate them. * **mail\_server\_temporary\_error (Unknown)** - These emails belong to a mail server that is returning a temporary error. * **mail\_server\_did\_not\_respond (Unknown)** - These emails belong to a mail server that is not responding to mail commands. * **forcible\_disconnect (Unknown)** - These emails belong to a mail server that disconnects immediately upon connecting. * **failed\_smtp\_connection (Unknown)** - These emails belong to a mail server that won't allow an SMTP connection. * **role\_based (do\_not\_email)** - These emails belong to a position or a group of people, like sales@ info@ and contact\@. * **unroutable\_ip\_address (Invalid)** - These emails domains point to an un-routable IP address, these are marked invalid. * **domain\_cant\_receive\_emails** - The domain cannot received any email. #### Successful response example ```json { "versium": { "version":"2.0", "match\_counts":{ "email\_validation":1, }, "num\_matches":1, "num\_results":1, "query\_id":"48f9238a-ba98-4c45-97df-74f405c97527", "query\_time":7.340619087219238, "results":\[ { "Email Address": "[jdoe@versium.com](mailto:jdoe@versium.com)", "Is Input Email Valid": true, "Email Validation Status": "valid", "Email Validation Sub-status": "valid", } \], "input\_query":{ "email":"[jdoe@versium.com](mailto:jdoe@versium.com)" } } } ```
#### Successful response example when using output\[]=email\_validation\_alternate ```json { "versium": { "version": "2.0", "match\_counts": { "email\_validation": 1, "email\_validation\_alternate": 1, }, "num\_matches": 1, "num\_results": 1, "query\_id": "48f9238a-ba98-4c45-97df-74f405c97527", "query\_time": 7.340619087219238, "results": \[ { "Email Address": "[jdoe@gmail.com](mailto:jdoe@gmail.com)", "Is Input Email Valid": false, "Is Alternate Email": true, "Email Validation Status": "spamtrap", "Email Validation Sub-status": "possible\_trap", } \], "input\_query": { "email": "[jdoe@versium.com](mailto:jdoe@versium.com)" } } } ```
#### Error responses When an error occurs, the response object will contain an “errors” property, which array of strings. ```json { "versium": { "version":"2.0", "match\_counts":{}, "num\_matches":0, "num\_results":0, "query\_id":"48f9238a-ba98-4c45-97df-74f405c97527", "query\_time":7.340619087219238, "results":\[{}\], "input\_query":{}, "errors": \[\] } } ```