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.

POSThttps://g.sendcorex.com/v1/tool/validate
i

Same 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.

i

Errors are reported in the result of the command, and the HTTP status stays 200.

Body parameters

  • commandsobject[]required

    Exactly 1 command.

  • commands[].commandstringrequired

    validate_email, validate_emails or list_validations.

  • commands[].argsobjectoptional

    The command arguments.

  • commands[].idstringoptional

    Your 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

  • type

    Always SUCCESS when the request itself was accepted.

  • results[0].command / id / type

    The command, your id, and SUCCESS or ERROR.

  • results[0].took_ms

    How long the validation took. Most addresses take 1 to 5 seconds.

  • results[0].data

    The command output. Only present when type is SUCCESS.

  • results[0].code / message

    The error. Only present when type is ERROR.

Authentication

Use the API key you create in the dashboard, under Developers → API Keys, with the tools:validate scope.

  • Authorization

    Send Authorization: <api key> or Authorization: Bearer <api key>.

  • tools:validate

    Needed by every command on this route.

  • Mailbox tokens

    The webmail token does not work here. It is rejected with WRONG_CREDENTIAL_TYPE.

Credits

  • 1 credit per address

    Each address you validate uses one validation credit. The same address twice in one command counts once.

  • All or nothing

    If you do not have enough credits for the whole command, nothing is validated and nothing is charged (INSUFFICIENT_CREDITS).

  • Refund on failure

    If the validation servers fail, the credits of that command are returned (VALIDATION_FAILED).

  • History is free

    list_validations reads 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.

  • 400INVALID_JSON

    The body is not {"commands":[...]} or is larger than 1 MB.

  • 400INVALID_ARGS

    The request has no command or more than one. This route takes exactly 1 command per request.

  • 401MISSING_AUTH_HEADER

    No Authorization header was sent.

  • 401INVALID_API_KEY

    The API key does not exist, was revoked or was disabled in the dashboard.

  • 401API_KEY_EXPIRED

    The API key passed the expiration date set in the dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    A mailbox token was sent. Email validation needs a dashboard API key.

  • 403IP_NOT_ALLOWED

    The request came from an IP that is not in the allowed IPs of the key.

  • 403ACCOUNT_BLOCKED

    The account is blocked.

  • 403MISSING_SCOPE

    The key does not have `tools:validate`, so no command can run.

  • 429RATE_LIMITED

    More than 75 requests/s or 75 in flight for the same IP + API key. Wait the number of seconds in Retry-After.

  • 503AUTH_UNAVAILABLE

    Authentication is temporarily unavailable. Try again.

  • CMDUNKNOWN_COMMAND

    The command name does not exist.

  • CMDINTERNAL

    Server error. The detail is only written to the server log.