Email Validator: Routes
Run Commands
The entry point for email validation. Send one command per request: validate one address, up to 50, or read your history.
https://g.sendcorex.com/v1/tool/validateSame envelope as Logs and Contacts, but with exactly 1 command per request: a validation talks to real mail servers and can take a few seconds.
Errors are reported in the result of the command, and the HTTP status stays 200.
Body parameters
commandsobject[]requiredExactly 1 command.
commands[].commandstringrequiredvalidate_email,validate_emailsorlist_validations.commands[].argsobjectoptionalThe command arguments.
commands[].idstringoptionalYour own identifier for the result. Defaults to
"0".
Quick start
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/tool/validate',
{
commands: [
{
command: "validate_email",
args: {
email: "ana@acme.com"
}
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);Response
{
"type": "SUCCESS",
"results": [
{
"command": "validate_email",
"id": "0",
"type": "SUCCESS",
"took_ms": 1840,
"data": {
"email": "ana@acme.com",
"valid": true,
"checks": [
{
"check": "Format Validation",
"status": "Passed",
"details": "Valid email format"
},
{
"check": "Local Part Validation",
"status": "Passed",
"details": "Local part is RFC compliant"
},
{
"check": "Role-based Email Check",
"status": "Passed",
"details": "Not a role-based address"
},
{
"check": "No-reply Email Check",
"status": "Passed",
"details": "Not a no-reply address"
},
{
"check": "Temporary Email Check",
"status": "Passed",
"details": "Not a temporary email"
},
{
"check": "Misspelled Domain Check",
"status": "Passed",
"details": "Correct"
},
{
"check": "Spam Trap Check",
"status": "Passed",
"details": "Not a spam trap"
},
{
"check": "Provider Type",
"status": "Passed",
"details": "Corporate or custom domain"
},
{
"check": "Domain Validation",
"status": "Passed",
"details": "Domain is valid and has MX records"
},
{
"check": "Null MX Check",
"status": "Passed",
"details": "Domain accepts email"
},
{
"check": "Email Provider Detection",
"status": "Passed",
"details": "Domain is hosted on a known provider: Google Workspace",
"providerId": 1,
"providerName": "Google Workspace"
},
{
"check": "Email Deliverability",
"status": "Passed",
"details": "Mailbox exists",
"fullResponse": "250 2.1.5 OK"
},
{
"check": "Catch-all Mail Exchanger Check",
"status": "Passed",
"details": "Mail exchanger correctly rejects nonexistent addresses"
}
]
}
}
]
}Response fields
typeAlways
SUCCESSwhen the request itself was accepted.results[0].command / id / typeThe command, your id, and
SUCCESSorERROR.results[0].took_msHow long the validation took. Most addresses take 1 to 5 seconds.
results[0].dataThe command output. Only present when
typeisSUCCESS.results[0].code / messageThe error. Only present when
typeisERROR.
Authentication
Use the API key you create in the dashboard, under Developers → API Keys, with the tools:validate scope.
AuthorizationSend
Authorization: <api key>orAuthorization: Bearer <api key>.tools:validateNeeded by every command on this route.
Mailbox tokensThe webmail token does not work here. It is rejected with
WRONG_CREDENTIAL_TYPE.
Credits
1 credit per addressEach address you validate uses one validation credit. The same address twice in one command counts once.
All or nothingIf you do not have enough credits for the whole command, nothing is validated and nothing is charged (
INSUFFICIENT_CREDITS).Refund on failureIf the validation servers fail, the credits of that command are returned (
VALIDATION_FAILED).History is freelist_validationsreads what you already validated and costs nothing.
Timeouts
A validation asks the real mail server, so it is slower than the other APIs. Set your HTTP client timeout to at least 2 minutes for validate_emails.
Errors
HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.
- 400
INVALID_JSONThe body is not {"commands":[...]} or is larger than 1 MB.
- 400
INVALID_ARGSThe request has no command or more than one. This route takes exactly 1 command per request.
- 401
MISSING_AUTH_HEADERNo Authorization header was sent.
- 401
INVALID_API_KEYThe API key does not exist, was revoked or was disabled in the dashboard.
- 401
API_KEY_EXPIREDThe API key passed the expiration date set in the dashboard.
- 401
WRONG_CREDENTIAL_TYPEA mailbox token was sent. Email validation needs a dashboard API key.
- 403
IP_NOT_ALLOWEDThe request came from an IP that is not in the allowed IPs of the key.
- 403
ACCOUNT_BLOCKEDThe account is blocked.
- 403
MISSING_SCOPEThe key does not have `tools:validate`, so no command can run.
- 429
RATE_LIMITEDMore than 75 requests/s or 75 in flight for the same IP + API key. Wait the number of seconds in Retry-After.
- 503
AUTH_UNAVAILABLEAuthentication is temporarily unavailable. Try again.
- CMD
UNKNOWN_COMMANDThe command name does not exist.
- CMD
INTERNALServer error. The detail is only written to the server log.